Python to bare-metal firmware — no runtime, no interpreter, no VM.
Explore the project »

Report a bug · Request a feature · Sponsor

_{Ecosystem Partner}

PyMCU compiles a statically-typed subset of Python into bare-metal firmware for AVR, ARM (RP2040 / RP2350) and PIC — no runtime, no interpreter, no virtual machine. The same binary you would write in C.

A real session: 9 lines of Python → pymcu build → 150 bytes of flash → running on an Arduino Uno. Then the delay is edited, rebuilt and reflashed — the whole loop takes seconds.

LED blink for ATmega328P @ 16 MHz — all variants do the same thing: configure PB5 as output, then loop LED on → wait 500 ms → LED off → wait 500 ms forever.

PyMCU produces a smaller binary than C here. Why?

Pin("PB5", Pin.OUT) and delay_ms(500) are resolved entirely at compile time — the compiler sees through the Python objects and emits the same raw SBI/CBI port-toggle instructions a C programmer would write by hand. The rest of the difference is the delay: PyMCU emits one calibrated delay subroutine shared by both waits (rcall twice), where avr-libc's _delay_ms is inlined at each call site — and there is no call main / jmp _exit scaffolding around the program. The interrupt vector table and startup stub are identical fixed overhead in both toolchains.

Native HAL and MicroPython API produce byte-for-byte identical firmware — both compile down to the same SBI/CBI toggle and the same delay loop. The API is a zero-cost abstraction. CircuitPython is 2 bytes larger because the Direction.OUTPUT setter clears the PORT register before setting DDR, as the CircuitPython spec requires.

These numbers are for a minimal blink. Real programs that use SRAM (global variables, buffers) will emit a small zeroing loop at startup, just like C does.

For complex drivers (custom protocols, timing-critical bit-bang): expect 2-3x flash vs hand-written C. PyMCU is not competing with C — the goal is to make microcontroller development approachable in Python you already know, without the overhead of Arduino. The output is still 100-1000x smaller than any embedded Python interpreter.

Pick the API that fits your background. Both compile to the same bare-metal firmware.

# The exact same code that runs on a Pico under CircuitPython
import board
import digitalio
import time

led = digitalio.DigitalInOut(board.LED)
led.direction = digitalio.Direction.OUTPUT

while True:
    led.value = True
    time.sleep(0.5)
    led.value = False
    time.sleep(0.5)

# The exact same code that runs on a Pico under MicroPython
from machine import Pin
from utime import sleep_ms

led = Pin(13, Pin.OUT)

while True:
    led.value(1)
    sleep_ms(500)
    led.value(0)
    sleep_ms(500)

pymcu build   # → dist/firmware.hex  (150 bytes flash, 0 bytes SRAM)
pymcu flash   # → avrdude upload to Arduino Uno

pipx install --pip-args=--pre "pymcu-compiler[avr]"    # AVR (ATmega / ATtiny)   -- beta
pipx install --pip-args=--pre "pymcu-compiler[arm]"    # RP2040 / RP2350 (Pico)  -- alpha
pipx install --pip-args=--pre "pymcu-compiler[pic]"    # PIC16                   -- alpha
pipx install --pip-args=--pre "pymcu-compiler[all]"    # all of the above

Requires Python 3.11+ and pipx. Each extra bundles its full toolchain (compiler backend + assembler/linker binaries) — no system packages needed.

The extras are not equally mature. [avr] is beta; [arm] and [pic] are alpha, and [all] installs alpha backends alongside the beta one. See Supported targets for what alpha means here.

Package name: PyMCU is published as pymcu-compiler on PyPI while a PEP 541 request to reclaim the pymcu name is under review. Once approved, a pymcu metapackage will alias pymcu-compiler — installs and project configs will stay compatible.

pymcu new blink --board arduino_uno --stdlib micropython
cd blink

That is the whole setup. pymcu new scaffolds a project that already builds: a pyproject.toml carrying the board, frequency, toolchain and dependencies, a src/main.py with a working blink, plus requirements.txt, a Makefile and VS Code tasks. Pass --stdlib circuitpython for the other API, or run it with no flags and it asks for what you left out.

MicroPython style (--stdlib micropython):

# src/main.py
from machine import Pin
from time import sleep_ms

led = Pin(13, Pin.OUT)
while True:
    led.value(1)
    sleep_ms(500)
    led.value(0)
    sleep_ms(500)

CircuitPython style (--stdlib circuitpython):

# src/main.py
import board
import digitalio
import time

led = digitalio.DigitalInOut(board.LED)
led.direction = digitalio.Direction.OUTPUT
while True:
    led.value = True
    time.sleep(0.5)
    led.value = False
    time.sleep(0.5)

Both compile to bare-metal firmware for the same chip. The Quick Start walks the same path in more detail, including what each scaffolded file is for.

pymcu build
# Compiling src/main.py...
# → dist/firmware.hex

pymcu flash --port /dev/cu.usbmodem*
# avrdude: flash verified

Build against a compatibility layer, not against pymcu.hal.*.

The beta label covers the compiler frontend and the AVR backend. It is not a promise about every API those two can reach, and the difference between the three rows above matters:

