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]

Clean and then build a board (rebuild from scratch):

mpbuild rebuild 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 / Rebuild / Clean buttons. The bottom-right log streams docker output as the build runs.

Key bindings:

Clicking Build, Rebuild, or Clean 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