CircuitPython builds for Raspberry Pi boards are available on circuitpython.org just like other microcontroller versions, under the Downloads section.

Next, click on the board that you have.

The board page allows you to download the stable or unstable release of CircuitPython. This notion of stability applies to CircuitPython as a whole, not necessarily the "port", meaning support for certain chip family. For the Raspberry Pi builds, always use "unstable" or "absolute latest" while the port is still in an alpha state (documented in the release notes.)

Additionally, you can also select a language for all of the serial messages including Python errors.

Broadcom builds come in two different file types:

• .disk.img.zip is full filesystem image that is typically used by "imager" programs like rpi-imager.
• .kernel8.img  or .kernel.img is only the CircuitPython portion of the image and can be copied directly onto an existing SD card.

The disk image is best to start with but may overwrite the CircuitPython filesystem if used for updating. (The actual behavior varies based on the imaging program.)

Raspberry Pi Imager

Raspberry Pi (the company) has created an imager that makes it easy to write disk images to an SD card. We'll use it to write the CircuitPython disk image to a card. Install the Raspberry Pi Imager based on instructions from the Raspberry Pi website.

After launching the Imager, click "Choose OS".

Then, scroll down to the bottom of the popup and select "Use custom".

In the file selection dialog, pick the .disk.img.zip file that you downloaded earlier.

Next, choose the storage device to write the disk image to. Make sure it's correct! It will be overwritten.

After selecting the disk you wish to write, the middle box will change. To initiate the write click "WRITE". Imager will confirm the selection.

After confirming the write, a progress bar will show for writing the SD card and then verifying the contents were written correctly.

After the SD card is written, remove it from the writer and insert it into an unpowered Raspberry Pi. Power the board up to start CircuitPython.

On first power up, CircuitPython will create a second partition on the SD card to use for the CIRCUITPY drive. On subsequent flashes, some writers may preserve this partition but others may not. So, make sure and back up your code prior to flashing.

Upgrading

The CircuitPython disk image includes the CircuitPython code along with supporting code from the Pi folks and potentially erases the whole card.

If you want to just update CircuitPython, then you can download the kernel image alone (called kernel.img for Zeros and kernel8.img for Zero 2, Pi 3 and Pi 4.)

From circuitpython.org/downloads the filename is really long but the Raspberry Pi boot code only knows how to find the exact short name.

So, to update CircuitPython first download the kernel img file following the instructions above and then rename it to remove the circuitpython information.

After renaming the file, drag or copy the file onto BOOT. If your OS asks, confirm that you want to overwrite the existing file.

Again, after upgrading, put the SD card back into your Pi when powered off and then power it up.