CircuitPython Turbo: Go Blinka!

Compile the busy parts. Keep building in Python.

by phillip torrone

published September 11, 2026, last edited September 16, 2026

posted in CircuitPython Programming Raspberry Pi/ RP2040

Save Download

New

Intermediate

Skill guide

Try Turbo

Download, flash, and try Turbo

Turbo support is now included in the latest official CircuitPython builds for RP2040 and RP2350 boards. Download the UF2 for your board, flash it, and the firmware is ready to run compiled Turbo modules. You do not need to build custom firmware for this example.

Start with the ready-to-copy Blinka art demo on an Adafruit Feather RP2040 with DVI Output Port. Its modules are already compiled, so you can try the display without installing compiler tools on your computer. The later build-and-compare section uses the small Mandelbrot example on a Metro RP2040.

1. Download and install the UF2

As of September 11, 2026, use the Absolute Newest continuous build. The stable 10.3.0 download predates Turbo support. The official files below identify themselves as 10.3.0-55-geb49ac4141, built on September 11, 2026.

Your board	Official UF2 with Turbo support	Board download page
Metro RP2040, for the later Mandelbrot example	Download Metro RP2040 UF2	Metro RP2040 on circuitpython.org
Feather RP2040 with DVI Output Port, for the art demo	Download Feather RP2040 DVI UF2	Feather RP2040 DVI on circuitpython.org

For a newer build, open your board's page on circuitpython.org and scroll to Absolute Newest → BROWSE S3. Choose your language and a main-branch build containing the Turbo support merged on September 11. Each board needs its own UF2.

Back up the files already on your board's CIRCUITPY drive. Connect the board with a USB data cable.
Hold BOOT/BOOTSEL, then press and release RESET. Keep holding BOOT until the RPI-RP2 drive appears, then release it.
Drag the downloaded UF2 onto RPI-RP2. Let the copy finish. The board restarts and the CIRCUITPY drive appears.

That's the firmware installed! Your board can now load matching native and Viper .mpy modules. The prepared project below supplies those modules and its Python files.

For pictures of the buttons and drives, see the Metro RP2040 install guide or the Feather RP2040 DVI install guide.

2. Copy the Blinka art demo

Use the Feather RP2040 DVI and its matching UF2 from step 1. Connect its DVI output to a compatible monitor using an HDMI cable. This program uses that board's display wiring.

Download the ready-to-copy Blinka demo, CIRCUITPY.zip (24 KB)

Unzip the download and open the folder named CIRCUITPY.
Copy everything inside that folder to the root of your board's CIRCUITPY drive. Replace the old code.py only after backing it up. The new code.py, .mpy modules and assets folder should sit directly on the drive, with no extra CIRCUITPY folder inside it.
Wait for the copy to finish, safely eject or sync the drive, then press RESET.

The program cycles through Blinka's Turbo OFF art, Turbo ON art and a live native neon effect. The ZIP includes the prepared modules, so no host CLI or compiler is needed for this demo. Install the UF2 separately; it is not inside this download.

The OFF and ON numbers time the same job: adding up the bytes of the starting artwork. The program compares the Python and native results before showing their timing ratio. The live effect is a separate demonstration; its displayed multiplier reuses that byte-sum ratio and is not a measured animation speedup.

The supplied clip below shows the art demonstration. The archive's contents and installation layout were checked for this guide; we have not run a new hardware test of this ZIP on the official firmware.

Supplied art-demo recording, shown here as a silent loop. The original MP4 is available below. Its on-screen multiplier refers to byte-sum timing, not the speed of the live animation. This is recorded footage, not a new hardware test for this guide.

Download the original art-demo video (MP4)

Compile a function yourself

The ready-to-copy art demo above is complete. Continue here when you want to build or change your own accelerated function. We'll use the Metro RP2040 Mandelbrot example for this compiler walkthrough.

3. Install the MPY cross-compiler tools on your computer

On Apple Silicon macOS or supported Linux hosts, with Python 3.11 or newer and Git installed, create a new project folder and an isolated environment. Install the reviewed CLI revision:

python3 -m venv .venv
.venv/bin/python -m pip install 'git+https://github.com/mikeysklar/turbo-cli.git@a0143a4efa246a8621d8ea076aa718f8c7215265'
.venv/bin/turbo --help

This installs the Turbo CLI, which invokes a matching mpy-cross compiler to prepare modules for your board. Compile a function once and run it repeatedly on the board; compile it again after changing it. This pinned installation produced adafruit-turbo 0.1.0 in our host check. Use the CLI source and firmware notes when choosing a newer revision.

