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)

AVR support is built in. 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