Mach (German for do) is a generic command dispatcher for the command line.

To use mach, you install the mach core (a Python package), create an executable driver script (named whatever you want), and write mach commands. When the driver is executed, mach dispatches to the requested command handler automatically.


On a high level, mach is similar to using argparse with subparsers (for command handling). When you dig deeper, mach offers a number of additional features:

Distributed command definitions

With optparse/argparse, you have to define your commands on a central parser instance. With mach, you annotate your command methods with decorators and mach finds and dispatches to them automatically.

Command categories

Mach commands can be grouped into categories when displayed in help. This is currently not possible with argparse.

Logging management

Mach provides a facility for logging (both classical text and structured) that is available to any command handler.

Settings files

Mach provides a facility for reading settings from an ini-like file format.


Mach is conceptually composed of the following components:


The mach core is the core code powering mach. This is a Python package that contains all the business logic that makes mach work. The mach core is common to all mach deployments.


These are what mach dispatches to. Commands are simply Python methods registered as command names. The set of commands is unique to the environment mach is deployed in.


The driver is the entry-point to mach. It is simply an executable script that loads the mach core, tells it where commands can be found, then asks the mach core to handle the current request. The driver is unique to the deployed environment. But, it’s usually based on an example from this source tree.

Project State

mach was originally written as a command dispatching framework to aid Firefox development. While the code is mostly generic, there are still some pieces that closely tie it to Mozilla/Firefox. The goal is for these to eventually be removed and replaced with generic features so mach is suitable for anybody to use. Until then, mach may not be the best fit for you.