mpbuild

Build MicroPython firmware with ease!

mpbuild builds MicroPython firmware in containers so you don't need to install any compiler toolchains or development tools. It knows which containers to use for each board so the appropriate build tools are used.

Table of Contents

• Usage
  • Interactive mode
  • Advanced Usage
  • Use as a Module
• Installation
  • Prerequisites
• Examples
• Testing
• Related links

Usage

mpbuild is intended to be executed in the root of a MicroPython repository. Help text (accessed with adding --help) is extensive and documents advanced options.

Note

Note that there are some special builds. unix, webassembly and windows can all be specified as BOARDs but their target isn't a microcontroller. See the MicroPython documentation for details.

Warning

Currently mpbuild is tested on Linux (specifically Ubuntu 24.04 on WSL on Windows 11) but it's intended to work on any platform that supports Docker.

Build a board, with optional variant:

mpbuild build BOARD [VARIANT]

Remove build artifacts:

mpbuild clean BOARD [VARIANT]

List the available boards, optionally filter by the port name.

Displays the board names (as a clickable link), variants and number of boards per port:

mpbuild list [PORT]

Interactive mode

For exploring boards and triggering builds without typing the names, mpbuild ships with a Textual TUI:

mpbuild --interactive   # or `mpbuild -i`

The left pane shows every port and board found in the MicroPython tree. Selecting a board fills the right pane with its metadata, reveals a variant dropdown if the board has variants, and enables the Build / Clean buttons. The bottom-right log streams docker output as the build runs.

Key bindings:

Key	Action
↑ / ↓	Navigate the tree
→	Expand the current branch
←	Collapse the current branch (or, on a leaf, collapse the parent)
Enter	Select
b	Build the selected board
c	Clean the selected board
s	Stop the running build
q	Quit

Clicking Build while a build is already running terminates the running container before starting the new one. Stop is enabled only while a build is actually streaming.

Advanced Usage

Validate the state of all images referenced in board definitions:

mpbuild check_images

Use as a Module

Caution

This is very much a work-in-progress and the API is subject to change.

mpbuild can also be used from Python as a module. This allows it to easily be integrated into other tools.

Example:

import mpbuild

mpbuild.build("RPI_PICO")
mpbuild.list()

Installation

uv tool install mpbuild

Or use pipx, pip etc.

After installation, you may want to also install command-line tab completion for your shell (bash, zsh, fish and PowerShell are supported). Tab completion includes the various mpbuild commands as well as the board names and variants:

mpbuild --install-completion

Prerequisites

A clone of MicroPython (or a fork):

git clone git@github.com:micropython/micropython.git

Docker is currently necessary for managing containers and must be installed and available on your system path.

Examples

$ mpbuild build RPI_PICO
# Downloads appropriate containers and builds firmware for the Raspberry Pi Pico

$ mpbuild list rp2
🐍 MicroPython Boards
└── rp2   19
    ├── ADAFRUIT_FEATHER_RP2040
    ├── ADAFRUIT_ITSYBITSY_RP2040
    ├── ADAFRUIT_QTPY_RP2040
    ├── ARDUINO_NANO_RP2040_CONNECT
    ├── GARATRONIC_PYBSTICK26_RP2040
    ├── NULLBITS_BIT_C_PRO
    ├── PIMORONI_PICOLIPO  FLASH_16M
    ├── PIMORONI_TINY2040  FLASH_8M
    ├── POLOLU_3PI_2040_ROBOT
    ├── POLOLU_ZUMO_2040_ROBOT
    ├── RPI_PICO
    ├── RPI_PICO2  RISCV
    ├── RPI_PICO_W
    ├── SIL_RP2040_SHIM
    ├── SPARKFUN_PROMICRO
    ├── SPARKFUN_THINGPLUS
    ├── W5100S_EVB_PICO
    ├── W5500_EVB_PICO
    └── WEACTSTUDIO  FLASH_2M, FLASH_4M, FLASH_8M

Testing

The test suite uses pytest. Dev dependencies are declared in the dev group of pyproject.toml.

Install dev dependencies:

uv sync --group dev

Run the tests:

uv run pytest

Run with coverage:

uv run pytest --cov=mpbuild --cov-report=term-missing