pymcu-compiler

Pre-release

This release is a pre-release and may not be stable for production use.

PyMCU

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

Report a bug · Request a feature · Sponsor

[!IMPORTANT] Alpha 3 is out — v0.1.0a3 release notes. The language grows generators, async/await, dict/set literals, f-strings as values and type inference; the ARM targets (RP2040 / RP2350) reach feature parity with AVR — exceptions, floats, WiFi; and a brand-new PIC backend joins the family. Core compilation is stable and test-covered, but rough edges remain in error messages and tooling — 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 firmware for AVR, ARM (RP2040 / RP2350) and PIC — 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.

Source	Total flash	SRAM
C (`avr-gcc -Os`)	176 B	0 B
PyMCU (native HAL)	162 B	0 B
PyMCU (MicroPython API)	162 B	0 B
PyMCU (CircuitPython API)	164 B	0 B
Arduino (IDE defaults)	~1 024 B	9 B

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
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)

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 --pip-args=--pre "pymcu-compiler[avr]"    # AVR (ATmega / ATtiny)
pipx install --pip-args=--pre "pymcu-compiler[arm]"    # RP2040 / RP2350 (Pico / Pico 2)
pipx install --pip-args=--pre "pymcu-compiler[pic]"    # PIC16
pipx install --pip-args=--pre "pymcu-compiler[all]"    # everything

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

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[avr]", "pymcu-circuitpython"]

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

# 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)

MicroPython style — add pymcu-micropython to dependencies:

