Some of the CircuitPython compatible boards come with CircuitPython installed. Others areCircuitPython-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.

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.

Download the latest software for your board by clicking the green button below to go toCircuitPython.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.

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 inuf2 then you want to continue with this section.However, if the file ends in .bin, you have to do a more complex installation - go tothis 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 labeledRESET orRSTon the board. The boot button is labeledBOOTSEL orBOOTon 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 calledboardnameBOOT whereboardname is a reference to your specific board. For example, a basic Feather will haveFEATHERBOOT and a Trinket will haveTRINKETBOOT etc.

For RP2040 boards:

The drive will be calledRPI-RP2 on all RP2040 boards.

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

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 theboot drive on your computer.

The lights should flash again,boot will disappear and anew drive will show up on your computer calledCIRCUITPY.

Congratulations! You've successfully installed or updated CircuitPython!

What's the difference betweenCIRCUITPY andboardnameBOOT orRPI-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 theCIRCUITPY drive. When you double-tap the reset button on most boards, you'll see theboardnameBOOT drive, or when hold boot select and tap reset for RP2040 boards, you'll seeRPI-RP2. You can drag files to theboot drives andCIRCUITPY, but onlyCIRCUITPY 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 theboot 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. theboot drive).

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

Bootloader Drive Names

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

• Feather RP2040 = RPI-RP2
• QT Py RP2040 = RPI-RP2
• ItsyBitsy RP2040 = RPI-RP2
• 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 
• PyPortal, Pynt and Titano = PORTALBOOT