CircuitPython Getting Started: Adafruit’s Python for Hardware

After years of wrestling with Arduino’s C++ syntax and cryptic compiler errors, discovering CircuitPython felt like someone finally turned on the lights. Edit a file, save it, watch your hardware respond instantly—no compilation, no uploading, no waiting. That’s the magic of Adafruit CircuitPython, and it’s transformed how I prototype embedded projects.

CircuitPython is Adafruit’s beginner-friendly fork of MicroPython, designed specifically to make hardware programming accessible to everyone. With support for over 600 microcontroller boards, a massive library ecosystem, and that satisfying instant-feedback workflow, it’s become my go-to platform for everything from Python NeoPixel animations to full Adafruit IO connected devices.

This guide walks you through everything you need to get started with Circuit Python—from installation to your first blinking LED to sending sensor data to the cloud.

What is CircuitPython?

CircuitPython is a programming language designed to simplify experimenting and learning to code on low-cost microcontroller boards. It’s based on Python 3, which means if you’ve written any Python before, you already know most of what you need.

The key insight behind Adafruit CircuitPython is brilliant in its simplicity: when you plug in a CircuitPython board, it appears as a USB drive called CIRCUITPY. Your code lives in a file called code.py on that drive. Edit the file with any text editor, save it, and the board automatically reloads and runs your updated code. No IDE required, no compile step, no upload button.

Why CircuitPython Over Arduino?

Feature	CircuitPython	Arduino
Language	Python 3	C/C++
Code deployment	Save file to USB drive	Compile and upload
Feedback loop	Instant (auto-reload)	10-30 seconds
Serial console	Built-in REPL	Requires Serial Monitor
Learning curve	Gentle	Steeper
Libraries	500+ unified libraries	Thousands (varying quality)
Error messages	Clear and descriptive	Cryptic compiler errors

For rapid prototyping and education, Circuit Python wins hands down. For production firmware requiring every microsecond of performance, Arduino still has its place. But for 90% of maker projects, CircuitPython gets you to a working prototype faster.

CircuitPython vs MicroPython

Since CircuitPython is a fork of MicroPython, they share about 95% of their DNA. The differences matter, though, especially for beginners.

Aspect	CircuitPython	MicroPython
Focus	Education, beginners	Efficiency, advanced users
USB drive	Automatic CIRCUITPY drive	Requires manual setup
Auto-reload	Yes, on file save	No
Hardware APIs	Unified across all boards	Board-specific
Library ecosystem	Curated, quality-controlled	Decentralized, varying
Community	Adafruit Discord, forums	GitHub, technical forums
Board support	600+ curated boards	Broader but less consistent

The unified hardware APIs deserve special attention. In Adafruit CircuitPython, code written for a Feather M4 works on a QT Py RP2040 with minimal changes. The board module abstracts away hardware differences, so board.LED means the onboard LED regardless of which board you’re using.

Supported Boards for Adafruit CircuitPython

The CircuitPython ecosystem has exploded. As of 2025, over 600 microcontroller boards support CircuitPython, from tiny QT Py boards to powerful Feathers with WiFi and displays.

Popular CircuitPython Boards

Board	Processor	Flash	RAM	Special Features	Price
Circuit Playground Express	SAMD21	256KB	32KB	10 NeoPixels, sensors, buttons	~$25
Feather M4 Express	SAMD51	2MB	192KB	Fast, lots of GPIO	~$23
Feather RP2040	RP2040	8MB	264KB	Dual-core, PIO	~$12
QT Py RP2040	RP2040	8MB	264KB	Tiny, STEMMA QT	~$10
Metro M4 Express	SAMD51	2MB	192KB	Arduino form factor	~$28
Feather ESP32-S3	ESP32-S3	8MB	512KB	WiFi, Bluetooth	~$18
Raspberry Pi Pico	RP2040	2MB	264KB	Budget-friendly	~$4

For absolute beginners, the Circuit Playground Express remains the best starting point. It has built-in NeoPixels, buttons, sensors, and speaker—no soldering or wiring required. Just plug it in and start coding.

