Skip to content

Installing MPF

The current stable version of MPF is 0.57.1, and the upcoming release is 0.80.0.

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!

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

MPF works with Python 3.8 - 3.11. It runs on 3.12 but has not been extensively tested, so your mileage may vary.

Simplest Installation: Precompiled Binary (MPF 0.80)

As of MPF 0.80 we are providing precompiled binaries for new users to get up and running as easily as possible. You can see all the latest binaries at the MPF Precompiled Binaries repository, but here are some links:

Advantages of Simplest Installation:

  • Fastest way to get MPF running on a computer
  • No installation or dependencies necessary
  • Always has compatible Python and package versions

Disadvantages of Simplest Installation:

  • Startup times are slower than a Standard Installation
  • Not (yet) available for all platforms
  • No option to customize MPF or use bleeding-edge features

Okay, it's not technically "pre-compiled". MPF is written in Python, which is an interpreted language, and therefore cannot be truly "compiled" into a binary. The provided binaries are special applications that bundle a copy of Python, the MPF framework modules, and all dependency packages into a single file.

The point is, you can download a single file and run it and have a working copy of 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.8-3.12 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.8+ 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.8+ 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:

  • Fast startup times (compared to precompiled binaries)
  • 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.8+ 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:

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.

Next step: The Tutorial!

We have a tutorial which walks you through the first few steps of getting your project started at missionpinball.org/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