Quick Start – Contributing stubs for a new board

This guide walks you through generating and contributing a complete set of MicroPython stubs for a new port or board to the micropython-stubs project. No prior knowledge of the project internals is needed.

What are stubs, and why do I need them?

Stub files teach your editor (VS Code, PyCharm, …) about the MicroPython modules that are available on your board. Without them, the editor has no way to offer code-completion or type-checking for machine, network, uos, and every other MicroPython-specific module.

Three complementary stub types are combined to give the best coverage:

Stub type

Source

Command

Firmware stubs

Connected board

stubber firmware-stubs

Doc stubs

MicroPython documentation

stubber docstubs

Frozen stubs

Modules frozen into firmware source

stubber frozen

Prerequisites

  • Python 3.9 or newer installed on your PC.

  • Git installed (needed to clone the MicroPython source tree).

  • A MicroPython board connected to your PC, flashed with a recent stable or preview release.

  • A working directory — for example ~/my-stubs.

Note

Platform support: stubber has been tested on both Windows and Unix (Linux / macOS). Running stubber inside WSL2 is also supported, but can occasionally encounter errors caused by extra timing delays that occur after a device resets — if you see connection timeouts, try running from a native Windows terminal instead.

Step 1 – Install micropython-stubber

uv tool install micropython-stubber

Verify the installation:

stubber --help

Step 2 – Create a working directory

mkdir ~/my-stubs
cd ~/my-stubs

All subsequent commands should be run from inside this directory unless noted otherwise.

Step 3 – Initialize the workspace

Use one command to:

  • clone micropython-stubs into ./micropython-stubs

  • clone micropython + micropython-lib into ./micropython-stubs/repos

  • switch those repos to the latest stable MicroPython version

stubber init

At the end, stubber init prints a cd command with the full path. Run it before continuing:

cd ~/my-stubs/micropython-stubs

After initialization, your workspace looks like this:

~/my-stubs/
└── micropython-stubs/
	├── repos/
	│   ├── micropython/      ← MicroPython source (for doc & frozen stubs)
	│   └── micropython-lib/  ← MicroPython library source
	└── publish/              ← Built stub packages

Step 4 (optional) – Generate doc stubs

Doc stubs are generated from the MicroPython documentation and contain full parameter names and descriptions. Skip this step if you only need firmware stubs for a new board — the cloned repo already contains up-to-date doc stubs.

stubber docstubs --enrich

Step 5 (optional) – Generate frozen stubs

Frozen stubs cover Python modules compiled directly into the firmware. Skip this step if the board’s frozen modules are already covered in the cloned repo.

stubber frozen --version stable --enrich

Note

Generating frozen stubs requires checking out the MicroPython source tree and can take 10–20 minutes depending on your internet connection and machine speed.

Step 6 – Generate firmware stubs from a connected device

Connect your board (flashed with a stable or preview MicroPython release) and run:

stubber firmware-stubs

This captures the board-specific modules that may not be documented or frozen elsewhere. The port, board name, and version are detected automatically and used to name the output folder.

Step 7 – Merge and build the stub package

The stubber firmware-stubs command already runs the below steps, but in some cases you may want to re-run them after making manual edits to the generated stubs, or after regenerating doc/frozen stubs in steps 5 and 6.

Combine all stub types for your board into a single distributable package. Replace esp32 / ESP32_GENERIC with the values reported by the previous step:

stubber merge --port esp32 --board ESP32_GENERIC --version stable
stubber build --port esp32 --board ESP32_GENERIC --version stable

The resulting stub package is placed under publish/.

Step 8 – Verify the stubs locally

Before opening a pull request, install the built stub package locally to confirm it works in your editor. Replace the folder name below with the actual name produced by stubber build:

# From inside ~/my-stubs/micropython-stubs
pip install ./publish/micropython-v1_27_0-esp32-esp32_generic_c3-stubs/ --target ../typings

The typings folder is the conventional location for MicroPython stubs in VS Code projects. Point your editor’s Python extension at this folder to get code-completion and type-checking for your board.

Step 9 – Contribute your stubs

Open a pull request against micropython-stubs so the new board stubs become available to everyone:

git checkout -b add-stubs-esp32-esp32_generic-stable
git add .
git commit -m "Add stubs for esp32 ESP32_GENERIC stable"
git push origin add-stubs-esp32-esp32_generic-stable

Then open a pull request on GitHub at https://github.com/Josverl/micropython-stubs/compare.

Full workflow at a glance

pip install micropython-stubber
mkdir ~/my-stubs && cd ~/my-stubs

stubber init
cd ~/my-stubs/micropython-stubs

# Optional: regenerate doc and frozen stubs (takes 10-20 min)
# stubber docstubs --enrich
# stubber frozen --version stable --enrich

# Required: board must be connected with stable/preview firmware
stubber firmware-stubs

stubber merge --port esp32 --board ESP32_GENERIC --version stable
stubber build --port esp32 --board ESP32_GENERIC --version stable

# Verify locally before submitting a PR
pip install ./publish/micropython-v1_27_0-esp32-esp32_generic_c3-stubs/ --target ../typings

# Contribute: open a PR to micropython-stubs
git checkout -b add-stubs-esp32-esp32_generic-stable
git add . && git commit -m "Add stubs for esp32 ESP32_GENERIC stable"
git push origin add-stubs-esp32-esp32_generic-stable

Next steps