For more advanced projects needing WiFi connectivity for Adafruit IO integration, the Feather ESP32-S3 provides excellent value with native wireless support.

Installing CircuitPython: Step-by-Step

Getting CircuitPython running takes about two minutes. Here’s the process:

Step 1: Download the CircuitPython UF2 File

Visit circuitpython.org/downloads and find your specific board. Download the latest stable .uf2 file for your board and language preference.

Step 2: Enter Bootloader Mode

Connect your board via USB. Double-click the reset button quickly—you should see a new drive appear called something like FEATHERBOOT or RPI-RP2 depending on your board.

Step 3: Copy the UF2 File

Drag the downloaded .uf2 file onto the bootloader drive. The board will automatically restart, and a new drive called CIRCUITPY will appear. That’s it—CircuitPython is installed.

Step 4: Install Libraries

Download the CircuitPython Library Bundle from circuitpython.org/libraries. Extract it and copy the libraries you need into the lib folder on your CIRCUITPY drive.

Your First CircuitPython Program

Let’s blink an LED. Create a file called code.py on your CIRCUITPY drive with this code:

python

import boardimport digitalioimport timeled = digitalio.DigitalInOut(board.LED)led.direction = digitalio.Direction.OUTPUTwhile True:    led.value = True    time.sleep(0.5)    led.value = False    time.sleep(0.5)

Save the file. The LED starts blinking immediately. Change 0.5 to 0.1, save again—the blink rate changes instantly. This immediate feedback loop is what makes Circuit Python so satisfying for learning and prototyping.

Python NeoPixel Control with CircuitPython

NeoPixels and CircuitPython are a perfect match. The Python NeoPixel library makes controlling addressable LEDs trivially simple.

Basic NeoPixel Setup

python

import boardimport neopixel# 10 NeoPixels on pin A1pixels = neopixel.NeoPixel(board.A1, 10, brightness=0.3, auto_write=False)# Set all pixels to redpixels.fill((255, 0, 0))pixels.show()# Set individual pixelspixels[0] = (0, 255, 0)  # Greenpixels[1] = (0, 0, 255)  # Bluepixels.show()

Rainbow Animation Example

python

