CircuitPython Detailed Install

Reinstalling and Updating CircuitPython in Detail

The latest builds of CircuitPython are available from the GitHub release page. Binaries for different boards are listed under the Downloads section. Pick the one that matches your board such as adafruit-circuitpython-circuitplayground_express-2.0.0.uf2 for the Circuit Playground Express.

Files ending in .uf2 can be flashed onto a virtual drive when in bootloader mode. Files that end with .bin can be flashed with or bossac.

You will see a list of all available flavors of CircuitPython. Since we support a lot of different hardware, we have a long list of available downloads!

See below for which file to download!


Flashing is the process of updating the CircuitPython core. It isn't needed for updating your own code. There are two available methods: UF2 and bossac

Flashing is only available on newer boards including the Circuit Playground Express. Flashing via bossac is possible with both the UF2 bootloader and the original "Arduino" one. We recommend using UF2 if you can, its the easiest! If UF2 fails, or is not available, try bossac.

Entering Bootloader Mode

Regardless of what method you use, you must first get the board into the bootloader mode. This is done by single clicking the reset button. The board is in bootloader mode when the red led fades in and out. The status neopixels will also show USB status while the red led fades. Green means USB worked while red means the board couldn't talk to the computer. The first step to troubleshooting a red neopixel is trying a different USB cable to make sure its not a charge-only cable.

Flashing UF2

The Circuit Playground Express comes with a new bootloader called UF2 (Usb Flasher version 2) that makes flashing CircuitPython even easier than before. This beta bootloader allows you to drag so-called ".uf2" type files onto the BOOT drive. For more information, check out our UF2 bootloader page.

Start by ejecting or "safely remove" the CIRCUITPY drive if its present, then single-clicking the reset button while it is plugged into your computer. You should see a new disk drive 'pop up' called CPLAYBOOT or similar, and the NeoPixels on your board glow green, while the red indicator LED pulses.

The drive will contain a few files. If you want to make a 'backup' of the current firmware on the device, drag-off and save the CURRENT.UF2 file. Other that that you can ignore the index.htm and info_uf2.txt files. They cannot be deleted and are only for informational purposes.

Next up, find the Circuit Playground Express UF2 file in the github downloads list:

Click to download and save the file onto your Desktop or somewhere else you can find it

Then drag the uf2 file into the CIRCUITPY drive.

Once the full file has been received, the board will automatically restart into CircuitPython. Your computer may warn about ejecting the drive early, if it does, simply ignore it because the board made sure the file was received ok.

Flashing with BOSSAC

This method is only recommended if you can't use UF2 for some reason!

.bin files for the CircuitPlayground Express are available here. Make sure the filename matches the uf2 except for the last three characters.

To flash with bossac (BOSSA's command line tool) first download the latest version from here. The mingw32 version is for Windows, apple-darwin for Mac OSX and various linux options for Linux. Once downloaded, extract the files from the zip and open the command line to the directory with bossac.

bossac -e -w -v -R ~/Downloads/adafruit-circuitpython-circuitplayground_express-1.0.0.bin

This will erase the chip, write the given file, verify the write and Reset the board. After reset, CircuitPython should be running. Newer boards with the UF2 bootloader may cause a warning of an early eject of a USB drive but just ignore it. Nothing important was being written to the drive.

After flashing

After a successful flash by bossac or UF2 you should see a CIRCUITPY drive appear.

Last updated on 2017-12-01 at 04.56.58 PM Published on 2017-10-12 at 10.43.39 PM