Fetch the Code to Build

Once your build tools are installed, fetch the CircuitPython source code from its GitHub repository ("repo") and also fetch the git "submodules" it needs. The submodules are extra code that you need that's stored in other repos.

In the commands below, you're cloning from Adafruit's CircuitPython repo. But if you want to make changes, you might want to "fork" that repo on GitHub to make a copy for yourself, and clone from there. For more information about using GitHub and forking a repo, see theContribute to CircuitPython with Git and GitHub guide.

git clone https://github.com/adafruit/circuitpython.gitcd circuitpython

git clone https://github.com/adafruit/circuitpython.gitcd circuitpython

Install Required Python Packages

After you have cloned the repo, you'll need to install some Python packages that are needed for the build process. You only need to do this the first time, though you may want to run this again from time to time to make sure the packages are up to date.

# Install pip if it is not already installed (Linux only). Try running pip first.sudo apt install python3-pip# Install needed Python packages from pypi.org.pip3 install --upgrade -r requirements-dev.txtpip3 install --upgrade -r requirements-doc.txt

# Install pip if it is not already installed (Linux only). Try running pip first.sudo apt install python3-pip# Install needed Python packages from pypi.org.pip3 install --upgrade -r requirements-dev.txtpip3 install --upgrade -r requirements-doc.txt

The--upgrade flag will force installation of the latest packages, except where a version is explicitly specified in therequirements-*.txt files.

If you get an error indicating thatrust is needed to installminify-html, installrust:

curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh# You can verify the installation by running:source $HOME/.cargo/env #Import the environment config for rustrustc --version

curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh# You can verify the installation by running:source $HOME/.cargo/env #Import the environment config for rustrustc --version

Checking out a Specific Branch or Version

If you want to build a version other the latest, checkout the branch or tag you want to build. For example:

# Build using the latest code on the main branch.git checkout main# Build the latest code on the 9.0.x branchgit checkout 9.0.x# Build the 9.2.1 version exactly.git checkout 9.2.1

# Build using the latest code on the main branch.git checkout main# Build the latest code on the 9.0.x branchgit checkout 9.0.x# Build the 9.2.1 version exactly.git checkout 9.2.1

Note the build process has evolved, and earlier versions will need to be built somewhat differently than how the instructions in this guide specify. If you have trouble, ask onDiscord or theforums.

Fetch Submodules

We are not usinggit submodule update --init --recursive orgit submodule update --init. Instead you run the specialMakefile targetmake fetch-all-submodules at the top level, ormake fetch-port-submodules when you in a particularports/port-namedirectory. The target fetches only as many commits from each submodule as is necessary, using either a blobless partial clone (if available) or a shallow clone. This avoids downloading the complete trees of some large submodules, saving time and space.

make fetch-all-submodules fetches all the submodules in the entire repository, and can take several minutes and use up a lot of storage. If you are planning to build only in one or a few port directories, you'll save time by usingmake fetch-port-submodules, which fetches only the submodules need for that particular port.

If you are having trouble with your submodules, you can clean out all the fetched modules by doingmake remove-all-submodules at the top level. Then runmake fetch-all-submodules ormake fetch-port-submodules again to fetch a fresh copy of all the submodules. (There is nomake remove-port-submodules.)

Using a Version of git that can do Partial Clones

As mentioned above, the submodule fetching targets try to do a blobless partial clone if possible. This is better than a shallow clone: it is slightly faster, and the partial clone acts like a full clone if you want to maneuver around in the submodule by checking out other commits, examining the history, etc.

Git version 2.36 or later supports blobless partial clones. Ubuntu 24.04 includes such a version. To find out which version of git you are using, do git --version. Consider installing a newer version of git if it is available. On earlier versions of Ubuntu, you can install the git PPA and get the latest stable version of git. On macOS,homebrew may provide a later version for you.

cd circuitpython   # go to the top levelmake fetch-all-submodules# OR, for example, to fetch only the submodules needed for RP2040 builds:cd circuitpython/ports/raspberrypimake fetch-port-submodules

cd circuitpython   # go to the top levelmake fetch-all-submodules# OR, for example, to fetch only the submodules needed for RP2040 builds:cd circuitpython/ports/raspberrypimake fetch-port-submodules

Installpre-commit

We are using thepre-commit system to check submitted code for problems before it gets to GitHub. For more information, see thisLearn Guide page. To addpre-commit to your repository clone, do:

cd <your repository clone directory># You only need to do this once in each clone.pre-commit install

cd <your repository clone directory># You only need to do this once in each clone.pre-commit install

