pymcu-compiler 0.1.0a3

PyMCU

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

Report a bug · Request a feature · Sponsor

[!IMPORTANT] Alpha — v0.1 — under active development. Core AVR compilation is stable and test-covered, but rough edges remain in error messages and tooling. Stability is expected for the supported feature set — if you hit a bug, please open an issue, it helps a lot.

Avoid pymcu.hal.* during the alpha — the native HAL API may change between releases. Use the MicroPython or CircuitPython compat API instead; those are stable and community-specified.

PyMCU compiles a statically-typed subset of Python into bare-metal AVR firmware — no runtime, no interpreter, no virtual machine. The same binary you would write in C.

The pitch in one table

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 delay loop PyMCU generates happens to use one fewer padding instruction than the loop avr-gcc -Os emits for this particular pattern. 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.

Write code you already know

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

CircuitPython

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

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

while True:
    led.value = True
    sleep_ms(500)
    led.value = False
    sleep_ms(500)

MicroPython

# 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  (56 bytes flash, 0 bytes SRAM)
pymcu flash   # → avrdude upload to Arduino Uno

First binary in under 5 minutes

1. Install

pipx install "pymcu-compiler[avr]"

Requires Python 3.11+ and pipx. The [avr] extra includes the AVR toolchain.

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.

2. Create a project

pymcu new blink
cd blink

3. Choose your API and write the program

CircuitPython style — add pymcu-circuitpython to dependencies:

# pyproject.toml
[project]
dependencies = ["pymcu-compiler", "pymcu-circuitpython"]

[tool.pymcu]
board     = "arduino_uno"
frequency = 16000000

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

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

while True:
    led.value = True
    sleep_ms(500)
    led.value = False
    sleep_ms(500)

MicroPython style — add pymcu-micropython to dependencies:

# pyproject.toml
[project]
dependencies = ["pymcu-compiler", "pymcu-micropython"]

[tool.pymcu]
board     = "arduino_uno"
frequency = 16000000

# src/main.py
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)

4. Build and flash

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

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

Choosing an API

Start with MicroPython or CircuitPython — they are stable, community-specified, and backed by real hardware compatibility guarantees. The pymcu.hal.* native HAL is functional but its API may change between alpha releases — avoid it unless you need direct register access not yet covered by the compat layers.

Supported targets

HAL coverage (ATmega328P / Arduino Uno)

Drivers: DHT11, DS18B20, LM35, HD44780 LCD, SSD1306 OLED, MAX7219, BMP280, WS2812 NeoPixel.

What Python features are supported

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

Supported:

• Integer types: uint8, int8, uint16, int16, uint32, int32, float
• Fixed arrays buf: uint8[16] and heap-bounded lists x: list[uint8] = list()
• for, while, if, match / case, with, class, @inline, lambda
• @interrupt ISR handlers, asm("...") inline assembly
• try / except / raise / finally (AVR only; raise and except in same function)
• CircuitPython and MicroPython compat packages

Not supported:

• dict / set (hash tables require heap)
• Runtime f"value={x}" with non-constant expressions (compile-time constants only)
• async / await — use @interrupt + polling loop instead
• Closures capturing mutable variables — use explicit parameters
• *args / **kwargs

The compiler rejects unsupported features with a clear error at compile time. See the Language Limitations page for the full list.

CLI reference

Sustainability

Post-alpha development will be slower and community-driven. If PyMCU saves you time, consider sponsoring the project — the goal is $200-300/month to cover the AI tooling costs that made this first release possible and keep active development going.

Sponsor on GitHub

License

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

Contributing

See CONTRIBUTING.md and LANGUAGE_ROADMAP.md.

Credits

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