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 2 — Docker image

Pre-built images are published to GitHub Container Registry for every release. Docker is useful for CI pipelines or environments where you cannot install Python tools.

Flavor	Image	Stdlib included
base	ghcr.io/pymcu/pymcu:latest	Bare-metal PyMCU stdlib
micropython	ghcr.io/pymcu/pymcu:micropython	+ machine, utime, micropython compat
circuitpython	ghcr.io/pymcu/pymcu:circuitpython	+ board, digitalio, analogio, pwmio compat

docker pull ghcr.io/pymcu/pymcu:latest

Mount your project and run pymcu build:

docker run --rm \
    -v "$(pwd):/workspace" \
    ghcr.io/pymcu/pymcu:latest \
    sh -c "cd /workspace && pymcu build"

---

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
rsync -av lib/src/pymcu/ .venv/lib/python3.*/site-packages/pymcu/
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