Last modified: Jun 16, 2026

Install CircuitPython Guide

CircuitPython is a beginner-friendly version of Python for microcontrollers. It makes coding hardware easy and fun. This guide will help you install it step by step.

You do not need prior experience. Just follow each section carefully. By the end, your board will run CircuitPython.

What You Need

Before you start, gather these items:

  • A compatible microcontroller board like Adafruit ItsyBitsy or Feather.
  • A USB cable that supports data transfer.
  • A computer with a USB port (Windows, Mac, or Linux).
  • An internet connection to download files.

Check your board's documentation. Most Adafruit boards support CircuitPython. Some boards from other brands also work.

Download CircuitPython

Go to the official CircuitPython downloads page. Find your specific board model. Download the latest stable .uf2 file.

Do not download beta versions unless you need new features. Stable releases are safer for beginners.

Save the file to your computer. Remember its location. You will use it soon.

Put Board in Bootloader Mode

Most boards need to enter bootloader mode. This lets you flash new firmware.

To do this:

  1. Unplug the board from USB.
  2. Press and hold the reset button (often labeled RST or RESET).
  3. Keep holding it while plugging the USB cable into your computer.
  4. Release the button after 2 seconds.

Your computer should show a new drive named BOOT or ITSYBOOT. This means the board is ready.

If you see no new drive, try a different USB cable. Some cables only charge and do not transfer data.

Flash the CircuitPython Firmware

Now copy the downloaded .uf2 file to the BOOT drive. Just drag and drop it like a normal file.

The board will blink or reset automatically. The BOOT drive will disappear. A new drive named CIRCUITPY will appear.

This confirms the installation succeeded.


# No code needed for this step.
# Just drag the .uf2 file onto the BOOT drive.

If the CIRCUITPY drive does not appear, repeat the bootloader process. Ensure you used the correct firmware for your board.

Install the Mu Editor (Optional)

You can use any text editor to write code. But Mu Editor is designed for CircuitPython. It has a serial monitor and file manager.

Download Mu from its official website. Install it like any other program. Open it and select CircuitPython mode.

Mu will detect your CIRCUITPY drive automatically. You can write and run code instantly.

Write Your First Program

Open the code.py file on the CIRCUITPY drive. Replace its content with this simple test.


# This is your first CircuitPython program
# It blinks the built-in LED
import board
import digitalio
import time

led = digitalio.DigitalInOut(board.LED)
led.direction = digitalio.Direction.OUTPUT

while True:
    led.value = True   # Turn LED on
    time.sleep(0.5)
    led.value = False  # Turn LED off
    time.sleep(0.5)

Save the file. The board will restart and run the code. You should see the LED blink every half second.

If nothing happens, check the serial output. Use Mu's serial monitor or a tool like PuTTY.

Test the Serial Connection

Open a serial terminal at 115200 baud. You will see boot messages and any print() output from your code.


# Example serial output
Adafruit CircuitPython 8.2.0 on 2023-07-05; Adafruit ItsyBitsy M4 Express with samd51g19
Board ID:adafruit_itsybitsy_m4_express
Hello from CircuitPython!

If you see this, your installation works perfectly.

Common Problems and Fixes

Problem: No BOOT drive appears.
Fix: Try a different USB cable or port. Hold the reset button longer.

Problem: CIRCUITPY drive shows up but code does not run.
Fix: Ensure the file is named code.py exactly. Check for syntax errors in the serial monitor.

Problem: Board freezes after flashing.
Fix: Unplug power, then re-enter bootloader mode. Flash the firmware again.

Most issues come from wrong firmware or bad USB cables. Double-check your board model.

Conclusion

You have successfully installed CircuitPython on your microcontroller. You wrote and ran your first program. Now you can explore sensors, displays, and motors.

CircuitPython makes hardware programming accessible. Practice with simple projects. Use the serial monitor to debug. The community is helpful and active.

For advanced topics, check the official CircuitPython documentation. Happy coding!

Recent Tutorials: