Dev Containers

You can use dev containers to build the project if you prefer a streamlined setup experience. This means you can use the same tools and dependencies as the rest of the team, including our Continuous Integration (CI) workflows, without worrying about installing dependencies on your host machine. Additionally, using Dev Containers makes it simple to switch between local or remote development environments, such as GitHub Codespaces.

See also

More info on Dev Containers can be found here:

What, Why, How?

Lets briefly explain what dev containers are, why you should use them, and how they work.


Here we’ll assume the use of VS Code, but still applies to alternative tools and services, including other CLIs, IDEs, etc. such as:

What is a Dev Container?

A dev container is a Docker container that has all the tools and dependencies you need to develop the project. It runs in a self-contained environment and is isolated from other containers and your host machine. This lets you reliably develop for the project anywhere, notably for linux distributions targeted by ROS, regardless of your host machine’s operating system.

Why use a Dev Container?

A dev container provides a common and consistent development environment. It ensures that everyone on the team is using the same tools and dependencies. It also makes it easy to switch between projects because each project can use a different container. This is especially useful if you work on multiple projects that use different versions of the same tools and dependencies, such as different versions of ROS.

How do Dev Containers work?

When you open the project in VS Code, VS Code checks for the dev container configuration nested within the .devcontainer folder under the project’s root directory. If it finds one, it can prompt you to reopen the project in a container. If you choose to do so, it launches the container, connects to it, and mounts your project folder inside the container. You can then use VS Code in the container just as you would locally. While setting up the container, VS Code can also attempt to passthrough useful aspects of your local environment, such as git user configurations, X11 sockets, and more.

This is quite similar to earlier tools used to customize and run docker containers for development:


To use dev containers, you’ll need the following:


Alternatively, you could use GitHub Codespaces directly from the project repo, or any other remote host machine:

Getting started

Getting started using dev containers is as simple as opening the project in VS Code by either: following the notification prompt to reopen the project in a container, or explicitly opening the command palette (Crtl+Shift+P) and selecting Remote-Containers: Reopen in Container. This will create a new container, install any extensions specified in the project’s default .devcontainer/devcontainer.json config file, and mount the project’s root directory as the workspace folder. Once the container is created, VS Code will connect to it and you can start developing.


Clicking the Starting Dev Container (show log) notification in VS Code allows you to observe in live time how the sausage is made, while typing Dev Containers: Show Log into the command palette will list all the available commands to review and revisit these log files later.

While waiting for the initial setup, feel free to stretch your legs, grab a coffee, or continue to read the following guides to learn more about creating and using dev containers, or how to visualize and leverage graphical user interfaces from a headless development environment.



Ensure you trust the authors and contents of workspaces before launching derived dev containers.

A word of caution when using dev containers: they are powerful tools, but can be a security concern, as the capability of arbitrary code execution facilitated by IDE extensions to enable such automation and convenience remains inherently dual use. Before launching a dev container, ensure you trust the workspaces and authors. For example, when reviewing a pull request, verify patches remain benign and do not introduce any malicious code. Although such vigilance is merited whenever compiling and running patched code, using containers with either elevated privileges or filesystem access renders this diligence even more prudent.

See also

More info on trusting workspaces and extensions in general can be found here: