Linux build

The build process can be quite long and tedious. The F.A.Q. page offers solution for the most common complications. Alternatively, use the CARLA forum to post any unexpected issues that may occur.


Linux build command summary

Show command lines to build on Linux
# Make sure to meet the minimum requirements
# Read the complete documentation to understand each step

# Install dependencies
sudo apt-get update &&
sudo apt-get install wget software-properties-common &&
sudo add-apt-repository ppa:ubuntu-toolchain-r/test &&
wget -O - https://apt.llvm.org/llvm-snapshot.gpg.key|sudo apt-key add - &&
sudo apt-add-repository "deb http://apt.llvm.org/$(lsb_release -c --short)/ llvm-toolchain-$(lsb_release -c --short)-8 main" &&
sudo apt-get update

# Additional dependencies for Ubuntu 18.04
sudo apt-get install build-essential clang-8 lld-8 g++-7 cmake ninja-build libvulkan1 python python-pip python-dev python3-dev python3-pip libpng-dev libtiff5-dev libjpeg-dev tzdata sed curl unzip autoconf libtool rsync libxml2-dev &&
pip2 install --user setuptools &&
pip3 install --user -Iv setuptools==47.3.1

# Additional dependencies for previous Ubuntu versions
sudo apt-get install build-essential clang-8 lld-8 g++-7 cmake ninja-build libvulkan1 python python-pip python-dev python3-dev python3-pip libpng16-dev libtiff5-dev libjpeg-dev tzdata sed curl unzip autoconf libtool rsync libxml2-dev &&
pip2 install --user setuptools &&
pip3 install --user -Iv setuptools==47.3.1 &&
pip2 install --user distro &&
pip3 install --user distro

# Change default clang version
sudo update-alternatives --install /usr/bin/clang++ clang++ /usr/lib/llvm-8/bin/clang++ 180 &&
sudo update-alternatives --install /usr/bin/clang clang /usr/lib/llvm-8/bin/clang 180

# Get a GitHub and a UE account, and link both
# Install git

# Download Unreal Engine 4.24
git clone --depth=1 -b 4.24 https://github.com/EpicGames/UnrealEngine.git ~/UnrealEngine_4.24
cd ~/UnrealEngine_4.24

# Download and install the UE patch
wget https://carla-releases.s3.eu-west-3.amazonaws.com/Linux/UE_Patch/430667-13636743-patch.txt 430667-13636743-patch.txt
patch --strip=4 < 430667-13636743-patch.txt

# Build UE
./Setup.sh && ./GenerateProjectFiles.sh && make

# Open the UE Editor to check everything works properly
cd ~/UnrealEngine_4.24/Engine/Binaries/Linux && ./UE4Editor

# Clone the CARLA repository
git clone https://github.com/carla-simulator/carla

# Get the CARLA assets
cd ~/carla
./Update.sh

# Set the environment variable
export UE4_ROOT=~/UnrealEngine_4.24

# make the CARLA client and the CARLA server
make PythonAPI
make launch

# Press play in the Editor to initialize the server
# Run example scripts to test CARLA
# Terminal A 
cd PythonAPI/examples
python3 spawn_npc.py 
# Terminal B
cd PythonAPI/examples
python3 spawn_npc.py # Support for Python2 was provided until 0.9.10 (not included)
python3 dynamic_weather.py # Support for Python2 was provided until 0.9.10 (not included)

# Optionally, to compile the PythonAPI for Python2, run the following command in the root CARLA directory
make PythonAPI ARGS="--python-version=2"

Requirements

System specifics

  • Ubuntu 18.04. CARLA provides support for previous Ubuntu versions up to 16.04. However proper compilers are needed for UE to work properly. Dependencies for Ubuntu 18.04 and previous versions are listed separatedly below. Make sure to install the ones corresponding to your system.
  • 30GB disk space. The complete build will require quite a lot of space, especially Unreal Engine. Make sure to have around 30/50GB of free disk space.
  • An adequate GPU. CARLA aims for realistic simulations, so the server needs at least a 4GB GPU. A dedicated GPU is highly recommended for machine learning.
  • Two TCP ports and good internet connection. 2000 and 2001 by default. Be sure neither the firewall nor any other application block these.

