Installing MPF on Linux

As part of our automated build process, we build and test MPF and MPF-MC against Ubuntu 16.04 & 18.04 & 20.04 and Debian Stretch & Buster. MPF 0.54 supports Python 3.5 to 3.7. MPF 0.55 supports Python 3.6 to 3.9.

Installing MPF Using Our Installer

Download the MPF Debian Installer (which is used for all of these) from

Unzip it, and from a terminal run chmod +x install && sudo ./install from the folder you unzipped the files to. If you are using a P-Roc or P3-Roc also run chmod +x install-proc && ./install-proc (skip for other platforms). Consult the README for more information.

Download & run the “Demo Man” example game

Now that you have MPF installed, you probably want to see it in action. The easiest way to do that is to download a bundle of MPF examples and run our “Demo Man” example game. To do that, follow the instructions in the How to run “Demo Man”, an MPF example game guide.

There’s another example project you can also check out if you want called the “MC Demo” (for media controller demo) that lets you step through a bunch of example display things (slides, widgets, sounds, videos, etc). Instructions for running the MC Demo are here.

Running MPF

See the How to start MPF and run your game for details and command-line options.

Keeping MPF up-to-date

To upgrade MPF just re-run the installer which will make sure that you will also get updated dependencies:

sudo ./install

Alternatively, since MPF is a work-in-progress, you can use the pip command to update your MPF installation.

To to this, run the following:

pip3 install pip setuptools --upgrade
pip3 install mpf[all] mpf-mc --upgrade

This will cause pip to contact PyPI to see if there’s a newer version of the MPF MC (and any of its requirements, like MPF). If newer versions are found, it will download and install them.


If you are upgrading from MPF 0.33 to 0.50 you will need to manually perform several migration steps to modify your configuration files or they will not work in MPF 0.50. Please refer to Migrating from config version 4 to 5 of MPF for step-by-step instructions.

To install the latest dev release (not generally recommended) which allows you to try bleeding-edge features run:

pip3 install mpf[all] mpf-mc --pre --upgrade

To downgrade (or install a specific release x.yy.z) run:

pip3 install mpf[all]==x.yy.z
pip3 install mpf-mc==x.yy.z

Uninstalling MPF

To remove MPF either because it is no longer needed or to perform a clean install run:

sudo pip3 uninstall mpf-mc mpf

Specific Hardware Devices

We got some write-ups for specific hardware platforms. They follow the general linux installation schema but also cover some details about that hardware.

Specific Linux Distributions

Specifics about certain linux distributions.

What if it did not work?

In the following we list some common problems and solutions. If you got another problem please ask in our MPF User Forum.

YAML error on first start

You might see this error on startup when installing/upgrading to 0.55+/dev from an older version:

pkg_resources.VersionConflict: (ruamel.yaml 0.15.37 (c:\users\robert\appdata\local\programs\python\python36\lib\site-packages), Requirement.parse('ruamel.yaml<0.11,>=0.10')

What happened? You probably got incompatible versions of MPF, MPF-MC and/or the MPF-Monitor installed. We used to install ruamel 0.11 and switched to 0.15 in MPF 0.53+. MPF cannot start with two yaml libraries. To fix this check your versions pip3 list and check mpf, mpf-mc and mpf-monitor. Remove the wrong version and install the right one. All versions need to match (for instance all 0.55+ or all dev).

The following command will remove all three and install the latest release:

pip3 uninstall mpf mpf-mc mpf-monitor
pip3 install mpf mpf-mc mpf-monitor