Buildmpy-cross

Build thempy-cross compiler first, which compiles Circuitpython.py files into.mpy files. It's needed to include library code in builds that usefrozen modules.

(If you get amake: msgfmt: Command not found error, you have not installedgettext. Go back to the Setup page for your operating system.)

Normally you do not need to rebuildmpy-cross on every pull or merge from thecircuitpython repository or for your own changes. The.mpy format does not change very often. But occasionally when we merge from MicroPython, the format changes. You will find that your old.mpy files or frozen libraries give an error, and you will need to rebuildmpy-cross.

make -C mpy-cross

make -C mpy-cross

Build CircuitPython

Now you're all set to build CircuitPython. If you're in themainbranch of the repo, you'll be building the latest version. Choose which board you want to build for. The boards available are all the subdirectories inports/atmel-samd/boards/.

cd ports/atmel-samdmake BOARD=circuitplayground_express

cd ports/atmel-samdmake BOARD=circuitplayground_express

By default the en_US version will be built. To build for a different language supply aTRANSLATION argument.

cd ports/atmel-samdmake BOARD=circuitplayground_express TRANSLATION=es

cd ports/atmel-samdmake BOARD=circuitplayground_express TRANSLATION=es

Run Your Build!

When you've successfully built, you'll see output like:

Create build-circuitplayground_express/firmware.binCreate build-circuitplayground_express/firmware.uf2python2 ../../tools/uf2/utils/uf2conv.py -b 0x2000 -c -o build-circuitplayground_express/firmware.uf2 build-circuitplayground_express/firmware.binConverting to uf2, output size: 485888, start address: 0x2000Wrote 485888 bytes to build-circuitplayground_express/firmware.uf2.

Create build-circuitplayground_express/firmware.binCreate build-circuitplayground_express/firmware.uf2python2 ../../tools/uf2/utils/uf2conv.py -b 0x2000 -c -o build-circuitplayground_express/firmware.uf2 build-circuitplayground_express/firmware.binConverting to uf2, output size: 485888, start address: 0x2000Wrote 485888 bytes to build-circuitplayground_express/firmware.uf2.

Copyfirmware.uf2 to your board the same way you'd update CircuitPython: Double-click to get theBOOT drive, and then just copy the.uf2 file:

# Double-click the reset button, then:cp build-circuitplayground_express/firmware.uf2 /media/yourname/CPLAYBOOT

# Double-click the reset button, then:cp build-circuitplayground_express/firmware.uf2 /media/yourname/CPLAYBOOT

The board will restart, and your build will start running.

If you're using a board without a UF2 bootloader, you'll need to usebossac and thefirmware.binfile, not the.uf2 file. Detailed instructions arehere.

Use All Your CPUs When Building

Most modern computers have CPU chips with multiple cores. For instance, you may have a 2-core, 4-core, or 6-core or more CPU. Your CPU may also allow 2 "threads" per core, so that it appears to have even more cores. You can run much of the build in parallel by using themake -j flag. This is will speed up the build noticeably.

If you don't know how many cores or threads your CPU has, on Linux you can use this command:

getconf _NPROCESSORS_ONLN12# This CPU has 6 cores and 12 threads.

getconf _NPROCESSORS_ONLN12# This CPU has 6 cores and 12 threads.

Then, when you run make, add the -j<n> option to use as many cores or threads as possible. For example:

make -j12 BOARD=trinket_m0

make -j12 BOARD=trinket_m0

When tomake clean

After you make changes to code, normally just doing make BOARD=... will be sufficient. The changed files will be recompiled and CircuitPython will be rebuilt.

However, there are some circumstance where you must do:

make clean BOARD=...

make clean BOARD=...

If you have changed the#include file structure in certain ways, if you have defined QSTR's (a way of defining constants strings in the CircuitPython source), or if you have added new error messages, then you must make clean before rebuilding. If you're not sure, it's always safe tomake clean and thenmake. It might take a little longer to build, but you'll be sure it was rebuilt properly.

Updating Your Repo

When there are changes in the GitHub repo, you might want to fetch those and then rebuild. Just "pull" the new code (assuming you haven't made changes yourself), update the submodules if necessary, and rebuild:

git pull # only if necessary, from the top level directorymake fetch-submodules# Then make again.

git pull # only if necessary, from the top level directorymake fetch-submodules# Then make again.

Those are the basics. There's a lot more to know about how to keep your forked repo up to date, merge "upstream" (Adafruit's) changes into your code, etc. We cover this in theContribute to CircuitPython with Git and GitHub guide