Dependencies

CARLA needs many dependencies to run. Some of them are built automatically during this process, such as Boost.Python. Others are binaries that should be installed before starting the build (cmake, clang, different versions of Python and much more). In order to do so, run the commands below in a terminal window.

sudo apt-get update &&
sudo apt-get install wget software-properties-common &&
sudo add-apt-repository ppa:ubuntu-toolchain-r/test &&
wget -O - https://apt.llvm.org/llvm-snapshot.gpg.key|sudo apt-key add - &&
sudo apt-add-repository "deb http://apt.llvm.org/xenial/ llvm-toolchain-xenial-8 main" &&
sudo apt-get update

Warning

The following commands depend on your Ubuntu version. Make sure to choose accordingly.

Ubuntu 18.04.

sudo apt-get install build-essential clang-8 lld-8 g++-7 cmake ninja-build libvulkan1 python python-pip python-dev python3-dev python3-pip libpng-dev libtiff5-dev libjpeg-dev tzdata sed curl unzip autoconf libtool rsync libxml2-dev &&
pip2 install --user setuptools &&
pip3 install --user -Iv setuptools==47.3.1 &&
pip2 install --user distro &&
pip3 install --user distro

Previous Ubuntu versions.

sudo apt-get install build-essential clang-8 lld-8 g++-7 cmake ninja-build libvulkan1 python python-pip python-dev python3-dev python3-pip libpng16-dev libtiff5-dev libjpeg-dev tzdata sed curl unzip autoconf libtool rsync libxml2-dev &&
pip2 install --user setuptools &&
pip3 install --user -Iv setuptools==47.3.1 &&
pip2 install --user distro &&
pip3 install --user distro

All Ubuntu systems.
To avoid compatibility issues between Unreal Engine and the CARLA dependencies, use the same compiler version and C++ runtime library to compile everything. The CARLA team uses clang-8 and LLVM's libc++. Change the default clang version to compile Unreal Engine and the CARLA dependencies.

sudo update-alternatives --install /usr/bin/clang++ clang++ /usr/lib/llvm-8/bin/clang++ 180 &&
sudo update-alternatives --install /usr/bin/clang clang /usr/lib/llvm-8/bin/clang 180

GitHub

1. Create a GitHub account. CARLA is organized in different GitHub repositories, so an account will be needed to clone said repositories.

2. Install git to manage the repositories via terminal.

3. Create an Unreal Engine account to access the Unreal Engine repositories, which are set to private.

4. Connect both your GitHub and Unreal Engine accounts. Go to your personal settings in there is a section in Unreal Engine's website. Click on Connections > Accounts, and link both accounts. Here is a brief explanation just in case.

Warning

New Unreal Engine accounts need activation. After creating the account, a verification mail will be sent. Check it out, or the UE repository will be shown as non-existent in the following steps.


Unreal Engine

The current version of CARLA runs on Unreal Engine 4.24 only. In this guide, the installation will be done in ~/UnrealEngine_4.24, but the path can be changed. If your path is different, change the following commands accordingly.

Note

Alternatively to this section, there is another guide to build UE on Linux. When consulting it, remember that CARLA will need the 4.24 release, not the latest.

1. Clone the content for Unreal Engine 4.24 in your local computer.

git clone --depth=1 -b 4.24 https://github.com/EpicGames/UnrealEngine.git ~/UnrealEngine_4.24

2. Get into the directory where UE4.24 has been cloned.

cd ~/UnrealEngine_4.24

3. Download a patch for Unreal Engine. This patch fixes some Vulkan visualization issues that may occur when changing the map. Download and install it with the following commands.

wget https://carla-releases.s3.eu-west-3.amazonaws.com/Linux/UE_Patch/430667-13636743-patch.txt 430667-13636743-patch.txt
patch --strip=4 < 430667-13636743-patch.txt

Warning

If UE has already been built, install the patch, and make the build again.

4. Make the build. This may take an hour or two depending on your system.

./Setup.sh && ./GenerateProjectFiles.sh && make

5. Open the Editor to check that UE has been properly installed.

cd ~/UnrealEngine_4.24/Engine/Binaries/Linux && ./UE4Editor