# pyproject.toml
[project]
dependencies = ["pymcu-compiler[avr]", "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

Package	API surface	Install
`pymcu-circuitpython`	`digitalio`, `analogio`, `busio`, `pwmio`, `time`, `board`, `neopixel`	`pip install pymcu-circuitpython`
`pymcu-micropython`	`machine` (Pin/UART/ADC/PWM/SPI/I2C/Timer/WDT), `utime`	`pip install pymcu-micropython`
`pymcu.hal.*`	Direct register-level HAL — lowest overhead	`pymcu-stdlib` (installed automatically with `pymcu-compiler`)

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

Architecture	Chips
AVR (ATmega)	ATmega48/88/168/328P, ATmega2560, ATmega32U4
AVR (ATtiny)	ATtiny25/45/85, ATtiny24/44/84, ATtiny13/13A, ATtiny2313/4313
ARM (Cortex-M0+ / M33)	RP2040 (Pico / Pico W), RP2350 (Pico 2 / Pico 2 W) — incl. PIO and CYW43 WiFi
PIC (mid-range)	PIC16F84A, PIC16F877A — new in alpha 3

HAL coverage (ATmega328P / Arduino Uno)

Module	Features
`pymcu.hal.gpio`	`Pin` — high / low / toggle / irq / pulse_in
`pymcu.hal.uart`	`UART` — write / read / println / RX interrupt
`pymcu.hal.adc`	`AnalogPin` — poll + interrupt; internal temperature
`pymcu.hal.timer`	`Timer(n, prescaler)` — CTC mode; `millis()` / `micros()`
`pymcu.hal.pwm`	`PWM` — multi-channel; `set_duty` / `set_freq`
`pymcu.hal.spi`	`SPI` + `SoftSPI`
`pymcu.hal.i2c`	`I2C` + `SoftI2C`
`pymcu.hal.eeprom`	`EEPROM` — `write(addr, val)` / `read(addr)`
`pymcu.hal.watchdog`	`Watchdog` — `enable` / `disable` / `feed`
`pymcu.hal.power`	`sleep_idle` / `sleep_adc_noise` / `sleep_power_down` / `sleep_power_save` / `sleep_standby` / `sleep_extended_standby`

Drivers: DHT11, DS18B20, HD44780 LCD, SSD1306 OLED, MAX7219 8x8 matrix, 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 — with type inference for unannotated def parameters and returns
Fixed arrays buf: uint8[16], heap-bounded lists x: list[uint8] = list(), equal-length slice assignment
for, while, if, match / case, with, class, @inline, lambda
Generators (yield), async / await with asyncio.run / gather
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
try / except / raise / finally with cross-function propagation (AVR and ARM)
@interrupt ISR handlers, asm("...") inline assembly (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)

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

CLI reference

Command	Description
`pymcu new <name>`	Scaffold a new project
`pymcu build`	Compile `src/` → `dist/firmware.hex`
`pymcu flash`	Upload via avrdude
`pymcu clean`	Remove build artifacts

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.

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distributions

No source distribution files available for this release.See tutorial on generating distribution archives.

Built Distributions

If you're not sure about the file name format, learn more about wheel file names.

The dropdown lists show the available interpreters, ABIs, and platforms. Enable javascript to be able to filter the list of wheel files.

pymcu_compiler-0.1.0a4-py3-none-win_arm64.whl (2.6 MB view details)

Uploaded Aug 2, 2026 Python 3Windows ARM64

pymcu_compiler-0.1.0a4-py3-none-win_amd64.whl (2.8 MB view details)

Uploaded Aug 2, 2026 Python 3Windows x86-64

pymcu_compiler-0.1.0a4-py3-none-manylinux_2_17_x86_64.whl (2.9 MB view details)

Uploaded Aug 2, 2026 Python 3manylinux: glibc 2.17+ x86-64

pymcu_compiler-0.1.0a4-py3-none-manylinux_2_17_aarch64.whl (2.8 MB view details)

Uploaded Aug 2, 2026 Python 3manylinux: glibc 2.17+ ARM64

pymcu_compiler-0.1.0a4-py3-none-macosx_26_0_arm64.whl (2.7 MB view details)

Uploaded Aug 2, 2026 Python 3macOS 26.0+ ARM64

pymcu_compiler-0.1.0a4-py3-none-macosx_13_0_x86_64.whl (2.9 MB view details)

Uploaded Aug 2, 2026 Python 3macOS 13.0+ x86-64

File details

Details for the file pymcu_compiler-0.1.0a4-py3-none-win_arm64.whl.

File metadata

Download URL: pymcu_compiler-0.1.0a4-py3-none-win_arm64.whl
Upload date: Aug 2, 2026
Size: 2.6 MB
Tags: Python 3, Windows ARM64
Uploaded using Trusted Publishing? Yes
Uploaded via: twine/7.0.0 CPython/3.13.14

File hashes

Hashes for pymcu_compiler-0.1.0a4-py3-none-win_arm64.whl
Algorithm	Hash digest
SHA256	`34babcf352ece709417dcb8066da1b77f8a990f5cfe83639d61e81e52783973b`
MD5	`9e5374853302e55c45f3420bed0e9210`
BLAKE2b-256	`b3966c12066d6d214ab317b094160f12d1a9aaad099ac041ac379b4c420e1c96`

See more details on using hashes here.

Provenance

The following attestation bundles were made for pymcu_compiler-0.1.0a4-py3-none-win_arm64.whl:

Publisher: publish.yml on PyMCU/PyMCU

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

Statement:
- Statement type: https://in-toto.io/Statement/v1
- Predicate type: https://docs.pypi.org/attestations/publish/v1
- Subject name: pymcu_compiler-0.1.0a4-py3-none-win_arm64.whl
- Subject digest: 34babcf352ece709417dcb8066da1b77f8a990f5cfe83639d61e81e52783973b
- Sigstore transparency entry: 2318956064
- Sigstore integration time: Aug 2, 2026
Source repository:
- Permalink: PyMCU/PyMCU@4d08657d176548e00f0c4e451dd6d4208f8aea72
- Branch / Tag: refs/tags/v0.1.0a4
- Owner: https://github.com/PyMCU
- Access: public
Publication detail:
- Token Issuer: https://token.actions.githubusercontent.com
- Runner Environment: github-hosted
- Publication workflow: publish.yml@4d08657d176548e00f0c4e451dd6d4208f8aea72
- Trigger Event: release

File details

Details for the file pymcu_compiler-0.1.0a4-py3-none-win_amd64.whl.

File metadata

Download URL: pymcu_compiler-0.1.0a4-py3-none-win_amd64.whl
Upload date: Aug 2, 2026
Size: 2.8 MB
Tags: Python 3, Windows x86-64
Uploaded using Trusted Publishing? Yes
Uploaded via: twine/7.0.0 CPython/3.13.14

File hashes

Hashes for pymcu_compiler-0.1.0a4-py3-none-win_amd64.whl
Algorithm	Hash digest
SHA256	`9f894543f86fb55fabc9901e2fdd58fceae3aa0deb724b6435fa059440876878`
MD5	`c681d3d07df58f40edf935bcbe738466`
BLAKE2b-256	`12da5dc4ff67c06c6156f35d29e86b0139e65ab06439fbb20d9a0a686c65c684`

See more details on using hashes here.

Provenance

The following attestation bundles were made for pymcu_compiler-0.1.0a4-py3-none-win_amd64.whl:

Publisher: publish.yml on PyMCU/PyMCU

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

Statement:
- Statement type: https://in-toto.io/Statement/v1
- Predicate type: https://docs.pypi.org/attestations/publish/v1
- Subject name: pymcu_compiler-0.1.0a4-py3-none-win_amd64.whl
- Subject digest: 9f894543f86fb55fabc9901e2fdd58fceae3aa0deb724b6435fa059440876878
- Sigstore transparency entry: 2318954306
- Sigstore integration time: Aug 2, 2026
Source repository:
- Permalink: PyMCU/PyMCU@4d08657d176548e00f0c4e451dd6d4208f8aea72
- Branch / Tag: refs/tags/v0.1.0a4
- Owner: https://github.com/PyMCU
- Access: public
Publication detail:
- Token Issuer: https://token.actions.githubusercontent.com
- Runner Environment: github-hosted
- Publication workflow: publish.yml@4d08657d176548e00f0c4e451dd6d4208f8aea72
- Trigger Event: release

File details

Details for the file pymcu_compiler-0.1.0a4-py3-none-manylinux_2_17_x86_64.whl.

File metadata

Download URL: pymcu_compiler-0.1.0a4-py3-none-manylinux_2_17_x86_64.whl
Upload date: Aug 2, 2026
Size: 2.9 MB
Tags: Python 3, manylinux: glibc 2.17+ x86-64
Uploaded using Trusted Publishing? Yes
Uploaded via: twine/7.0.0 CPython/3.13.14

File hashes

Hashes for pymcu_compiler-0.1.0a4-py3-none-manylinux_2_17_x86_64.whl
Algorithm	Hash digest
SHA256	`7e5875489247834019c36f7ba35e51120ed7d5961b6c04d8e4acde9ef769f49a`
MD5	`f39024accc0c3e09407be2df8af8a4c2`
BLAKE2b-256	`12cbce45ffddee1bad8efacf45d4b94cef53fafeb55a6fe7a7d5b1d85d88e2a2`

See more details on using hashes here.

Provenance

The following attestation bundles were made for pymcu_compiler-0.1.0a4-py3-none-manylinux_2_17_x86_64.whl:

Publisher: publish.yml on PyMCU/PyMCU

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

Statement:
- Statement type: https://in-toto.io/Statement/v1
- Predicate type: https://docs.pypi.org/attestations/publish/v1
- Subject name: pymcu_compiler-0.1.0a4-py3-none-manylinux_2_17_x86_64.whl
- Subject digest: 7e5875489247834019c36f7ba35e51120ed7d5961b6c04d8e4acde9ef769f49a
- Sigstore transparency entry: 2318955145
- Sigstore integration time: Aug 2, 2026
Source repository:
- Permalink: PyMCU/PyMCU@4d08657d176548e00f0c4e451dd6d4208f8aea72
- Branch / Tag: refs/tags/v0.1.0a4
- Owner: https://github.com/PyMCU
- Access: public
Publication detail:
- Token Issuer: https://token.actions.githubusercontent.com
- Runner Environment: github-hosted
- Publication workflow: publish.yml@4d08657d176548e00f0c4e451dd6d4208f8aea72
- Trigger Event: release

File details

Details for the file pymcu_compiler-0.1.0a4-py3-none-manylinux_2_17_aarch64.whl.

File metadata

Download URL: pymcu_compiler-0.1.0a4-py3-none-manylinux_2_17_aarch64.whl
Upload date: Aug 2, 2026
Size: 2.8 MB
Tags: Python 3, manylinux: glibc 2.17+ ARM64
Uploaded using Trusted Publishing? Yes
Uploaded via: twine/7.0.0 CPython/3.13.14

File hashes

Hashes for pymcu_compiler-0.1.0a4-py3-none-manylinux_2_17_aarch64.whl
Algorithm	Hash digest
SHA256	`48a55152cfc044f7b25d1583aaf26ac0ad3e82f9c4db7fff6131fb73555505be`
MD5	`7dd4ddfdcb5bc213ed527f2e353698bb`
BLAKE2b-256	`f82d43f9e6a7b74cbcedc2f7b160a0a0fe7fe8fcb10880addcce78cfc42fa92e`

See more details on using hashes here.

Provenance

The following attestation bundles were made for pymcu_compiler-0.1.0a4-py3-none-manylinux_2_17_aarch64.whl:

Publisher: publish.yml on PyMCU/PyMCU

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

Statement:
- Statement type: https://in-toto.io/Statement/v1
- Predicate type: https://docs.pypi.org/attestations/publish/v1
- Subject name: pymcu_compiler-0.1.0a4-py3-none-manylinux_2_17_aarch64.whl
- Subject digest: 48a55152cfc044f7b25d1583aaf26ac0ad3e82f9c4db7fff6131fb73555505be
- Sigstore transparency entry: 2318955444
- Sigstore integration time: Aug 2, 2026
Source repository:
- Permalink: PyMCU/PyMCU@4d08657d176548e00f0c4e451dd6d4208f8aea72
- Branch / Tag: refs/tags/v0.1.0a4
- Owner: https://github.com/PyMCU
- Access: public
Publication detail:
- Token Issuer: https://token.actions.githubusercontent.com
- Runner Environment: github-hosted
- Publication workflow: publish.yml@4d08657d176548e00f0c4e451dd6d4208f8aea72
- Trigger Event: release

File details

Details for the file pymcu_compiler-0.1.0a4-py3-none-macosx_26_0_arm64.whl.

File metadata

Download URL: pymcu_compiler-0.1.0a4-py3-none-macosx_26_0_arm64.whl
Upload date: Aug 2, 2026
Size: 2.7 MB
Tags: Python 3, macOS 26.0+ ARM64
Uploaded using Trusted Publishing? Yes
Uploaded via: twine/7.0.0 CPython/3.13.14

File hashes

Hashes for pymcu_compiler-0.1.0a4-py3-none-macosx_26_0_arm64.whl
Algorithm	Hash digest
SHA256	`17a6f4132ea23a4e43e827cf944b1c3a0c019c0bbaa3c2f17f242cae0bf19e5b`
MD5	`d444a7a63b1288185c08b9049d1996b8`
BLAKE2b-256	`ce180d346a7fe4bf8dccd57ded0d8664849c57fde73362aec51388d37c3065de`

See more details on using hashes here.

Provenance

The following attestation bundles were made for pymcu_compiler-0.1.0a4-py3-none-macosx_26_0_arm64.whl:

Publisher: publish.yml on PyMCU/PyMCU

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

Statement:
- Statement type: https://in-toto.io/Statement/v1
- Predicate type: https://docs.pypi.org/attestations/publish/v1
- Subject name: pymcu_compiler-0.1.0a4-py3-none-macosx_26_0_arm64.whl
- Subject digest: 17a6f4132ea23a4e43e827cf944b1c3a0c019c0bbaa3c2f17f242cae0bf19e5b
- Sigstore transparency entry: 2318956364
- Sigstore integration time: Aug 2, 2026
Source repository:
- Permalink: PyMCU/PyMCU@4d08657d176548e00f0c4e451dd6d4208f8aea72
- Branch / Tag: refs/tags/v0.1.0a4
- Owner: https://github.com/PyMCU
- Access: public
Publication detail:
- Token Issuer: https://token.actions.githubusercontent.com
- Runner Environment: github-hosted
- Publication workflow: publish.yml@4d08657d176548e00f0c4e451dd6d4208f8aea72
- Trigger Event: release

File details

Details for the file pymcu_compiler-0.1.0a4-py3-none-macosx_13_0_x86_64.whl.

File metadata

Download URL: pymcu_compiler-0.1.0a4-py3-none-macosx_13_0_x86_64.whl
Upload date: Aug 2, 2026
Size: 2.9 MB
Tags: Python 3, macOS 13.0+ x86-64
Uploaded using Trusted Publishing? Yes
Uploaded via: twine/7.0.0 CPython/3.13.14

File hashes

Hashes for pymcu_compiler-0.1.0a4-py3-none-macosx_13_0_x86_64.whl
Algorithm	Hash digest
SHA256	`43f3eeee83a049b67f5a121700d2ff9966d6b38e472f5dd6724e443345e79731`
MD5	`20c533bae3c5d893e8939590bbdf4408`
BLAKE2b-256	`0a84e10f0481cb9bcaa85d002ab1f2045a55c4b69d696ddba832e9d02711f2d1`

See more details on using hashes here.

Provenance

The following attestation bundles were made for pymcu_compiler-0.1.0a4-py3-none-macosx_13_0_x86_64.whl:

Publisher: publish.yml on PyMCU/PyMCU

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

Statement:
- Statement type: https://in-toto.io/Statement/v1
- Predicate type: https://docs.pypi.org/attestations/publish/v1
- Subject name: pymcu_compiler-0.1.0a4-py3-none-macosx_13_0_x86_64.whl
- Subject digest: 43f3eeee83a049b67f5a121700d2ff9966d6b38e472f5dd6724e443345e79731
- Sigstore transparency entry: 2318955781
- Sigstore integration time: Aug 2, 2026
Source repository:
- Permalink: PyMCU/PyMCU@4d08657d176548e00f0c4e451dd6d4208f8aea72
- Branch / Tag: refs/tags/v0.1.0a4
- Owner: https://github.com/PyMCU
- Access: public
Publication detail:
- Token Issuer: https://token.actions.githubusercontent.com
- Runner Environment: github-hosted
- Publication workflow: publish.yml@4d08657d176548e00f0c4e451dd6d4208f8aea72
- Trigger Event: release