pymcu-avr-toolchain

Pre-built AVR-GCC toolchain for the PyMCU AVR (ATmega/ATtiny) backend.

The AVR backend compiles PyMCU's architecture-agnostic IR to AVR assembly and then invokes three core tools to produce a flashable Intel HEX file:

avr-gcc   avr-as   avr-objcopy

(Full toolchain also includes avr-g++, avr-ld, avr-ar, avr-objdump, avr-size, avr-gdb, and avr-libc.)

This package is the AVR counterpart of pymcu-rp2040-toolchain: a platform-specific wheel whose only job is to ship those tools so that pip install pymcu-compiler[avr] is fully self-contained — no separate avr-gcc installation required on supported platforms.

The build script (avr-gcc-build.sh) is based on the work of Zak Kemble.

License: GPL-3.0-or-later packaging + binaries

The bundled AVR-GCC toolchain is derived from GCC and Binutils, which are licensed under GPL-3.0-or-later and LGPL-3.0-or-later respectively. avr-libc is BSD-2-Clause. Because the wheel bundles GPL code, the package as a whole is distributed under GPL-3.0-or-later.

• The GPL applies to the toolchain binaries themselves, not to the firmware your projects compile with them. Firmware produced by avr-gcc is your own work and carries no GPL obligation.
• Contrast with RP2040: pymcu-rp2040-toolchain bundles LLVM, which is Apache-2.0 WITH LLVM-exception (permissive, no copyleft). The isolation mechanism is the same — a separate optional package — but the license differs because the upstream compilers differ.

See LICENSES/ and NOTICE for the full texts.

Bundled versions

Installation

pip install pymcu-avr-toolchain

avr-gcc + avr-libc together exceed PyPI's 100 MB per-file ceiling (~150 MB per platform). The distribution is therefore split:

The binary wheel is downloaded automatically. The first call to get_bin_dir() (or any PyMCU build that needs the toolchain) downloads the correct wheel for your platform from GitHub Releases and extracts it to the shared cache at ~/.pymcu/tools/. Subsequent calls are instant.

import pymcu_avr_toolchain
bin_dir = pymcu_avr_toolchain.get_bin_dir()   # downloads on first call

For CI or air-gapped environments, set PYMCU_AVR_WHEEL_URL to override the download URL, or install the binary wheel directly:

# Linux x86-64
pip install https://github.com/PyMCU/avr-gcc-build/releases/download/v15.2.0.post5/pymcu_avr_toolchain-15.2.0.post5-py3-none-manylinux_2_17_x86_64.whl

# Linux arm64 (best-effort build)
pip install https://github.com/PyMCU/avr-gcc-build/releases/download/v15.2.0.post5/pymcu_avr_toolchain-15.2.0.post5-py3-none-manylinux_2_17_aarch64.whl

# macOS Apple Silicon
pip install https://github.com/PyMCU/avr-gcc-build/releases/download/v15.2.0.post5/pymcu_avr_toolchain-15.2.0.post5-py3-none-macosx_14_0_arm64.whl

# Windows x86-64
pip install https://github.com/PyMCU/avr-gcc-build/releases/download/v15.2.0.post5/pymcu_avr_toolchain-15.2.0.post5-py3-none-win_amd64.whl

System toolchain (alternative)

If you already have avr-gcc installed, the AvrToolchain driver finds the tools automatically via PATH — no package needed:

# macOS
brew tap osx-cross/avr && brew install avr-gcc

# Debian/Ubuntu
apt install gcc-avr binutils-avr avr-libc

Linux arm64: Built on GitHub's ubuntu-24.04-arm runner. The build script was designed for Linux x64; the arm64 build is best-effort (continue-on-error) and may be absent from a release if the runner fails.

macOS Intel (x86-64): The osx-cross/avr tap does not provide x86-64 bottles for avr-gcc, so no Intel wheel is published.

How the driver resolves tools

AvrToolchain (in pymcu-avr) checks these sources in order:

A missing wheel never blocks a developer who already has avr-gcc installed.

Inspecting installed tools

pymcu-avr-toolchain-info     # entry-point
python -m pymcu_avr_toolchain

For maintainers: publishing a new wheel

Release process

1. Update VER_GCC, VER_BINUTILS, VER_GDB in avr-gcc-build.sh and version in python/pyproject.toml.
2. Tag and push:

   git tag v15.2.0
   git push origin v15.2.0
   

3. The build-wheels.yml workflow fires automatically:
   • Builds one binary wheel per platform (Linux x64 from source ~2 h, Linux arm64 best-effort, macOS via Homebrew, Windows via MSYS2).
   • Binary wheels → GitHub Releases (too large for PyPI's 100 MB limit).
   • PyPI receives only the pure-Python sdist stub.
   • publish-pypi uses OIDC trusted publishing (no stored token required).

Required GitHub configuration

Building a wheel locally

AVRT_TOOLCHAIN_DIR=build/avr-gcc-15.2.0-x64-linux \
WHEEL_PLATFORM_TAG=manylinux_2_17_x86_64 \
uv build --wheel python/

Environment variables

Version history