The CircuitPython experience on the Raspberry Pi is very similar to the experience on all of the other USB capable CircuitPython boards. One difference is that the CIRCUITPY drive is on removable storage. So please leave the SD card inserted for the whole time CIrcuitPython is running.

New to CircuitPython

If you are new to CircuitPython, then start by checking out the excellent Welcome to CircuitPython and CircuitPython Essentials guides. They'll get you started connecting to the CircuitPython serial and editing The essentials guide will provide basic examples for the common hardware interfaces.

Experienced CircuitPythonistas

The Raspberry Pi port is still very new and is likely missing modules you've used on other boards. Check out the Support Matrix for the lastest details on what is supported.


One of the main benefits of CircuitPython on the Raspberry Pi, is the easy use of a connected HDMI display. These are the first CircuitPython boards to support HDMI output. (Audio output over HDMI isn't currently supported.)

When using a display, make sure it is connected on bootup. The GPU firmware will discover the connected display and start the video output. Once CircuitPython starts, it will start a 640x480 frame buffer for displayio's normal terminal output. This is likely the wrong size for your display (but it's a safe bet for support.) So, you can reinitialize the CircuitPython framebuffer with a few lines of code. This code can be put into if you want to run it once on boot or in if you want to change it later. The example sets the output to 1/4 the size of HDMI (half of each dimension) because large terminal framebuffers are a bit slow for CIrcuitPython to update.

import displayio
import framebufferio
import videocore

fb = videocore.Framebuffer(1920 // 2, 1080 // 2)
display = framebufferio.FramebufferDisplay(fb)

After this re-initialization, display variable or board.DISPLAY can be used as normal. Check out the displayio guide for details.

This guide was first published on Jan 12, 2022. It was last updated on Mar 08, 2024.

This page (Using CircuitPython) was last updated on Mar 08, 2024.

Text editor powered by tinymce.