What you will need

  • A computer running macOS or Windows

What you will get

  • A Duckietown Workspace installation

Attention

If you have already installed Ubuntu on your computer, skip this page and proceed to setting up your accounts.

Workspace installation (macOS and Windows)#

This page details how to set up a Duckietown environment inside a Development (Dev) Container using Visual Studio Code.

Note

Duckietown Workspaces are the only supported workflow for running Duckietown software on an Apple Silicon (M-series) Mac and on Windows.

Warning

You can report bugs and constructive feedback in the Duckietown Slack community channel #beta-devcontainer or by email at info@duckietown.com.

Host System Container Installation#

Depending on your host machine operating system, instructions vary slightly.

Attention

If you have Docker Desktop installed on your host machine, uninstall it and reboot before continuing.

First, install Orbstack, a lightweight container runtime that supports Apple Silicon (M-series) Macs.

To install Orbstack:

  1. Download the Orbstack .dmg file.

  2. Navigate to your Downloads folder.

  3. Double-click the .dmg file.

  4. Move the application to your Applications folder.

Tip

If your Mac refuses to open an application because it is not trusted, hold down the option key and right-click it, then select Open. Your Mac will inform you that the application is not trusted but will allow you to open it. Alternatively, whitelist the app from the “Privacy and Security” section of your Mac’s System Settings.

Duckietown Workspace: Windows 11 installation tutorial

This video is a third-party contribution kindly created by Irina Zheleznova, Senior Lecturer at Academy of Civil Aviation, Almaty, Kazakhstan, and her students Zhanibek Kenshilik and Andrey Shilovsky.

On Windows, we will be installing WSL with Ubuntu and Docker Desktop.

Attention

The following instructions use Windows Terminal, which comes preinstalled with Windows 11 version 22H2 and later. If you do not have it installed, you can download it from the Microsoft Store.

To install WSL and Ubuntu on Windows:

  1. Install WSL by opening up the Windows Terminal and running

    wsl --install

  2. Reboot your computer after the installation is complete.

  3. Install Ubuntu by running

    wsl --install ubuntu

  4. Follow on-screen instructions to set up an account in Ubuntu on WSL.

Installing Docker Desktop:

  1. Install Docker Desktop from https://www.docker.com/

  2. Start Ubuntu by running wsl in the Windows Terminal.

Important

From now on, cloning and running the devcontainer should be done from the wsl terminal, except when otherwise specified.

Installing Visual Studio Code#

To install Visual Studio Code:

  1. Download the appropriate VS Code .zip file.

  2. Navigate to your Downloads folder.

  3. Double-click the .zip file.

  4. (On Mac) Move the application to your Applications folder.

Installing the necessary VS Code extensions#

To install the Remote - Containers extension in VS Code:

  1. Open VS Code.

  2. Click on the Extensions icon in the left sidebar (or press Ctrl+Shift+X on Windows or Cmd+Shift+X on macOS).

  3. In the search bar, type Remote - Containers.

  4. Click on the Install button next to the Remote - Containers extension by Microsoft.

  5. (Windows only) Follow the same instructions to also install the WSL extension.

Cloning the workspace repository#

To clone the workspace repository, run:

git clone [email protected]:duckietown/workspace.git

Attention

Ignore the instructions in the README of this repository.

(Windows) If you are on Windows, make sure to run the above command from the wsl terminal.

Running the Dev Container in VS Code#

To run the Dev Container in VS Code:

  1. Open VS Code and navigate to the workspace folder (File -> Open Folder... -> /path/to/workspace). You should see a popup appear in the bottom-right corner of your screen containing the message “Folder contains a Dev Container configuration file. Reopen folder to develop in a container (learn more).”.

  2. Click the Reopen in Container button.

  3. (Optional) Click the Reading Dev Container Configuration (show log) link.

Note

The first time you load the Dev Container it may take some time as it is building the environment.

Note

To create a new local integrated terminal (outside the Dev Container), open the VS Code Command Palette (Shift+Cmd+P on macOS or Shift+Ctrl+P on Windows), enter Terminal: Create New Integrated Terminal (Local) and press Enter.

Note