The pinned CLI can resolve compiler downloads for Apple Silicon macOS and Linux x86_64, aarch64, and armv7l. Intel Macs need a separately supplied matching compiler via --mpy-cross. Compiler download was not exercised in this draft's host check.

4. Build and compare

Use the intended test board with its matching official UF2 installed. These are the documented example commands; build copies compiled modules to the board, and bench runs and installs candidates:

.venv/bin/turbo doctor
.venv/bin/turbo init --example
.venv/bin/turbo build
.venv/bin/turbo bench pixels --trials 5

doctor identifies the target and checks the toolchain. init --example creates the shim, source module, and example application. build produces architecture-specific modules. bench times bytecode, native, and Viper, compares the benchmark's returned value, and selects a faster matching candidate. A successful build by itself is not an output-equivalence check.

The benchmark command runs through the board's REPL. To run the example as the board's application, copy the local project's generated code.py to the root of the intended board's CIRCUITPY drive after backing up its existing code.py. Wait for copying to finish and safely eject or sync the CIRCUITPY drive, then press the board's reset button. build already copies the shim and source module, but leaves the board's code.py alone.

A minimal application is just:

import turbo
import pixels

print(pixels._turbo_bench())

The actual Mandelbrot source contains the fixed-point row function and the benchmark. Its expected returned value is 407644.

5. Make the comparison useful

Record the exact board, firmware, clock, source revision, input, trial count, median times, and result checks. Compare complete outputs where practical. Then time the full application, including the parts that wait for hardware.

On the Metro RP2040's CIRCUITPY drive, remove lib/turbo/armv6m/pixels.mpy and press reset to run the installed example from source. Leave src/pixels.py, lib/turbo.py, and code.py present. Removing only the host copy does not change the board. That gives you a baseline for the next experiment.

Once the example works, choose one small loop from your own project. Save a working copy, time it, and check the result after compiling. Then run the whole project again. That's where you'll find out whether the extra speed buys you another animation step, a bigger calculation, or more time to respond to input.

A pointer gives directions, not guardrails

In out: ptr8, ptr8 tells Viper to access the buffer through a pointer to bytes. out[px] = i writes the byte at that position. Viper pointer access does not check the buffer's bounds, so this function needs a writable buffer at least width bytes long. The example allocates 160 bytes and uses indexes 0 through 159. If you change the width, keep the allocation and loop limits together. The address does not come with a fence.

Sources: Viper pointers, this function and its buffer.

Download src-pixels.py

Copy Code

from turbo import turbo


@turbo.viper
def mandel_row(out: ptr8, width: int, dx: int, cy: int, max_iter: int):
    # fixed point, 12 fractional bits, integers only so viper can take it
    for px in range(width):
        cx = px * dx - (2 << 12)
        x = 0
        y = 0
        i = 0
        while i < max_iter:
            x2 = (x * x) >> 12
            y2 = (y * y) >> 12
            if x2 + y2 > (4 << 12):
                break
            y = ((x * y) >> 11) + cy
            x = x2 - y2 + cx
            i += 1
        out[px] = i


def _turbo_bench():
    W, H, IT = 160, 120, 64
    row = bytearray(W)
    dx = (3 << 12) // W
    total = 0
    for r in range(H):
        mandel_row(row, W, dx, ((r * 2) << 12) // H - (1 << 12), IT)
        total += sum(row)
    return total

from turbo import turbo


@turbo.viper
def mandel_row(out: ptr8, width: int, dx: int, cy: int, max_iter: int):
    # fixed point, 12 fractional bits, integers only so viper can take it
    for px in range(width):
        cx = px * dx - (2 << 12)
        x = 0
        y = 0
        i = 0
        while i < max_iter:
            x2 = (x * x) >> 12
            y2 = (y * y) >> 12
            if x2 + y2 > (4 << 12):
                break
            y = ((x * y) >> 11) + cy
            x = x2 - y2 + cx
            i += 1
        out[px] = i


def _turbo_bench():
    W, H, IT = 160, 120, 64
    row = bytearray(W)
    dx = (3 << 12) // W
    total = 0
    for r in range(H):
        mandel_row(row, W, dx, ((r * 2) << 12) // H - (1 << 12), IT)
        total += sum(row)
    return total

A smaller file is another useful goal

Kevin Matocha's Memory-saving Tips for CircuitPython explains how ordinary precompiled .mpy files can help with storage. That is a useful companion to this experiment: a file can take less space without making its calculation run faster. Check which benefit your project needs.

Parts for these examples

The ready-to-copy art demo needs a Feather RP2040 DVI, a compatible monitor, and an HDMI cable. The compiler walkthrough uses the Metro RP2040 below. For either board, use one USB data cable that fits your computer: USB A to USB C or USB C to USB C. Choose one, and keep a backup of the files already on the board.