What MicroPython is and where it runs

A Raspberry Pi Pico has 264 KB of RAM, no operating system and no screen, yet you can type 2 + 3 into it over a USB cable and it answers 5. MicroPython makes that possible: an implementation of Python 3 small enough to live inside a microcontrollermicrocontroller: A computer on one chip: a processor, a few hundred kilobytes of RAM, flash memory or an interface to it, and pins for the outside world. It runs one program, often with no operating system., which its project says can be as small as 256 KiB of flash and 16 KiB of RAM.

This lesson shows what runs on the chip when your Python runs there, which parts of the Python you know carry over, which boards and ports MicroPython supports and how well, and how to read the one object that names the build a board is running. By the end you will have picked a board for this track, and you will be able to decode the number that every build reports about the code it can load.

MicroPython compiles and runs your Python on the chip itself

On your computer, Python is a program that the operating system starts. A Pico has no operating system, so MicroPython brings everything with it. Its firmwarefirmware: The program stored in a microcontroller's flash that starts when it powers on. MicroPython's firmware holds the interpreter, its built-in modules and the drivers for one board., one file you install on the board, holds a compiler, a virtual machine that runs bytecodebytecode: Compact instructions that MicroPython's compiler makes from Python source and its virtual machine runs. MicroPython's bytecode format is not CPython's., a memory manager with a garbage collector, the built-in modules and the C code that drives that board’s hardware. MicroPython’s glossary puts it plainly: on a board without an operating system, MicroPython works like a small operating system itself, running your programs and giving you an interactive prompt. The ESP32 is the one exception among the boards of this track: its port runs on ESP-IDF, Espressif’s development framework, which is built on FreeRTOS. Your programs see the same MicroPython on both.

Follow a two-line main.py that switches GPIO 0 on, from the text in the board’s flash to the pin:

If you come from Arduino, notice the second step: the board compiles the source itself, so there is no build step on your computer. The cost is RAM. MicroPython’s guide to small chips says the bytecode of every imported module is kept in RAM, and the compiler needs RAM of its own while it works, so a program with many modules can run out of memory just by importing them. That is why the same code can reach the virtual machine in three ways:

You will write plain .py files for most of this track; precompiling and freezing come back in the module on packages and firmware, when a program outgrows its RAM.

Your Python carries over, but CPython’s standard library does not

Take a CPython script that reads a sensor value, formats it with an f-string, stores it as JSON and logs the time. On MicroPython the language part of it carries over almost untouched. The project’s README says MicroPython implements the entire Python 3.4 syntax, the async and await keywords of Python 3.5 and selected features of later versions, with the core types you use every day: str, bytes, bytearray, tuple, list, dict, set, classes and instances. The library part is different, and that is where most porting work goes:

The library reference calls the 29 cut-down modules “micro-ified”: each keeps the core of its CPython namesake, but only part of its functions. It also warns that a port, or one firmware file, may leave out a documented module or function to save space. The 12 MicroPython modules are the reason to use it at all: machine drives pins, timers and buses, and network joins Wi-Fi on boards that have a radio.

To see what a build has, type help('modules') at its prompt: on the ports that support it, it lists every module built into the firmware, frozen ones included. The next module of this track, on the differences from CPython, works through the rest one probe at a time.

Firmware is built for one board, and each port has a support tier

MicroPython’s download page lists different files for the Pico and the Pico W, although both boards carry the same RP2040 chip. The Pico W has a Wi-Fi and Bluetooth chip beside the RP2040, and only its firmware switches on the network module and the driver for that chip, as the board’s configuration in the source shows. That is the general rule: the glossary says firmware is usually built per boardboard: A circuit board that carries a microcontroller and the parts around it, such as the Raspberry Pi Pico. MicroPython firmware is usually built for one board, with its drivers and pin names., because it holds the board’s drivers and pin names as well as code for the chip.

The code that adapts MicroPython to one family of chips, or one operating system, is a portport: MicroPython adapted to one family of chips or one operating system, such as rp2 for the RP2040 and RP2350, esp32, or unix. Each port builds the firmware for its boards.. The rp2 port covers the RP2040 and the RP2350, the esp32 port Espressif’s ESP32 chips, and the unix and windows ports run MicroPython as a program on a computer. Since version 1.27, each port belongs to a support tiersupport tier: One of MicroPython's four levels of care for a port. Tier 1 ports such as rp2, esp32 and unix are the most actively maintained, tested and documented. that says how much care it gets:

The two ports this track uses, rp2 and esp32, are both Tier 1, and so is unix, which runs on your computer. Answer three questions about your projects and the table below marks which of the four boards of this track fit them:

In short: a Pico W or a Pico 2 W follows the whole track and installs with a file copy; a plain Pico does everything except the networking module; an ESP32 board brings the fastest cores and installs with a command-line tool. What only one chip can do, such as PIO on the RP2040 and RP2350 or partitions on the ESP32, has a module of its own near the end of the track.