import boardimport neopixelimport timefrom rainbowio import colorwheelpixels = neopixel.NeoPixel(board.A1, 30, brightness=0.2, auto_write=False)def rainbow_cycle(wait):    for j in range(255):        for i in range(len(pixels)):            pixel_index = (i * 256 // len(pixels)) + j            pixels[i] = colorwheel(pixel_index & 255)        pixels.show()        time.sleep(wait)while True:    rainbow_cycle(0.01)

The auto_write=False parameter is important for performance—it batches all pixel changes and sends them with a single pixels.show() call rather than updating the strip after every individual pixel change.

NeoPixel Best Practices

Parameter	Recommended Value	Notes
brightness	0.1 – 0.3	Start low, saves power
auto_write	False	Better performance for animations
pixel_order	neopixel.GRB	Default for most strips
Power limit	60mA per pixel at full white	Plan your power supply

For large Python NeoPixel installations, always calculate your power requirements. A strip of 100 NeoPixels at full white brightness can draw 6 amps—far more than USB can provide.

Connecting to Adafruit IO with CircuitPython

Adafruit IO is Adafruit’s IoT platform, perfect for logging sensor data, controlling devices remotely, and building dashboards. Connecting CircuitPython projects to Adafruit IO requires a WiFi-capable board like the Feather ESP32-S3 or PyPortal.

Setting Up WiFi and Adafruit IO Credentials

Create a settings.toml file on your CIRCUITPY drive:

toml

CIRCUITPY_WIFI_SSID = “your_wifi_network”CIRCUITPY_WIFI_PASSWORD = “your_wifi_password”ADAFRUIT_AIO_USERNAME = “your_aio_username”ADAFRUIT_AIO_KEY = “your_aio_key”

Sending Sensor Data to Adafruit IO

python

import timeimport boardimport adafruit_dhtfrom adafruit_io.adafruit_io import IO_HTTPfrom os import getenvimport wifiimport socketpool# Connect to WiFiwifi.radio.connect(    getenv(“CIRCUITPY_WIFI_SSID”),    getenv(“CIRCUITPY_WIFI_PASSWORD”))# Create Adafruit IO HTTP clientpool = socketpool.SocketPool(wifi.radio)io = IO_HTTP(    getenv(“ADAFRUIT_AIO_USERNAME”),    getenv(“ADAFRUIT_AIO_KEY”),    pool)# Setup DHT22 sensordht = adafruit_dht.DHT22(board.D5)# Create or get feedtemperature_feed = io.get_feed(“temperature”)while True:    try:        temp = dht.temperature        print(f”Temperature: {temp}°C”)        io.send_data(temperature_feed[“key”], temp)    except Exception as e:        print(f”Error: {e}”)    time.sleep(60)  # Send every minute

Once data flows to Adafruit IO, you can create dashboards with gauges, charts, and controls—all accessible from any web browser or mobile device.

Essential CircuitPython Libraries

The Adafruit CircuitPython library bundle contains over 500 libraries. Here are the ones I install on almost every project:

Library	Purpose	Common Use
adafruit_neopixel	LED control	Python NeoPixel strips and rings
adafruit_bus_device	I2C/SPI helpers	Required by many sensor libraries
adafruit_requests	HTTP requests	Web APIs, Adafruit IO
adafruit_io	IoT platform	Cloud data logging, dashboards
adafruit_display_text	Text rendering	OLED and TFT displays
adafruit_motor	Motor control	Servos, DC motors, steppers
adafruit_hid	USB HID	Custom keyboards, mice

The adafruit_bus_device library is a dependency for most sensor libraries, so always include it even if you don’t use it directly.

CircuitPython Development Tools

Recommended Editors

Mu Editor is the official recommendation for beginners. It’s designed specifically for CircuitPython and MicroPython, with built-in serial console, plotter, and helpful error messages.

For more experienced developers, VS Code with the CircuitPython extension provides code completion, error checking, and direct serial console access.

Editor	Best For	Features
Mu Editor	Beginners	Simple, built-in plotter, REPL
VS Code	Advanced users	Extensions, code completion
Thonny	Education	Step-through debugging
Any text editor	Quick edits	Just save to CIRCUITPY

The REPL (Read-Eval-Print Loop)

Connect to your board’s serial port (115200 baud) to access the REPL. This interactive Python prompt lets you test code snippets, inspect variables, and debug issues in real time.

python

>>> import board>>> dir(board)[‘A0’, ‘A1’, ‘A2’, ‘D5’, ‘D6’, ‘LED’, ‘NEOPIXEL’, ‘SCL’, ‘SDA’, …]>>> board.board_id’adafruit_feather_rp2040′

The REPL is invaluable for figuring out which pins your board has and testing sensor connections before committing to code.

Essential Resources and Downloads

Resource	URL	Description
CircuitPython Downloads	circuitpython.org/downloads	Board firmware files
Library Bundle	circuitpython.org/libraries	All official libraries
Adafruit Learn System	learn.adafruit.com/category/circuitpython	Tutorials and guides
API Documentation	docs.circuitpython.org	Full API reference
Adafruit IO	io.adafruit.com	IoT platform dashboard
Mu Editor	codewith.mu	Beginner-friendly editor
GitHub Repository	github.com/adafruit/circuitpython	Source code
Adafruit Discord	adafru.it/discord	Community chat

Troubleshooting Common Issues

CIRCUITPY Drive Not Appearing

• Try a different USB cable (some are charge-only)
• Double-click reset to enter bootloader mode
• Check if the board appears in Device Manager (Windows) or lsusb (Linux)

Code Not Running

• Ensure your file is named code.py (not Code.py or code.py.txt)
• Check the serial console for error messages
• Verify all required libraries are in the lib folder

ImportError for Libraries

• Download the matching library bundle version for your CircuitPython version
• Copy both .py files and folders (some libraries have multiple files)
• Check available memory—some boards can’t fit all libraries

Safe Mode

If your code crashes on startup, CircuitPython enters safe mode. The CIRCUITPY drive still mounts, letting you fix your code. Press reset to try running again after fixing the issue.

Frequently Asked Questions

Can I use regular Python libraries with CircuitPython?

No, standard Python libraries like requests or numpy won’t work directly because CircuitPython runs on microcontrollers with limited memory and no operating system. However, Adafruit provides equivalent libraries specifically written for CircuitPython—like adafruit_requests instead of requests. These libraries offer similar functionality optimized for embedded use.

How much memory do CircuitPython boards have?

It varies significantly by board. Entry-level boards like the Trinket M0 have 32KB RAM, while the Feather RP2040 has 264KB. For Python NeoPixel projects or Adafruit IO applications, aim for at least 64KB RAM. The SAMD51 and RP2040 boards offer the best balance of memory and price for most projects.

Can CircuitPython boards connect to WiFi?

Yes, but only boards with WiFi hardware. The Feather ESP32-S3, PyPortal, and boards with AirLift co-processors support WiFi. These can connect to Adafruit IO, fetch data from web APIs, and serve simple web pages. The Raspberry Pi Pico W also supports CircuitPython with WiFi.

Is CircuitPython fast enough for real-time applications?

CircuitPython is interpreted, so it runs slower than compiled C/C++ code. For most maker projects—reading sensors, controlling NeoPixels, responding to buttons—it’s plenty fast. For timing-critical applications like high-speed motor control or audio synthesis, you might hit limitations. The RP2040’s PIO (Programmable I/O) helps with precise timing tasks while keeping the main code in Python.

How do I update CircuitPython to a newer version?

Download the new .uf2 file from circuitpython.org, enter bootloader mode (double-click reset), and drag the file to the boot drive. Your code.py and lib folder on CIRCUITPY are preserved, but always back them up first. After updating, also update your libraries to the matching version to avoid compatibility issues.

Building Your First Complete Project

Here’s a practical project combining everything we’ve covered: a temperature logger that displays readings on NeoPixels and sends data to Adafruit IO.

python

import timeimport boardimport neopixelimport adafruit_dhtfrom adafruit_io.adafruit_io import IO_HTTPfrom os import getenvimport wifiimport socketpool# Setup NeoPixels for visual feedbackpixels = neopixel.NeoPixel(board.NEOPIXEL, 1, brightness=0.1)# Connect to WiFipixels[0] = (255, 255, 0)  # Yellow while connectingwifi.radio.connect(    getenv(“CIRCUITPY_WIFI_SSID”),    getenv(“CIRCUITPY_WIFI_PASSWORD”))pixels[0] = (0, 255, 0)  # Green when connected# Setup Adafruit IOpool = socketpool.SocketPool(wifi.radio)io = IO_HTTP(    getenv(“ADAFRUIT_AIO_USERNAME”),    getenv(“ADAFRUIT_AIO_KEY”),    pool)# Setup sensordht = adafruit_dht.DHT22(board.D5)temp_feed = io.get_feed(“temperature”)while True:    try:        temp = dht.temperature        # Color based on temperature        if temp < 20:            pixels[0] = (0, 0, 255)  # Blue = cold        elif temp < 25:            pixels[0] = (0, 255, 0)  # Green = comfortable        else:            pixels[0] = (255, 0, 0)  # Red = warm                io.send_data(temp_feed[“key”], temp)        print(f”Sent: {temp}°C”)    except Exception as e:        pixels[0] = (255, 0, 255)  # Purple = error        print(f”Error: {e}”)        time.sleep(300)  # Log every 5 minutes

This project demonstrates the power of Adafruit CircuitPython: readable code, visual feedback with Python NeoPixel, and cloud connectivity through Adafruit IO—all in under 50 lines.

Moving Forward with CircuitPython

Once you’re comfortable with the basics, the Circuit Python ecosystem opens up endless possibilities: wearable electronics, home automation, custom input devices, interactive art installations, and IoT sensor networks. The combination of easy programming, instant feedback, and extensive library support makes it the fastest path from idea to working prototype I’ve found in embedded development.

Start with a simple project, get comfortable with the workflow, then gradually explore more advanced features. The Adafruit Learning System has hundreds of project guides, and the Discord community is genuinely helpful for troubleshooting. Welcome to CircuitPython—you’re going to love it.