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.

We are not using git submodule update --init --recursive or git submodule update --init. Instead you run the special Makefile target make fetch-submodules fetches only many commits from each submodule as is necessary. This saves downloading the complete trees of some large submodules.

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

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 on Discord or the forums.

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.

You may see errors if you have too-old or too-new versions of some of these packages already installed, and have to fix an installation by installing a package with a version specifier. For example, if the whatever package is too new, you may need to do pip3 install --upgrade 'whatever<2.1.0'.

Install pre-commit

We are using the pre-commit system to check submitted code for problems before it gets to GitHub. For more information, see this Learn Guide page. To add pre-commit to your repository clone, do:

Build mpy-cross

Build the mpy-cross compiler first, which compiles Circuitpython .py files into .mpy files. It's needed to include library code in certain boards.

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

Normally you do not need to rebuild mpy-cross on every pull or merge from the circuitpython 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 rebuild mpy-cross.

Build CircuitPython

Now you're all set to build CircuitPython. If you're in the main branch 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 in ports/atmel-samd/boards/.

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

Run Your Build!

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

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

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

If you're using a board without a UF2 bootloader, you'll need to use bossac and the firmware.bin file, not the .uf2 file. Detailed instructions are here.

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 the make -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:

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

When to make 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:

If you have changed the #include file structure in certain ways, or if you have defined QSTR's (a way of defining constants strings in the CircuitPython source), then you must make clean before rebuilding. If you're not sure, it's always safe to make clean and then make. 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:

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 the Contribute to CircuitPython with Git and GitHub guide