• pymcu-circuitpython and pymcu-micropython are the surfaces designed to hold still, because they do not define their own shape: they track digitalio / board and machine / utime as specified by CircuitPython and MicroPython. That is a reason you can check, not a guarantee we have earned yet, and both packages are still pre-1.0.
• pymcu.hal.* is deliberately low-level, it is the layer being actively reshaped, and it may change between releases without a deprecation cycle. Reach for it when you need direct register access, @interrupt, asm() or @extern, and expect to revisit that code.

All three are deepest on the ATmega parts. board.* in particular is defined for the Arduino boards but not for ATtiny or for the RP2040 / RP2350, where you pass the pin number instead (digitalio.DigitalInOut(25)). On the alpha backends a compat call may resolve to a HAL module that does not implement it yet; the compiler says so at build time rather than emitting silently wrong code.

Not every backend is at the same maturity. The compiler frontend and the AVR backend are beta as of 0.1.0b1. ARM, PIC and RISC-V remain alpha.

What the labels mean.

• beta: the language surface below is implemented and test-covered on this backend, and it is validated on real silicon (Arduino Uno, logic analyzer). The label covers the compiler frontend and the AVR backend, not the stability of every API you can reach through them: see Choosing an API for which surface to build against.
• alpha: it builds and it runs, but parts of the language surface below are missing on this backend, it does not carry AVR's continuous silicon validation, and the API may change between releases. Specifically today: list[T] is AVR-only; try / except is unavailable on PIC; float, f-strings, generators and @interrupt are unavailable on PIC16 (PIC18 has float and generators); and PIC16F84A / PIC16F877A builds emit no configuration word, so the resulting image will not boot on real hardware until you program the fuses yourself. See Language Limitations.

How far each backend has been validated on real hardware. This is the part that most separates beta from alpha, so it is worth stating per backend rather than in one sentence:

RISC-V (CH32V003/V203) has a working backend in-tree but is not published on PyPI and has no install extra, so a pip/pipx install never provides it.

Drivers: DHT11, DS18B20, HD44780 LCD, SSD1306 OLED, MAX7219 8x8 matrix, BMP280, WS2812 NeoPixel.

PyMCU accepts Python syntax but enforces a strict compile-time type system.

The list below describes the AVR backend, which is the beta one. Items marked (AVR only) or with an explicit backend list are not available everywhere. See Supported targets.

Supported:

• Integer types: uint8, int8, uint16, int16, uint32, int32 — with type inference for unannotated def parameters and returns
• float (IEEE-754 single) on AVR, ARM and PIC18; PIC16 has no floating point at all
• Fixed arrays buf: uint8[16] and bytearray everywhere; heap-bounded lists x: list[uint8] = list() (AVR only); on ARM and PIC, use a fixed array
• Slices: equal-length assignment (including through __setitem__, so microcontroller.nvm[0:4] = b"..." compiles) and iteration with runtime bounds (for b in buf[0:n])
• print() of a bytearray or a slice as the CPython repr, and of a float with two rounded decimals; s = "".join([chr(b) for b in buf]) for bytes-to-string
• for, while, if, match / case, with, class, @inline, lambda
• Generators (yield) on AVR, ARM and PIC18; async / await with asyncio.run / gather on AVR, ARM and PIC18, both unavailable on PIC16
• dict / set literals as closed compile-time lookup tables, plus pymcu.collections.FixedDict for mutable fixed-capacity maps — still no heap
• f-strings with runtime interpolations and format specs, as stream writes or values (AVR and ARM only: PIC and RISC-V have no string-building path)
• try / except / raise / finally with cross-function propagation (AVR and ARM); on PIC, use return codes, since only the ZeroDivisionError guard exists there
• @interrupt ISR handlers (not on PIC16), asm("...") inline assembly everywhere (with operands on ARM)
• CircuitPython and MicroPython compat packages, plus pymcu lint to vet a port

Not supported:

• Open-ended dict / set mutation beyond FixedDict's fixed capacity (no heap hash tables)
• Closures capturing mutable variables — use explicit parameters
• *args / **kwargs, reflection (getattr / setattr / eval)
• Anything whose size is only known at runtime: a slice read bound to a name (b = buf[0:n]), a runtime tuple, a comprehension filtered on a runtime condition

The compiler rejects unsupported features with a clear error at compile time — including the ones the hardware cannot honour, such as a runtime pin number, an image larger than the chip's flash, or static data that does not fit in SRAM. See the Language Limitations page for the full list.

• Python on a Classic Uno on Arduino Project Hub — why the board that taught millions of us electronics never got to speak Python, and what changes once the interpreter is gone.

If PyMCU saves you time, consider sponsoring the project. The goal is $300/month, which covers the AI tooling, domains and hosting that keep development at its current pace. Sponsors at $10/month and above are listed in SPONSORS.md.

Sponsor on GitHub

PyMCU is built by one person, and these are the people helping keep it going.

Adafruit, the home of CircuitPython, sponsors PyMCU on GitHub. Thank you, pt and ladyada.

All components are licensed under the MIT License. Your compiled firmware output is entirely yours — no runtime license, no attribution required.

See CONTRIBUTING.md and LANGUAGE_ROADMAP.md.

Special thanks to Richard Wardlow, creator of the original pyMCU project (2012). See CREDITS.md for the full acknowledgement.