Installing CircuitPython

As we continue to develop CircuitPython and create new releases, we will stop supporting older releases. If you are running CircuitPython 2.x, you need to update to 3.x. Generally Adafruit will support the last two major versions.

Some of the CircuitPython compatible boards come with CircuitPython installed. Others are CircuitPython-ready, but need to have it installed. As well, you may want to update the version of CircuitPython already installed on your board. The steps are the same for installing and updating. Here we will cover how to install or update CircuitPython on your board.

You only have to install CircuitPython ONCE, after that you are free to code all you like without going through this process again until it's time to upgrade!

Download the latest version!

The first thing you'll want to do is download the most recent version of CircuitPython.

If you're already running CircuitPython, make sure you're running the latest version! If you're unsure,  you can follow the steps below to ensure you have the latest version installed.

ALWAYS BACKUP YOUR CODE BEFORE INSTALLING OR UPDATING CIRCUITPYTHON. Most of the time, nothing will be removed from your board during the update, but it can happen. If you already have code on your board, be sure to back it up to your computer before following the steps below.

Two Locations for CircuitPython Code

Before April, 2019, code was downloaded from the Adafruit CircuitPython Github site. Beginning in April, 2019, the new site CircuitPython.org was created to host CircuitPython. Definitions for supported boards are updated there and are much easier to find. New boards, both from Adafruit and other parties, are added as board definition files are created and uploaded to the site.

Download the latest software for your board by clicking the green button below to go to CircuitPython.org.

For now, the files are still available on Adafruit's CircuitPython GitHub repository also. These files may migrate to a new CircuitPython.org repository in the future.

Scroll down to the list of CircuitPython files, and choose the file appropriate to your board. Each file includes the name of the board it's compatible with. Download the file for your board.

Next, you'll want to plug in your board using a known-good USB data cable. Make sure the USB cable is a data cable! There are some that work only for charging and can lead to a lot of frustration.

Windows 7 Drivers

If you're using Windows 7, you need to install a driver before plugging in your board.

If you're using Windows 7, use the link below to download the driver package. You will not need to install drivers on Mac, Linux or Windows 10.

Start the UF2 Bootloader

Nearly all CircuitPython boards ship with a bootloader called UF2 (USB Flasher version 2) that makes installing and updating CircuitPython a quick and easy process. The bootloader is the mode your board needs to be in for the CircuitPython .uf2 file you downloaded to work. If the file you downloaded that matches the board name ends in uf2 then you want to continue with this section. However, if the file ends in .bin then you have to do a more complex installation - go to this page for how to do that.

Find the reset button on your board. It's a small, black button, and on most of the boards, it will be the only button available. (On Circuit Playground Express, it's the smaller button located in the center of the board.)

Tap this button twice to enter the bootloader. If it doesn't work on the first try, don't be discouraged. The rhythm of the taps needs to be correct and sometimes it takes a few tries. If you have a Circuit Playground Express, and it's fresh-out-of-the-bag try pressing the button once.

Once successful, the RGB LED on the board will flash red and then stay green. A new drive will show up on your computer. The drive will be called boardnameBOOT where boardname is a reference to your specific board. For example, a Feather will have FEATHERBOOT and a Trinket will have TRINKETBOOT etc. Going forward we'll just call the boot drive BOOT

The board is now in bootloader mode! This is what we need to install or update CircuitPython.

Now find the file you downloaded. Drag that file to the BOOT drive on your computer.

The lights should flash again, BOOT will disappear and a new drive will show up on your computer called CIRCUITPY.

Congratulations! You've successfully installed or updated CircuitPython!

What's the difference between CIRCUITPY and boardnameBOOT?

When you plug a CircuitPython board into your computer, your computer will see the board's flash memory as a USB flash drive where files can be stored. When you have successfully installed CircuitPython, you'll see the CIRCUITPY drive. When you double-tap the reset button, you'll see the boardnameBOOT drive. You can drag files to both, but only CIRCUITPY will run your CircuitPython code.

Normally, when you drag a file to a mounted USB drive, the file copies to the drive and then is able to be seen in your file explorer. However, when you drag the CircuitPython UF2 file to the boardnameBOOT drive, it seems to disappear, and the drive disconnects. This is normal! The UF2 is essentially an installer file, and does not simply sit on the drive, but installs CircuitPython if the board is in bootloader mode (i.e. boardnameBOOT).

You will be able to copy other files to the bootloader drive (boardnameBOOT) but they will not run or be accessible to CircuitPython. So make sure that once you're done installing CircuitPython, that you're dragging to and editing files on the CIRCUITPY drive!

Bootloader Drive Names

This list is not exhaustive, but should give you an idea what to look for in a bootloader drive name.

  • Trinket M0 = TRINKETBOOT
  • Gemma M0 = GEMMABOOT
  • Circuit Playground Express = CPLAYBOOT
  • ItsyBitsy M0 Express = ITSYBOOT
  • ItsyBitsy M4 Express = ITSYM4BOOT
  • Feather M0 Express = FEATHERBOOT
  • Feather M4 Express = FEATHERBOOT
  • Metro M0 Express = METROBOOT
  • Metro M4 Express = METROM4BOOT
  • Grand Central M4 Express = GCM4BOOT
  • NeoTrelis M4 Express = TRELM4BOOT 
This guide was first published on Dec 19, 2017. It was last updated on Dec 19, 2017. This page (Installing CircuitPython) was last updated on Sep 17, 2019.