To build CircuitPython on macOS, you need to install git, python3, and the compiler toolchain. The easiest way to do this is to first install Homebrew, a software package manager for macOS. Follow the directions on its webpages.

Now install the software you need:

brew update
brew install git git-lfs python3 gettext uncrustify cmake
brew link gettext --force

Then install the compiler toolchain. You can use  the gcc-arm-embedded homebrew formula to install the correct toolchain, but make sure you have homebrew install the correct version, as described on the Linux Setup page in this guide. As an alternative to homebrew, on the Linux Setup page, you can find pointers to the download pages for different kinds of ARM processors, and also special instructions for other builds (not all are available on macOS). Download and install the appropiate .pkg file for your Mac.

Once the dependencies are installed, we'll also need to make a disk image to clone CircuitPython into. By default the macOS filesystem is case insensitive. In a few cases, this can confuse the build process. So, we recommend creating a case sensitive disk image with Disk Utility to store the source code. Make the image capable of storing at least 10GB, preferably 20GB, so you won't run out of space if you do extensive development. You can use a sparse bundle disk image which will grow as necessary, so you don't use up all the space at once. The disk image is a single file that can be mounted by double clicking it in the Finder. Once it's mounted, it works like a normal folder located under the /Volumes directory.

Install gmake if Necessary

Depending on your version of macOS, whether or not you have installed Xcode, and other factors, the version of make on your Mac may not be recent enough to run builds. Check the version:

make --version
# and
gmake --version

If neither program exists, or both are older than version 4.3, install a newer version of gmake with brew:

brew install make

If you install the brew version of make, it will be known as gmake.

That's it! Now you can move on and actually Build CircuitPython. 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 May 20, 2024.

This page (macOS Setup) was last updated on Mar 08, 2024.

Text editor powered by tinymce.