This is the documentation the latest work-in-progress version of MPF!

This is the documentation for MPF 0.56, which is the “dev” (next) release of MPF that is a work-in-progress. This is probably ok, and means you’ll be on the latest, cutting-edge version of MPF.

However, if you want a more stable version, select the v:stable version from the lower-left corner of this page, which is the most recent version that is not getting new updates.

If you are new to MPF, we have recently rewritten the installation process which only applies to this “latest” 0.56, so you probably want to stay here because the prior installation process doesn’t work on the latest OS and Python versions.

How to start MPF and run your game

MPF is a console-based application which you run from the command line.

The quick version

  1. Open a command prompt
  2. Switch to your machine folder
  3. Run mpf both

Starting the MPF game engine and media controller together

You can start both the MPF game engine and the media controller at the same time with a single command.

Since this is done from the command line, you’ll need to open a command line window. On Windows, you can right-click on the Start Button (or whatever it’s called these days) and click the “Command Prompt”. On Mac OS X you can run the Terminal app. On Linux, well, if you’re using Linux, you know what a command line is. :)

From the command line, change to the directory which is the root of your machine folder. This is the folder that contains your machine’s config, modes, shows, etc. folders.


Prior to MPF 0.30, we recommended that you put your machine’s folder in the /machine_files folder inside the MPF package. That is changed now, and you can put your machine folder(s) wherever you want. In fact now that MPF has a “real” installer, the MPF package folder is hidden deep inside your system.

Then run:

mpf both <enter>

The mpf both command is what we use and probably what you’ll use 99% of the time.

Starting the MPF media controller

Alternately you can choose to run just the media controller by itself (still from within your machine folder) like this:

mpf mc <enter>

You should see a popup window and a bunch of stuff scroll by in the console.

Starting the MPF game engine

You can run the MPF game engine by itself by running:

mpf game <enter>

Note that if you do not have a media controller running, the game engine won’t start fully because it will get stuck trying to connect to the media controller. To avoid this if you just want to run the game engine by itself, add the -b command line option. (Details below)

Specifying command-line options

There are several command-like options you can use when you run MPF. To use them, add them after the name of the MPF command you’re running, like:

mpf game -x -v

mpf mc -xvV

mpf both -v -b

The full list of available commands is covered in the documentation for each command (discussed below).

Understanding how this works

When you install MPF, the command mpf is registered with your system. Then you can open a command prompt and run “mpf” from any folder.

There are several sub-commands you can specify when you run MPF. You specify a sub-command by running mpf <command>. (Some mpf commands take additional options).

Here’s a list of valid MPF commands. Click on any one of them for full details and command-line options.

  • mpf (Starts the MPF game engine and other commands)
  • mpf game (Starts the MPF game engine)
  • mpf mc (Starts the MPF Media Controller)
  • mpf both (Starts both the MPF game engine and media controller at the same time)
  • mpf migrate (Migrates older config and show files to the current version)
  • mpf hardware (Scan, inspect and configure hardware)
  • mpf service (Service command line interface)
  • mpf build (Build production bundles)

Specifying BCP ports

By default, the MPF game engine and the MC will connect via TCP port 5050. You can change that port to whatever you want though.