Skip to content

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 (no media controller) by running:

mpf <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 -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). For a list of all the 'mpf game' command-line options, see C.

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 command-line utility (Starts the MPF game engine and other commands)
  • mpf (Starts the MPF engine)
  • mpf mc (Starts the MPF Media Controller)
  • mpf both (Starts both the MPF 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.

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