As CircuitPython development continues and and there are new releases, Adafruit will stop supporting older releases. If you are running earlier versions of CircuitPython, you need to update to the latest. 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. This section 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 back up your code before installing or updating CircuitPython!

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.

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

Click here to download CircuitPython from CircuitPython.org

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 and 8.1 Drivers

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

If you're using Windows 7 or 8.1, check out the Windows 7 and 8.1 Drivers page for details.

It is highly recommended that you upgrade to Windows 10.

Start the UF2 Bootloader

Nearly all CircuitPython boards ship with a bootloader called UF2 (USB Flashing Format) 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, you have to do a more complex installation - go to this page for details.

For most boards:

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. It is typically labeled RESET or RST on the board. (On Circuit Playground Express and Bluefruit, 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.

For RP2040 boards:

You'll want to find two buttons on the RP2040 boards: reset and BOOTSEL/BOOT. The two buttons are the same size - small black buttons. Reset is typically labeled RESET or RST on the board. The boot button is labeled BOOTSEL or BOOT on the board.

To enter the bootloader on an RP2040 board, you must hold down the boot select button, and while continuing to hold it, press and release the reset button. Continue to hold the boot select button until the bootloader drive appears.

Bootloader Mode

Once successful, the RGB status LED(s) on the board will flash red and then stay green. A new drive will show up on your computer.

For most boards:

The drive will be called boardnameBOOT where boardname is a reference to your specific board. For example, a basic Feather will have FEATHERBOOT and a Trinket will have TRINKETBOOT etc.

For RP2040 boards:

The drive will be called RPI-RP2 on all RP2040 boards.

Going forward, the bootloader drive will be referred to as the boot drive.

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

Install 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 or RPI-RP2?

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 on most boards, you'll see the boardnameBOOT drive, or when hold boot select and tap reset for RP2040 boards, you'll see RPI-RP2. You can drag files to the boot drives and CIRCUITPY, 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 boot 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. the boot drive).

You will be able to copy other files to the boot drive 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!