Using MicroPython Stubber¶

This section describes how to use micropython-stubber to create and maintain stubs for a MicroPython firmware or project.

If you just want to use the stubs, then you can skip this section and instead read the documentation in the sister-repo [micropython-stubs][] section [using-the-stubs][].

Command Reference¶

Task	Primary Command	Aliases	Description
Initialize workspace	`stubber init`	-	Clone `micropython-stubs`, clone required repos, and switch to stable
Switch version	`stubber switch v1.22.2`	-	Switch to specific version/branch/commit
Generate doc stubs	`stubber docstubs`	`docs-stubs`, `docs`, `get-docstubs`	Create doc stubs from documentation
Generate frozen stubs	`stubber frozen`	`frozen-stubs`, `get-frozen`, `get-frozen-stubs`	Create frozen stubs from frozen modules
Generate firmware stubs	`stubber firmware-stubs`	`firmware`, `mcu-stubs`, `mcu`, `get-mcu-stubs`	Create firmware stubs (formerly MCU stubs; stored stub source name remains “MCU stubs” for compatibility) from connected device
Get core stubs	`stubber get-core`	-	Download CPython compatibility stubs
Build packages	`stubber build`	-	Build stub packages for distribution
Publish packages	`stubber publish-stubs`	-	Publish stubs to repository
Merge stubs	`stubber merge`	-	Combine different stub types
Show configuration	`stubber show-config`	`config`	Display current configuration
Create variants	`stubber variants`	`make-variants`	Create minified createstubs variants

Quick Start¶

For a beginner-friendly, step-by-step walkthrough see the Quick Start guide.

For official MicroPython releases, the condensed workflow is:

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

# Optional if you want a different version than stable
# stubber switch v1.22.2

stubber docstubs --enrich
stubber frozen --version stable --enrich
stubber merge --port esp32 --board ESP32_GENERIC --version stable
stubber build --port esp32 --board ESP32_GENERIC --version stable

# Optional: capture stubs directly from a connected device running your firmware
# stubber firmware-stubs --version stable  # alias mcu-stubs remains available

For a worked end-to-end walkthrough that mirrors these commands, see the notebook Manual stub build chain.ipynb.

The stubber firmware-stubs command will create the stubs on the MCU, copy them to the pc and merge them with the other stubs, and create a type-stub package in the publish folder.

You can specify the version of the stubs using the --version parameter on the various commands, for example --version=1.22.2, --version=preview, or omit it after stubber switch to reuse the selected version.

The name of the folder will be based on the the detected name of the port and the board, including the version, and will be logged as part of the output of the command, as shown below:

                                                         Results
┏━━━━━━━━━━┳━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┳━━━━━━━━━━┳━━━━━━━┓
┃ Result   ┃ Name/Path                                                                                ┃ Version  ┃ Error ┃
┡━━━━━━━━━━╇━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━╇━━━━━━━━━━╇━━━━━━━┩
│ Build OK │ micropython-esp32-esp32_generic_c6-stubs                                                 │ 1.27.0a1 │       │
│          │ repos/micropython-stubs/publish/micropython-v1_27_0_preview-esp32-esp32_generic_c6-stubs │          │       │
└──────────┴──────────────────────────────────────────────────────────────────────────────────────────┴──────────┴───────┘

Custom MicroPython Builds¶

If you’re working with a fork, branch, pull request, or custom build of MicroPython, see the Custom MicroPython Guide for detailed step-by-step instructions.