ArduPilot and Docker Part 1

Hello friends,

A recurrent question I got is : How to use ArduPilot SITL (Software In The Loop) with Docker. For those that don’t know what Docker is, it is a container management service : a kind of Virtual Machines (VM) but for applications. This can be really useful to set up a build environment for ArduPilot or simulation with a level of reproducibility as we can manage close to everything like in all VM systems.

Docker can be used in numerous ways with ArduPilot and I will try to share some knowledge on this series of blog posts.

Docker builders

The first usage of docker is generally for build environments. It can be tricky and time consuming to set up a build environment for ArduPilot, and using Docker can help.

So you may have seen this file on a bunch of ArduPilot repo.

That DockerFile allows you to set up a build environment. The one on ArduPilot is a generic builder. It is able to build all boards and run SITL in cmdline mode, so no GUI on Mavproxy. It can be used in different ways. But the first step will always be to build the Docker container.

From the repository root directory (the one that contains the Dockerfile file), run :

 docker build . -t ardupilot

Depending you Docker version, you should have an output like this one :

The dot . says to build the container from the current directory and -t is used to give the name ardupilot to the container we are building.


What does it do during this build ? The same things that you do when you configure your computer!

Getting Ubuntu, creating a user, installing some software. It uses ArduPilot install script Tools/environment_install/

And you can see some environment variables :


Those are passed to the script to control what to install. So by default we disable all GUI support packages, code coverage support and running git update at the end of the build.

Why those choices ? If Docker can be really useful, it is still close to a virtual machine and the setup of the GUI environment isn’t straightforward. So we chose to not install all those packages to keep the Docker Container simpler. I won’t cover here how to use the GUI.

Build environment.

The most common usage of the DockerFile is to set up a build environment. After building the container, you can enter in it to run your ArduPilot development like you would do in a normal Linux computer.

To do so :

 docker run -it -v `pwd`:/ardupilot ardupilot:latest bash

This mounts your local ArduPilot repository into the Docker container and puts you inside. You can then run waf commands and build ArduPilot binaries !

It has drawbacks on Linux systems. As you are sharing the filesystem, you can have some permission issues with the built binaries as the default user inside the container is not necessarily the same as your computer default user. To solve this, you can pass

-u "$(id -u):$(id -g)" to set up the Docker user as your computer user. That way, what you build on Docker will have the same owner as your current user, and you can use the resulting binaries directly.

You can notice that we don’t pass the --rm parameter that you can find in some other Docker documentation/example. This is to not destroy the container when you exit it. During the installation phase, we are installing some caching tools that will help to speed up the nexts build in the container. If you destroy the container each time, you won’t benefit from the cache. This can be useful if you want a true clean from scratch build each time.


The docker builder can also be used as a cmdline tool to build firmware. So let’s say you want to build CubeOrange firmware for Copter, you can simply used the container that way :

docker run --user $(id -u):$(id -g) -v `pwd`:/ardupilot ardupilot:latest ./waf configure --board CubeOrange

To configure the build for CubeOrange. And then :

docker run --user $(id -u):$(id -g) -v `pwd`:/ardupilot ardupilot:latest ./waf copter

To build !

What is the difference with the previous one : we don’t run an interactive session into the container, we can use it as a builder tool !

Docker CI (Continuous Integration)

You may have noticed that we are running a lot of automated tests on our Github repo.

Those tests are also running into Docker containers. We could have used our install script to set up the test environment for each test but this is a waste of resources and time, so we optimize the container for our CI.

If you search about ArduPilot Docker on your favorite search engine, you will probably find :!
Those are the docker containers that we are using to run CI. They are made from the definition on this repository :

They are simply setting up the environment and tools we need to run ArduPilot tests. Therefore there is one container per test target to optimize test run time. The CI workflow is the following :

We don’t recommend using those containers outside the CI environment as they are intended for CI and lack general purpose tools in them.


You got, now, a brief summary on how to use docker to build ArduPilot binaries. If you look on the wiki repository, you will see that you can also use it to build the whole wiki. A strong advantage is that you can use this on all OS like Windows to have a clean and isolated build environment !

Next post will introduce how to use SITL with Docker with some swarming examples !


hi, i’m using docker on windows.
i clone the ardupilot git and run from ardupilot directory : docker build . -t ardupilot
i got the error : executor failed running [/bin/sh -c Tools/environment_install/ -y]:
do you know what the issues could be?


yes, unfortunately, it is probable that windows nuke the file handling and permission on the scripts. I will look for a fix for this


Is there a reason y’all don’t publish a full ardupilot SITL container? My team takes advantage of the SITL sim_vehicle for integration testing and having to pull and build our own docker container does not seem easily maintainable compared to one published during your CICD. Interested if you have any insight on how best to tackle this challenge and minimize the footprint of a sim_vehicle container.

1 Like

The issue is there are 100 ways to do a SITL container.
I will make a new blog post showing some simple ways to do this next week, it was planned to be a follow up from this one but I lacked time to write up…


through the wsl the image was built

Using the docker build process is how I started using SITL on my Steam Deck last night. Just found this and pt2 posts today. I appreciate the work that’s gone into docker support!

1 Like