Linux Setup

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 18.04 LTS (Long Term Support) version is stable and reliable.

Native Linux

You can install Ubuntu on a bare machine easily. Follow the directions (this link is for 16.04) 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.


Vagrant is software that is designed to make it easy to set up and use pre-configured virtual machines. There are potential stumbling blocks. This guide will include Vagrant information in the future.

Install Build Tools on Ubuntu

The Ubuntu 18.04 LTS Desktop distribution includes nearly everything you need to build CircuitPython. You just need to install git and the ARM processor toolchain (compiler, linker, etc.). In a terminal window, do:

Download: file
sudo apt update
# Try running `make`. If it's not installed, do:
# sudo apt install build-essential
sudo apt install git
sudo apt install gettext
pip3 install huffman
sudo add-apt-repository ppa:team-gcc-arm-embedded/ppa
# If you don't have add-apt-repository, do:
# sudo apt install add-apt-repository
sudo apt update
sudo apt install gcc-arm-embedded

Now move to the Build CircuitPython section of this guide.

This guide was first published on Apr 26, 2018. It was last updated on Apr 26, 2018. This page (Linux Setup) was last updated on Dec 14, 2019.