sys.implementation names the build a board is running

Two boards can run the same release and still differ: one has a radio driver, another emits machine code for a different processor. The object sys.implementation tells you which build you are talking to, and the MicroPython documentation recommends it as the way to tell MicroPython apart from other Pythons. On a Pico running 1.29.0, its fields hold these values, which the firmware takes from its own configuration:

The last field is a number with three fields packed into it. MicroPython’s page on .mpy files lays out the bits: the lowest 8 hold the .mpy version, the next 2 the sub-version, and bits 10 to 13 the native architecture, an index into a fixed list of instruction sets. Step through the decoding of the Pico’s 4870:

ARCH = [None, "x86", "x64",
        "armv6", "armv6m",
        "armv7m", "armv7em",
        "armv7emsp", "armv7emdp",
        "xtensa", "xtensawin",
        "rv32imc", "rv64imc"]

mpy = 4870
version = mpy & 0xFF
sub = (mpy >> 8) & 3
code = (mpy >> 10) & 0x0F
arch = ARCH[code]
flags = mpy >> 16
print("version:", version)
print("sub-version:", sub)
print("arch:", arch)
print("arch flags:", flags)

version: 6
sub-version: 3
arch: armv6m
arch flags: 0

So the Pico loads .mpy files of version 6.3, and machine code inside them must be armv6m. The architecture matters the day you copy a precompiled module from one board to another: a .mpy file that holds machine code for one architecture fails to import on a board of another with ValueError('incompatible .mpy arch'). The next program works out the number for four builds of this track’s release from the same layout, and decodes each one back. Like every program in this track, it shows under the code what it printed when it ran. The programs on these pages are the half that runs on your computer, as mpremote and editors do, and they ran on Python 3.14.8; code for the board is what you type at its prompt or save on it, and a program that stands in for a board says so:

"""The sys.implementation._mpy number of four MicroPython 1.29.0 builds, worked out and decoded.

The number packs three fields: the .mpy version in bits 0 to 7, the sub-version in bits 8 and 9,
and the native architecture in bits 10 to 13 (MicroPython's ".mpy files" page, py/persistentcode.h).
"""

ARCH = (None, "x86", "x64", "armv6", "armv6m", "armv7m", "armv7em",
        "armv7emsp", "armv7emdp", "xtensa", "xtensawin", "rv32imc", "rv64imc")

MPY_VERSION = 6      # .mpy 6.3 is the format of v1.23.0 and every later release
MPY_SUB_VERSION = 3


def encode(arch):
    """The _mpy number of a build whose compiler emits machine code for arch (None: no machine code)."""
    return MPY_VERSION | (MPY_SUB_VERSION << 8) | (ARCH.index(arch) << 10)


def decode(value):
    """The .mpy version, sub-version and native architecture that an _mpy number holds."""
    return value & 0xFF, (value >> 8) & 3, ARCH[(value >> 10) & 0x0F]


BUILDS = [
    ("RPI_PICO", "armv6m"),           # RP2040: two Arm Cortex-M0+ cores
    ("ESP32_GENERIC", "xtensawin"),   # ESP32: two Xtensa LX6 cores
    ("unix on x86-64", "x64"),
    ("unix on 64-bit Arm", None),     # MicroPython has no emitter for 64-bit Arm
]

print(f"{'Build':<20}{'_mpy':>6}  {'hex':>6}  .mpy  native code")
for name, arch in BUILDS:
    value = encode(arch)
    version, sub, found = decode(value)
    print(f"{name:<20}{value:>6}  {value:#06x}  {version}.{sub}   {found or 'none'}")

# Put the number your own board printed for sys.implementation._mpy here, then run again.
mine = 4870
version, sub, found = decode(mine)
print(f"\nYour board: {mine} is .mpy {version}.{sub}, native code {found or 'none'}")

Build                 _mpy     hex  .mpy  native code
RPI_PICO              4870  0x1306  6.3   armv6m
ESP32_GENERIC        11014  0x2b06  6.3   xtensawin
unix on x86-64        2822  0x0b06  6.3   x64
unix on 64-bit Arm     774  0x0306  6.3   none

Your board: 4870 is .mpy 6.3, native code armv6m

Every build of the release says .mpy 6.3, because the format belongs to the release, and only the architecture changes: armv6m for the Pico’s Cortex-M0+ cores, xtensawin for the ESP32, x64 for the unix port on a PC, and none at all for the unix port on a 64-bit Arm computer, for which MicroPython has no native code emitter.

Not every build has all six fields. _build was added in version 1.25.0 and _thread in 1.26.0, so a board still on 1.24 has neither, and _mpy is optional too: a very small port without .mpy support leaves it out. Read these fields with getattr(sys.implementation, "_build", None), so that a missing one is not an error.

