CARLA Duckietown

Features  ·  Prebuilt release  ·  Building from source  ·  Getting started  ·  Documentation

Data scarcity is the biggest bottleneck for end-to-end systems in Duckietown. Real footage is limited, and manual labeling is painstakingly slow. CARLA Duckietown solves this by providing photorealistic simulation environments equipped with modular sensors, dynamic lighting, and fully controllable traffic and props.

duckietown_01	duckietown_02	duckietown_03	duckietown_04	duckietown_05	duckietown_06

No Unreal Engine, no 2-hour compile: the packaged build ships the simulator with all six Duckietown maps baked in, plus a matching Python API wheel. The package is Linux-only — on Windows, see Windows below.

Release 1.0 — 2026-08-13 · release notes

• Ubuntu 22.04 or 26.04 and an NVIDIA GPU with at least 8 GB of VRAM.
• 12 GB of disk space once unpacked.
• Python 3.10 or 3.12 — the client is a compiled extension, so it works only with the exact version its wheel was built for. 3.10 is the system Python on 22.04, 3.12 on 26.04.
• One runtime library — the rest of the build requirements do not apply:

sudo apt-get install libvulkan1

1. Download and unpack the simulator. The parts are only meaningful concatenated, so fetch them all and pipe them straight into tar — nothing needs to be reassembled on disk first:

mkdir -p ~/CarlaDuckietown && cd ~/CarlaDuckietown

for p in 00 01 02; do
  curl -fL -C - -O "https://github.com/duckietown/carla/releases/download/1.0/CARLA_Duckietown-1.0.tar.gz.part$p"
done

cat CARLA_Duckietown-1.0.tar.gz.part* | tar -xzf -
rm CARLA_Duckietown-1.0.tar.gz.part*

curl -C - resumes, so re-running the loop after a dropped connection picks up where it left off rather than starting over.

2. Install the Python client. Use the wheel bundled under PythonAPI/carla/dist — it is built against this exact release. A carla wheel from PyPI will not work:

python3 -m pip install --upgrade -r PythonAPI/carla/requirements.txt
python3 -m pip install PythonAPI/carla/dist/carla_duckietown-*.whl

Client only. If the simulator runs on another machine and you just need the Python API, skip the package entirely and install the wheel for your Python version straight from the release:

python3 -m pip install https://github.com/duckietown/carla/releases/download/1.0/carla_duckietown-1.0-cp310-cp310-linux_x86_64.whl

Keep the client and the server on the same release. A wheel from a different build will warn about a version mismatch on connect.

The distribution is named carla_duckietown but it still provides the carla module, so it cannot coexist with upstream's carla package — pip will not spot the conflict for you. If you have ever installed carla from PyPI, remove it first:

python3 -m pip uninstall carla

./CarlaUE4.sh                              # windowed, boots into duckietown_01
./CarlaUE4.sh -RenderOffScreen             # headless, for data generation
./CarlaUE4.sh -quality-level=Low           # cheaper rendering
./CarlaUE4.sh -carla-rpc-port=3000         # non-default port

The server listens on ports 2000 and 2001 by default. The first launch is slower while shaders warm up. With the simulator running, continue to Getting started — every script works the same as in a source build.

Frame rate. Rendering is capped at 60 FPS. The Duckietown maps are light enough that an uncapped server idles at several hundred frames per second, which buys nothing and makes some GPUs whine. To change it, edit FrameRateLimit in CarlaUE4/Config/DefaultGameUserSettings.ini, or in ~/.config/Epic/CarlaUE4/Saved/Config/LinuxNoEditor/GameUserSettings.ini once that file exists — the saved copy wins. 0 is uncapped.

Note that this is a rendering cap and is independent of simulation timing: the -benchmark and -fps= command line flags have no effect on a packaged build, and for reproducible, evenly spaced sensor captures you want fixed_delta_seconds and synchronous_mode from the client instead.

Build from source if you want the Unreal Editor, need to change the C++ code, or want to author your own maps and assets. Otherwise the prebuilt release above is the shorter road.

→ Linux build guide

The full procedure lives there. In outline:

Budget 3-4 hours and 130 GB of disk space; most of both goes to Unreal Engine. A dedicated NVIDIA GPU with 8 GB of VRAM or more and 32 GB of RAM make for a comfortable workflow in the Editor. The F.A.Q. covers the most common complications.

We develop exclusively on Ubuntu and cannot make any guarantees for Windows. That said, CARLA itself builds natively on Windows and this fork keeps that toolchain intact, so a Windows build should be within reach: follow the upstream Windows instructions, substituting this repository for carla-simulator/carla.

Update.bat mirrors Update.sh, including the Duckietown content download and the same -s / -d flags — but that half has never been run on Windows, so expect to fix something. It additionally needs python on PATH with the requests package, and tar.exe (shipped with Windows 10 1803 and newer, with 7-Zip as a fallback). If it fails, the archive can always be fetched by hand from the ID in Util/DuckietownContentVersions.txt and extracted into Unreal\CarlaUE4\Content.

With the simulator running, in a second terminal:

cd PythonAPI/duckietown
python3 manual_control.py          # drive a Duckiebot

• Python API reference — including set_hdri_preset, get_hdri_presets and set_hidden_in_game
• Sensors reference — semantic tags, including Duckietown tags 29–35
• Blueprint library — every spawnable actor
• Core concepts — client, world, actors, sensors

Contributions are welcome — open an issue or a pull request.

This build inherits CARLA's licensing. CARLA specific code is distributed under MIT License; CARLA specific assets under CC-BY License.

The ad-rss-lib library compiled and linked by the RSS Integration build variant introduces LGPL-2.1-only License.

Unreal Engine 4 follows its own license terms.

CARLA uses three dependencies as part of the SUMO integration:

• PROJ, a generic coordinate transformation software which uses the X/MIT open source license.
• SQLite, part of the PROJ dependencies, which is in the public domain.
• Xerces-C, a validating XML parser, which is made available under the Apache Software License, Version 2.0.

CARLA uses one dependency as part of the Chrono integration:

• Eigen, a C++ template library for linear algebra which uses the MPL2 license.

CARLA uses the Autodesk FBX SDK for converting FBX to OBJ in the import process of maps. This step is optional, and the SDK is located here

This software contains Autodesk® FBX® code developed by Autodesk, Inc. Copyright 2020 Autodesk, Inc. All rights, reserved. Such code is provided "as is" and Autodesk, Inc. disclaims any and all warranties, whether express or implied, including without limitation the implied warranties of merchantability, fitness for a particular purpose or non-infringement of third party rights. In no event shall Autodesk, Inc. be liable for any direct, indirect, incidental, special, exemplary, or consequential damages (including, but not limited to, procurement of substitute goods or services; loss of use, data, or profits; or business interruption) however caused and on any theory of liability, whether in contract, strict liability, or tort (including negligence or otherwise) arising in any way out of such code."

• Paul Masan
• Simon Rappenecker