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.

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.

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!

This guide was first published on Dec 19, 2017. It was last updated on Nov 16, 2018. This page (Installing CircuitPython) was last updated on Oct 30, 2018.