Setting up the Build Environment (Linux/Ubuntu)

This article shows how to setup your build environment on Linux/Ubuntu machines.

Setup on Ubuntu

Get git

Git is a free and open source distributed version control system that is used to manage ArduPilot codebase. Git is available on all major OS platforms, and a variety of tools exist to make it easier to get started.

Git command line


Linux/Ubuntu users can install with apt :

  • sudo apt-get update
  • sudo apt-get install git
  • sudo apt-get install gitk git-gui

Other Systems

Clone ArduPilot repository

“Cloning” is git’s term for making a local copy of a remote repository (i.e. one held on the GitHub servers).

Developers should clone the main ArduPilot repository (if they simply want to download and compile the latest code) or their own fork (if they want to make changes to the source code and potentially submit changes back).

Instructions for commonly used tools are below but whichever tool is used, the URL for the source repo will be required. This can be found on the right side of the screen on each Github repository home page but in general the URL is:

  • for the main ardupilot repo
  • for your fork of the ardupilot repo

Cloning with the command line

  • open a terminal and navigate to the directory where you would like the clone to be stored

  • clone your fork:

    git clone
    cd ardupilot
    git submodule update --init --recursive

    or the main project repo:

    git clone
    cd ardupilot
    git submodule update --init --recursive

Install some required packages

If you are on a debian based system (such as Ubuntu or Mint), we provide a script that will do it for you. From ardupilot directory :

Tools/environment_install/ -y

Reload the path (log-out and log-in to make permanent):

. ~/.profile

Now you should be able to build with waf as described in

Add some directories to your search path (Facultative)


ONLY if you didn’t run the install-prereqs script from previous step.

Add the following lines to the end of your “.bashrc” in your home directory (notice the . on the start of that filename. Also, this is a hidden file, so if you’re using a file manager, make sure to turn on “show hidden files”).

export PATH=$PATH:$HOME/ardupilot/Tools/autotest
export PATH=/usr/lib/ccache:$PATH

Then reload your PATH by using the “dot” command in a terminal

. ~/.bashrc

Setup for other Distributions


Do not use this if you have already use the script !

To build for a Cube/Pixhawk target on Linux you need the following tools and git repositories:

  • The gcc-arm cross-compiler from here (Ardupilot is only built and tested on these specific versions of gcc-arm; if installed with apt-get gcc-arm will not produce a working binary in many cases)
  • gnu make, gawk and associated standard Linux build tools
  • On a 64 bit system you will also need to have installed libc6-i386.

Also, it’s worth mentioning here that you want to ensure that the modemmanager package is not installed and the modem-manager process is not running.


You need to make your user a member of the dialout group:

sudo usermod -a -G dialout $USER

You will need to log out and then log back in for the group change to take effect.


You need the specific gcc-arm cross-compiler linked above. You need to unpack it where you want, for now let’s call this location TARGET_DIR:

tar -xjvf gcc-arm-none-eabi-4_9-2015q3-20150921-linux.tar.bz2

and then add the bin directory from the tarball to your $PATH by editing the $HOME/.bashrc file and adding a line like this to the end. TARGET_DIR is the location choose previouly where you unpack the toolchain:

export PATH=$PATH:TARGET_DIR/gcc-arm-none-eabi-4_9-2015q3/bin

Now you should be able to build with waf as described in

ccache for faster builds

Installing ccache will speed up your builds a lot. Once you install it (for example with “sudo apt-get install ccache”) you should link the compiler into /usr/lib/ccache like this:

cd /usr/lib/ccache
sudo ln -s /usr/bin/ccache arm-none-eabi-g++
sudo ln -s /usr/bin/ccache arm-none-eabi-gcc

Then add /usr/lib/ccache to the front of your $PATH


If there have been updates to some git submodules you may need to do a full clean build. To do that use:

make px4-clean

that will remove the PX4NuttX archives so you can do a build from scratch

Additional Steps for macOS mojave

Due to some changes binutils installed via brew have stopped working for macOS mojave leading to crashing builds. So if installed, remove via following command:

brew uninstall binutils

Also you will need to install the c++ include headers to /usr/include to do that. Run the following in commandline and follow the installation routine:

open /Library/Developer/CommandLineTools/Packages/macOS_SDK_headers_for_macOS_10.14.pkg