Any issues this far are related with Unreal Engine. There is not much CARLA can do about it. However, the build documentation provided by Unreal Engine may be helpful.


CARLA build

The system should be ready to start building CARLA. Just for clarity, a brief summary so far.

  • Minimum technical requirements to run CARLA are suitable.
  • Dependencies have been properly installed.
  • GitHub account is ready.
  • Unreal Engine 4.24 runs smooth.

Note

Downloading aria2 with sudo apt-get install aria2 will speed up the following commands.

Clone repository

The official repository of the project. Either download and extract it, or clone the repository with the following command line.

git clone https://github.com/carla-simulator/carla

Now the latest state of the simulator, known as master branch in the repository, has been copied in local. Here is brief introduction to the most relevant branches of the repository. Remember that you can change and check your branches with the command git branch.

  • master branch — Latest fixes and features that have been tested. These will be featured in the next CARLA release.
  • dev branch — Latest fixes and features still in development and testing. This branch will be merged with master when the time for a new release comes.
  • stable branch — Latest version of CARLA tagged as stable. Previous CARLA versions also have their own branch.

Get assets

Download the assets, as they are necessary to run CARLA. These are stored in a separated package to reduce the size of the build. A script downloads and extracts the latest stable assets automatically. The package is >3GB, so the download may take some time.

1. Get into your root carla directory. The path should correspond with the repository just cloned.

cd ~/carla

2. Run the script to get the assets.

./Update.sh

Important

To download the assets currently in development, visit Update CARLA and read Get development assets.

Set the environment variable

This is necessary for CARLA to find the Unreal Engine 4.24 installation folder.

export UE4_ROOT=~/UnrealEngine_4.24

The variable should be added to ~/.bashrc or ~/.profile to be set persistently session-wide. Otherwise, it will only be accessible from the current shell. To do this, follow these steps.

1. Open ~/.bashrc.

gedit ~/.bashrc

2. Write the environment variable in the ~/.bashrc file: export UE4_ROOT=~/UnrealEngine_4.24

3. Save the file and reset the terminal.

make CARLA

The last step is to finally build CARLA. There are different make commands to build the different modules. All of them run in the root CARLA folder.

Warning

Make sure to run make PythonAPI to prepare the client and make launch for the server. Alternatively make LibCarla will prepare the CARLA library to be imported anywhere.

  • make PythonAPI compiles the API client, necessary to grant control over the simulation. It is only needed the first time. Remember to run it again when updating CARLA. Scripts will be able to run after this command is executed.
make PythonAPI
  • make launch compiles the server simulator and launches Unreal Engine. Press Play to start the spectator view and close the editor window to exit. Camera can be moved with WASD keys and rotated by clicking the scene while moving the mouse around.
make launch

The project may ask to build other instances such as UE4Editor-Carla.dll the first time. Agree in order to open the project. During the first launch, the editor may show warnings regarding shaders and mesh distance fields. These take some time to be loaded and the city will not show properly until then.

Finally, let's test the simulator. Inside PythonAPI/examples and PythonAPI/util there are some example scripts that may be especially useful for starters. The following commands will spawn some life into the town, and create a weather cycle. Each script should be run in one terminal

# Support for Python2 was provided until 0.9.10 (not included)
# Terminal A 
cd PythonAPI/examples
python3 spawn_npc.py  
# Terminal B
cd PythonAPI/examples
python3 dynamic_weather.py 

Important

If the simulation is running at very low FPS rates, go to Edit/Editor preferences/Performance in the UE editor and disable Use less CPU when in background.

Optionally, to compile the PythonAPI for Python2, run the following command in the root CARLA directory.

make PythonAPI ARGS="--python-version=2"

Now CARLA is ready to go. Here is a brief summary of the most useful make commands available.

Command Description
make help Prints all available commands.
make launch Launches CARLA server in Editor window.
make PythonAPI Builds the CARLA client.
make package Builds CARLA and creates a packaged version for distribution.
make clean Deletes all the binaries and temporals generated by the build system.
make rebuild make clean and make launch both in one command.

Read the F.A.Q. page or post in the CARLA forum for any issues regarding this guide.

Some recommendations after finishing the build. Learn how to update the CARLA build or take your first steps in the simulation, and learn some core concepts.