Practise: describe a build

Write the function that turns a sys.implementation object into the four facts this lesson decoded: the version, the build name, the .mpy version and the architecture. The sample tests use the builds of the tables above, a board too old to have _build, and a RISC-V build whose number carries flag bits above bit 15:

ARCH = (None, "x86", "x64", "armv6", "armv6m", "armv7m", "armv7em",
        "armv7emsp", "armv7emdp", "xtensa", "xtensawin", "rv32imc", "rv64imc")


def describe_build(impl):
    """Describe the MicroPython build that a sys.implementation-like object stands for."""
    return {}

from types import SimpleNamespace

from build import describe_build


def impl(**fields):
    return SimpleNamespace(name="micropython", **fields)


def test_pico():
    """describes a Pico on 1.29.0"""
    pico = impl(version=(1, 29, 0, ""), _build="RPI_PICO", _mpy=4870)
    assert describe_build(pico) == {"version": "1.29.0", "build": "RPI_PICO", "mpy": (6, 3), "arch": "armv6m"}


def test_esp32_and_unix():
    """finds xtensawin, x64 and no native code"""
    assert describe_build(impl(version=(1, 29, 0, ""), _build="ESP32_GENERIC", _mpy=11014))["arch"] == "xtensawin"
    assert describe_build(impl(version=(1, 29, 0, ""), _build="standard", _mpy=2822))["arch"] == "x64"
    assert describe_build(impl(version=(1, 29, 0, ""), _build="standard", _mpy=774))["arch"] is None


def test_older_build_without_build_name():
    """gives None for a build without _build"""
    old = impl(version=(1, 24, 1, ""), _mpy=4870)
    assert describe_build(old) == {"version": "1.24.1", "build": None, "mpy": (6, 3), "arch": "armv6m"}


def test_no_mpy():
    """gives None for mpy and arch without _mpy"""
    tiny = impl(version=(1, 29, 0, ""), _build="minimal")
    assert describe_build(tiny) == {"version": "1.29.0", "build": "minimal", "mpy": None, "arch": None}


def test_preview():
    """marks a preview version"""
    assert describe_build(impl(version=(1, 30, 0, "preview"), _mpy=774))["version"] == "1.30.0-preview"


def test_flag_bits_ignored():
    """reads the architecture under the flag bits of a RISC-V build"""
    riscv = impl(version=(1, 29, 0, ""), _build="RPI_PICO2-RISCV", _mpy=6 | 3 << 8 | 11 << 10 | 1 << 16)
    assert describe_build(riscv) == {"version": "1.29.0", "build": "RPI_PICO2-RISCV", "mpy": (6, 3), "arch": "rv32imc"}


def test_unknown_code():
    """gives "unknown" for a code past the end of ARCH"""
    assert describe_build(impl(version=(1, 29, 0, ""), _mpy=6 | 3 << 8 | 15 << 10))["arch"] == "unknown"


def test_not_micropython():
    """refuses another Python"""
    cpython = SimpleNamespace(name="cpython", version=(3, 14, 8, "final"))
    try:
        describe_build(cpython)
    except ValueError:
        return
    raise AssertionError("expected ValueError for cpython")

Last, test yourself on the four ideas of this lesson. The self-check picks the idea you are weakest on first, and it explains each choice you make on the spot:

Interview questions

Warm-up (fresher): What is MicroPython, and how is it different from CPython?

MicroPython is an implementation of Python 3 for microcontrollers and other small systems, written in C and shipped as firmware for each board. The firmware holds a compiler, a bytecode virtual machine, a garbage-collected heap and the built-in modules, so the board compiles and runs .py files itself, with a few hundred kilobytes of RAM and, on a chip such as the Pico’s, no operating system at all. The language is close to CPython’s: the whole Python 3.4 syntax, async and await, and selected later features. The libraries differ: 29 standard modules exist only in cut-down form, others such as datetime come from micropython-lib through mip, and MicroPython adds modules of its own, such as machine for pins, timers and buses.

Two longer interview questions of this module start from this lesson:

Key takeaways

• MicroPython’s firmware holds a compiler, a bytecode virtual machine and the board’s drivers, so the board compiles and runs your .py files itself, on a Pico with no operating system at all.
• The language carries over from CPython (the Python 3.4 syntax, async and await, selected later features), while the standard library shrinks to 29 cut-down modules, with more in micropython-lib.
• Firmware is built per board, and a port’s support tier says how much care it gets: rp2, esp32 and unix, the ports of this track, are all Tier 1.
• A Pico W or a Pico 2 W follows the whole track; a plain Pico has no radio, and an ESP32 board brings more RAM and installs with esptool instead of a file copy.
• sys.implementation names the running build, and its _mpy number packs the .mpy version, the sub-version and the native architecture: 4870 means .mpy 6.3 with armv6m machine code.