Install a Real or Virtual Linux Machine

If you don't already have a Linux machine, you can set one up in several different ways. You can install a Linux distribution natively, either on its own machine or as a dual-boot system. You can install Linux on a virtual machine on, say, a Windows host machine. You can also use Windows Subsystem for Linux (WSL), available on Microsoft Windows 10, which allows you to run a Linux distribution with an emulation layer substituting for the Linux kernel.

We recommend using the Ubuntu distribution of Linux or one of its variants (Kubuntu, Mint, etc.). The instructions here assume you are using Ubuntu. The 22.04 LTS (Long Term Support) version is stable and reliable.

Native Linux

You can install Ubuntu on a bare machine easily. Follow the directions on the Ubuntu website. You can also install Ubuntu on a disk shared with your Windows installation, or on a separate disk, and make a dual-boot installation.

Linux on a Virtual Machine

Linux can also be installed easily on a virtual machine. First you install the virtual machine software, and then create a new virtual machine, usually giving the VM software a .iso file of Ubuntu or another distribution. On Windows, VM Workstation Player and VirtualBox are both free and easily installed. Malke your virtual machine filesystem at least 20GB so you won't run out of space.

Raspberry Pi

It may be possible to build on Raspberry Pi OS, but it will be easier if you install Ubuntu on your Raspberry Pi. You will also need to download the aarch64 gcc toolchain. The RPi is not a fast machine: be prepared to wait for a build to complete.

Install Build Tools on Ubuntu

The Ubuntu 22.04 LTS Desktop distribution includes most of what you need to build CircuitPython. You'll need to install some additional packages, including build-essential, if it's not already installed, and also git, git-lfs, gettext, uncrustify, and cmake.

The version of git (2.30) installed with Ubuntu 22.04 will work, but git versions that support partial submodule cloning (2.36 or later) will work better with submodules.

In a terminal window, do:

sudo apt update
# Try running `make`. If it's not installed, do:
# sudo apt install build-essential

# If you don't have add-apt-repository, do:
# sudo apt install software-properties-common

# Optional: use the latest stable version of git:
sudo add-apt-repository ppa:git-core/ppa

# The version of uncrustify you need is in a PPA:
sudo add-apt-repository ppa:pybricks/ppa

sudo apt install git git-lfs gettext uncrustify cmake

Cortex-M Builds

Most CircuitPython boards use an ARM Cortex-M processor.  You need to download and unpack the appropriate ARM Cortex-M toolchain. Do not use the obsolete ARM Ubuntu "ppa" (private package archive). The links below point to the general download pages for the toolchains. Choose the arm-none-eabi version of the compiler, and select the correct architecture for your development computer, such as x64 Linux for a typical Linux PC. The package library for your particular Linux distribution will not necessary install the correct version.

If you want to build an older version of CircuitPython:

Cortex-A Builds

The broadcom port (Raspberry Pi Linux boards) needs a different toolchain. Use the Cortex-A toolchain:

  • For CircuitPython 7.x and later, use the 10.3-2021.07 version.

You will also need the mtools package:

sudo apt install mtools

And finally, you need a version 4.2 or later of mkfs.fat, which is part of the dosfstools package. Ubuntu 20.04 has version 4.1. You can download and build dosfstools. After you do so, copy mkfs.fat to some place that is or will be on your PATH.

tar xvf dosfstools-4.2.tar.gz
cd dosfstools-4.2

Installing the Toolchain

Unpack the toolchain in a convenient directory.

# This is an example.
cd ~/bin
tar xvf <name of the .bz2 or .xz file you downloaded>

Next, add a line to your .bash_profile or other startup file to add the unpacked toolchain executables to your PATH. For example:

export PATH=/home/$USER/bin/gcc-arm-none-eabi-10-2020-q4-major/bin:$PATH

Open a new terminal window, and see if you now have the correct executables on your path:

which arm-none-eabi-gcc

Other Builds

Now move to the Build CircuitPython section of this guide. There we will get the CircuitPython source code, install a few more dependencies, and then build!

This guide was first published on Apr 26, 2018. It was last updated on Jan 15, 2024.

This page (Linux Setup) was last updated on Nov 04, 2023.

Text editor powered by tinymce.