If you are using a Duckietown Workspace, Duckietown Viewer apps and Duckiematrix renderer-only commands such as dts matrix run must be run from a local integrated terminal outside the Dev Container. Commands such as dts matrix run --standalone start both the Engine and the Renderer in the same environment. Browser-based variants can be run inside or outside the Dev Container.

Setting up the Duckietown Shell on the host machine#

The Duckietown Shell is pre-installed in the workspace, so there is no need to re-install it. It is necessary though to configure it with your user credentials, which can be done by following the Duckietown Shell first boot setup instructions inside the workspace.

Tip

Some Duckietown robot apps, such as the image viewer or keyboard controller, can be visualized natively on the host machine instead of inside a noVNC desktop, resulting in a better experience. To enable this, set up the Duckietown Shell on the host machine as well.

Installing the Duckietown Shell on the host machine#

On your host machine, open a terminal and install Brew if you have not done so already:

/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

and proceed to install Python:

brew install [email protected]

Note

Compatible versions of Python are 3.10/3.11/3.12.

Confirm the installation was successful:

Test

Run:

/opt/homebrew/bin/python3.12 --version

Expected Result

Python 3.12.13

Before installing dts, remove any previously failed pipx attempts:

pipx uninstall duckietown-shell

Then (re)install the Duckietown Shell using Python 3.12 explicitly:

pipx install --python /opt/homebrew/bin/python3.12 duckietown-shell

And finally refresh the shell path with:

pipx ensurepath

and

exec zsh

To confirm the installation was successful:

Test

Run:

dts

Expected Result

username@computername ~ % dts
____  _   _  ____ _  _____ _____ _____ _____        ___   _     ____  _   _ _____ _     _
|  _ \| | | |/ ___| |/ /_ _| ____|_   _/ _ \ \      / / \ | |   / ___|| | | | ____| |   | |
| | | | | | | |   | ' / | ||  _|   | || | | \ \ /\ / /|  \| |   \___ \| |_| |  _| | |   | |
| |_| | |_| | |___| . \ | || |___  | || |_| |\ V  V / | |\  |    ___) |  _  | |___| |___| |___
|____/ \___/ \____|_|\_\___|_____| |_| \___/  \_/\_/  |_| \_|   |____/|_| |_|_____|_____|_____|
_______________________________________________________________________________________________
First Setup - Welcome!                                                                  v6.2.26

+-------------------------------------------------------------------------------------------------------------------------+
2026-06-01 15:08:11 computername.local shell[32591] INFO Installing bash-completion script...
2026-06-01 15:08:11 computername.local shell[32591] INFO Bash-completion script successfully installed

You need to choose the distribution you want to work with.
? Choose a distribution:
>> ente
daffy

Note

Host machine dts installations are not fully functional, but useful in specific circumstances. Continue using the Duckietown Shell inside your VS Code Workspace as default Duckietown Shell, and refer to the host machine dts only when instructed to do so.

To set up the Duckietown Shell on the host machine, install Python 3.10/3.11/3.12 and then follow the Duckietown Shell setup instructions.

Attention

If a popup asking you to input your credentials appears, you should do so and then click Always Allow.

Known bugs and other caveats#

Attention

There is a known bug for which dts fleet discover ran inside the workspace will not find physical robots on the same network. Nonetheless, all other functions (e.g., pinging, updating, controlling, etc.) are unaffected by this bug.

Running dts code editor#

To be able to run dts code editor, you need to install mkcert on your host system:

  1. Run brew install mkcert or download the darwin binary for your system’s architecture.

  2. Run mkcert -install (to install the local CA in your system).

  1. Download mkcert for Windows from this link, saving it to your Downloads folder.

  2. Then, open the Windows Terminal and run:

    .\Downloads\mkcert-v1.4.4-windows-amd64.exe --install

  3. Select Yes in the prompt.

  4. In the Ubuntu terminal, open the ~/.bashrc file with a text editor, e.g., by running nano ~/.bashrc, and append the following lines at the end of the file:

    WINUSER=$(powershell.exe '$env:USERNAME' | tr -d '\r')
export MKCERT_PATH="/mnt/c/Users/$WINUSER/AppData/Local/mkcert"

  5. Save and exit the text editor (in nano, press Ctrl+X, Enter, then Enter).

  6. Finally, run source ~/.bashrc to update the current shell or open a new wsl terminal window.