Skip to content

Guide to MPF 0.57 ("dev" branch needed for Neuron Controllers)

Last updated September 20, 2023

This page explains how to install and configure the "dev" branch of MPF, which is needed to use MPF with your FAST Neuron Controller. The dev branch is the pre-release version of MPF, current version (The "stable" branch of MPF is 0.56.x, but it does not support Neuron Controllers.)

Here's the high level overview of what you need to do:

  1. (Optional) install a new version of Python, up through 3.11.5. (MPF 0.57 requires a minimum of Python 3.8.)
  2. Install MPF 0.57 via pip.
  3. Update your config files for MPF 0.57.
  4. Try MPF Monitor 0.57
  5. Understand that the MPF-MC will not work yet.
  6. Share bugs via Slack or GitHub.

1. Install the latest version of Python (optional)

The existing version of MPF (0.56) only works with Python up to version 3.9. MPF 0.57 adds support for 3.10 and 3.11 (and drops 3.7).

You don't have to update your version of Python if you don't want to, but if you're starting from scratch, you might as well install the latest version of Python. (If you're using a Mac, you can install Python 3.11 via Homebrew.)

2. Install MPF v0.57 via pip

Installing the dev branch of MPF is similar to installing the stable branch, except you add the --pre flag to the pip command. (This tells pip to install the pre-release version of MPF.)

pip install mpf --pre

Note that if you have multiple versions of Python installed, you can put the version of Python you want to use in the pip command. For example, to force the Python 3.11 version of pip, you'd run:

pip3.11 install mpf --pre

Keeping MPF 0.57 up to date

Since MPF 0.57 is a pre-release version, it's being updated frequently. You'll want to update frequently as well. You can see the most recent MPF 0.57 dev release here. (This is a link to the MPF package on PyPI, which is where that "pip" app installs from.)

Then you can check the version of MPF you have installed by running mpf --version:

> mpf --version
Mission Pinball Framework v0.57.0.dev8

You can update to the latest dev version at any time by adding --upgrade to the pip command you used to install MPF:

> mpf --version
Mission Pinball Framework v0.57.0.dev6

> pip3 install mpf --pre --upgrade
[lots of stuff scrolls by]

> mpf --version
Mission Pinball Framework v0.57.0.dev8

3. Update your MPF config files for MPF 0.57

There are some changes to the MPF config files for MPF 0.57. These changes fall into two categories:

3A. Update your config files to version 6

Prior to MPF 0.57, the MPF config files were "mostly" YAML but not 100% compliant. MPF had several "hacks" which originally made it easier to write config files, but over time these hacks made it hard to maintain MPF. (These hacks were part of the reason MPF was stuck on old versions of Python for so long.) So in MPF 0.57, we removed those hacks, which means that the MPF config files are now 100% compliant YAML. 🎉 The downside to this is that you'll need to update your MPF config files to be 100% compliant YAML.

Remember that MPF uses config file versions (that #config_version= line at the top of every config file) to ensure the files its loading will work, so to use MPF 0.57, you'll need to update your config files to use the new config files and show files to version 6.

The good news is that this is pretty easy to do. It's mostly "find and replace" type things. There's a guide to the config file v6 changes on the MPF website:

3B. Update the fast: section of your config files

The FAST platform interface was completely overhauled for MPF 0.57. Since we were doing all that work, and since the Neuron and Expansion boards change a lot of things, and since MPF 0.57 was already moving to a new config file version, we decided to make some changes to the FAST config settings as well.

You'll have to update the fast: section of your config, but that will only take a few minutes. And you'll also need to update the numbers for your hardware devices, but that's simple find-and-replace stuff.

If you have an existing config for an older version of MPF that you're migrating to 0.57, we have a migration guide

We also have an entire set of documentation (the FAST MPF Config Guides) which explains how add your FAST hardware to MPF configs.

4. Install MPF Monitor 0.57

The dev branch of MPF Monitor has also been updated to v0.57, and also supports Python 3.8-3.11. You install it in the same way you installed MPF 0.57, by adding the --pre flag to the pip command:

> pip3 install mpf-monitor --pre

Then you can run MPF Monitor like normal.

5. MPF-MC does NOT work yet!

So far, only MPF and MPF Monitor have been updated to 0.57. I did the technical work needed for MPF-MC to be updated, but there are issues compiling and building it that I can't figure out. So until we can get help with those, MPF-MC will not work with MPF 0.57.

There's an open issue on GitHub with details if you can help! (This has to do with Cython.)

6. Share bugs via Slack or GitHub

If you find any bugs in MPF 0.57, please let us know! Post any bugs or questions to the FAST Pinball slack in the #software channel. Or, if you want to post full details of a bug, you can post it to the MPF GitHub Issues page where it can be tracked fully.

Documentation Feedback? Requests? Confused?

Hi! I'm Brian, and I'm responsible for the documentation at FAST Pinball. If you have any feedback, requests, corrections, ideas, or any other thoughts about the docs, please let me know!

You can email me at I maintain this site in my spare time, so there might be a week or so delay if you email me.

If you have a more pressing need, reach out to us via Slack, or email Aaron Davis.


N or > jump the next page, P or < for previous, search with S or ?