Installation

Note

Alpha release — PyMCU is currently in alpha (0.1.0a1). By default, pip, uv and pipx do not install pre-releases unless you pass a --pre flag. The commands on this page include the required flags. Once 0.1.0 stable ships, --pre will not be needed.

Option 1 — pip (recommended)

pymcu-compiler is distributed on PyPI. Install it with pip or uv:

uv (recommended)

uv tool install --pre pymcu-compiler

uv tool install places the pymcu command on your PATH globally, isolated in its own virtual environment. No activation step needed.

Requires uv 0.11 or newer — run uv self update if you are on an older version.

pipx

pipx install pymcu-compiler --pip-args="--pre"

pipx installs into an isolated environment and puts pymcu on your PATH.

pip

pip install --pre pymcu-compiler

Verify:

pymcu --version
# pymcu-compiler, version 0.1.0a1.post0

Compat layer extras

Install optional MicroPython or CircuitPython compatibility packages alongside pymcu-compiler:

# MicroPython compat (machine, utime, micropython modules)
pip install pymcu-micropython

# CircuitPython compat (board, digitalio, busio, neopixel, …)
pip install pymcu-circuitpython

RP2040 / ARM backend (alpha)

Note

The compiler frontend and the AVR backend are beta as of 0.1.0b1; ARM and PIC remain alpha: they build and run, but parts of the language surface are missing on them, they do not carry AVR’s continuous silicon validation, and their APIs may change between releases.

No backend is built in: pymcu-compiler on its own installs the driver and the stdlib, and every backend arrives through an extra ([avr], [arm], [pic], or [all]). To compile for the Raspberry Pi Pico (RP2040), install the ARM backend — it registers the rp2040 target, toolchain and programmer with the compiler via entry points:

uv

uv tool install --pre "pymcu-compiler[arm]"

pipx

pipx install "pymcu-compiler[arm]" --pip-args="--pre"

pip

pip install --pre "pymcu-compiler[arm]"

Or if pymcu-compiler is already installed:

pip install --pre pymcu-arm

This backend lowers PyMCU’s IR to LLVM IR (thumbv6m-none-eabi, Cortex-M0+) and drives an LLVM toolchain (opt → llc → ld.lld → llvm-objcopy). On Linux x64/arm64, Windows x64 and macOS arm64 the prebuilt pymcu-arm-toolchain wheel is pulled in automatically. On other platforms, install a system LLVM instead:

brew install llvm lld        # macOS
sudo apt install llvm lld    # Debian/Ubuntu

RP2040 support is alpha — GPIO + UART0 on a single core. See Language Limitations for the exact scope and Raspberry Pi Pico (RP2040) for runnable programs.

---

Option 3 — Build from source

For contributors or anyone who wants to run the latest development build.

Requirements

• .NET 10 SDK

• Python 3.11 or newer

• uv (recommended)

• avrdude (for flashing — see below)

Steps

git clone https://github.com/pymcu/pymcu.git
cd pymcu

# Build the C# compiler and AVR backend
dotnet publish src/compiler/PyMCU.csproj -c Release -o build/bin --nologo
dotnet publish extensions/pymcu-avr/src/csharp/cli/PyMCU.AVR.csproj -c Release -o build/bin --nologo

# Set up Python environment
uv venv && source .venv/bin/activate
uv sync
just sync-stdlib   # editable stdlib (uv pip install --no-deps -e lib/); edits are then live
pip install -e src/driver

Verify:

pymcu --version
# pymcu-compiler, version 0.1.0a1

---

Flash the firmware

Compiling produces dist/firmware.hex. Flashing to an Arduino Uno requires avrdude installed on your host machine.

macOS

brew install avrdude

Linux (Debian/Ubuntu)

sudo apt-get install avrdude

Windows

Download from the AVRDUDE releases page.

Then use pymcu flash (which calls avrdude internally):

pymcu flash --port /dev/cu.usbmodem*   # macOS
pymcu flash --port /dev/ttyACM0        # Linux
pymcu flash --port COM3                # Windows

Or call avrdude directly:

avrdude -c arduino -p atmega328p -P /dev/ttyACM0 -b 115200 \
        -U flash:w:dist/firmware.hex:i

---

Next steps

• Quick Start — create your first project and flash an LED