Skip to content

New MPF Coming Soon!

The next major release of MPF will be 0.80 and is coming soon! This exciting advancement offers a brand-new media controller based on the powerful Godot game engine. If you are just getting started with MPF, consider giving 0.80 a try!

Installing MPF 0.80 or 0.57

The current stable version of MPF is 0.57.3, and the upcoming release is 0.80.0 along with a long-term support release of 0.57.4.

The current beta version of MPF 0.80 is 0.80.0.dev11, which corresponds with MPF-GMC 0.1.6, which is necessary to use the latest Godot - 4.5.1.

Latest Versions

If you are creating a new game and are installing all of the MPF tools from scratch, you should start with the most up-to-date versions of everything you can. This will ensure you have the latest features and bug fixes, and are the easiest for the community to support. The most updated full installation (known-working on Windows and Linux) as of January 2026 is:

  • Python 3.13
  • MPF 0.80.0.dev11 (via pip --pre option)
  • MPF-GMC 0.1.6 (via Asset Library)
  • Godot Editor 4.5
  • MPF Monitor 0.57.2
  • Note: mpf-mc is no longer supported with MPF 0.80+, use Godot and MPF-GMC instead

Supported Operating Systems

MPF works with following platforms:

  • Windows 10 / Windows 11 (64-bit only)
  • macOS 10.14+, up through macOS 14 Sonoma (Intel & Apple Silicon)
  • Linux (64-bit, lots of distros including Debian and Ubuntu)
  • Raspberry Pi

Python Version Matching

MPF 0.57 works with Python 3.8 - 3.12. There is no planned support for Python 3.13+.

MPF 0.80 works with Python 3.10 - 3.13, with upcoming support for 3.14.

Migrating MPF 0.57 to MPF 0.80

If you have an existing MPF 0.57 project and would like to use MPF 0.80 and the GMC, there are just a few config changes needed. See the MPF 0.80 Migration Guide for instructions.

Video Tutorial

The following video shows on Windows how to install Python, Godot Engine, VS Code, and Sourcetree/Git, use Github to create a repo, and how to manage your Python Virtual Environment (venv) and install MPF.

Standard Installation: Pip Install (MPF 0.80)

Regardless of your platform or Python version, a virtual environment is strongly recommended when working with MPF unless you are using a precompiled binary.

Do not skip the Virtual Environment

Virtual environments are important for keeping your computer clean and preventing different packages from conflicting. Without virtual environments, you may encounter dependency conflicts and stale packages that will prevent MPF from running. Troubleshooting and manually cleaning up packages is a pain—do your future self a favor and setup an MPF virtual environment now!

After creating your Python 3.10-3.13 virtual environment and activating it, install MPF 0.80.

pip install mpf --pre

Now when inside your virtual environment, you can run MPF simply by typing mpf while in your machine folder. To update MPF, type pip install --upgrade mpf.

Advantages of Standard Installation:

  • Fast startup times (compared to precompiled binaries)
  • Easy upgrading of MPF, including pre-release versions
  • Smallest size on disk

Disadvantages of Standard Installation:

  • Requires a local Python 3.10+ installation
  • Requires setting up a virtual environment
  • Mistakes can pollute Pip environments and cause dependency conflicts
  • No option to customize MPF or use bleeding-edge features

Many Python Interpreters Supported

Without the MC's Kivy dependencies, MPF 0.80 now supports alternative Python interpreters like PyPy. You can use a different interpreter if you'd like.

Expert Installation: Local Repository (MPF 0.80)

For complete control, you can clone the MPF repository to your computer and run it directly from the source code.

After creating your Python 3.10+ virtual environment, go to the folder where you wish to clone the MPF repository and type:

git clone https://github.com/missionpinball/mpf
cd mpf
git checkout 0.80.x
pip install -e .

Now when inside your virtual environment, you can run MPF simply by typing mpf while in your machine folder. Typing pip list will reveal that the MPF module is being run directly from the repo folder on your computer. To update MPF, navigate inside the MPF repo folder and type git fetch and git pull.

Advantages of Expert Installation:

  • Faster startup times
  • Access to any version of MPF, including feature branches and forks
  • Edit the MPF source code and see the effects immediately

Disadvantages of Expert Installation:

  • Requires a local Python 3.10+ installation
  • Requires setting up a virtual environment
  • Requires knowledge of Git mechanics
  • Updates require a manual fetch and pull of the repository

Installing MPF 0.57 (Legacy MC)

If you are installing MPF 0.57 to continue work on an existing MC-based project, here are links to the legacy installation guides for each platform:

Next step: The Tutorial!

We have a tutorial which walks you through the first few steps of getting your project started at MPF Tutorial.

Something missing or wrong? You can fix it!

This website is edited by people like you! Is something wrong or missing? Is something out of date, or can you explain it better?

Please help us! You can fix it yourself and be an official "open source" contributor!

It's easy! See our Beginner's guide to editing the docs.

Page navigation via the keyboard: < >

You can navigate this site via the keyboard. There are two modes:

General navigation, when search is not focused:

  • F , S , / : open search dialog
  • P , , : go to previous page
  • N , . : go to next page

While using the search function:

  • Down , Up : select next / previous result
  • Esc , Tab : close search
  • Enter : go to highlighted page in the results