CircuitPython is a programming language based on Python, one of the fastest growing programming languages in the world. It is specifically designed to simplify experimenting and learning to code on low-cost microcontroller boards. Here is a guide which covers the basics:

Be sure you have the latest CircuitPython for your board loaded onto your board, as described here. You will need at least version 5.0 (possibly a beta version of it). While we'll reference the PyPortal in this guide, but this will work on all of the TFT based CircuitPython boards such as PyBadge and PyGamer.

This capability requires CircuitPython 5.0 or higher. It will not work for versions of CircuitPython less than 5.0.

CircuitPython is easiest to use within the Mu Editor. If you haven't previously used Mu, this guide will get you started.


Plug your board into your computer via a USB cable. Please be sure the cable is a good power+data cable so the computer can talk to the board.

A new disk should appear in your computer's file explorer/finder called CIRCUITPY. This is the place we'll copy the code and code library. If you can only get a drive named PORTALBOOT or PYGAMERBOOT, load CircuitPython per the guide mentioned above.

Create a new directory on the CIRCUITPY drive named lib.

Download the latest CircuitPython driver package to your computer using the green button below. Match the library you get to the version of CircuitPython you are using. Save to your computer's hard drive where you can find it.

To save bitmaps and screenshots you will need to add adafruit_bitmapsaver.mpy to the CIRCUITPY/lib directory.

This is in addition to whatever libraries are needed for your main code.

If your device has a microSD card slot or adapter and you wish to save to it you will also need adafruit_sdcard.mpy (if your board doesn't support sdcardio) and adafruit_bus_device in CIRCUITPY/lib.

This guide was first published on Sep 03, 2019. It was last updated on Mar 08, 2024.

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

Text editor powered by tinymce.