Quick Start

April 27, 2026 · View on GitHub

(quick-start)=

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?

{ref}Stub files <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 typeSourceCommand
{ref}Firmware stubs <mcu-stubs>Connected boardstubber firmware-stubs
{ref}Doc stubs <doc-stubs>MicroPython documentationstubber docstubs
{ref}Frozen stubs <frozen-stubs>Modules frozen into firmware sourcestubber 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.
**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

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