Building from source¶

Here we describe how to build ViZDoom from source. If you want to install pre-build ViZDoom wheels for Python, see Python quick start.

Dependencies¶

To build ViZDoom (regardless of the method), you need to install some dependencies in your system first.

Linux¶

To build ViZDoom on Linux, the following dependencies are required:

CMake 3.12+
Make
GCC 6.0+
Boost libraries 1.54.0+
Python 3.7+ for Python binding (optional)

Also some of additionally ZDoom dependencies are needed.

apt-based distros (Ubuntu, Debian, Linux Mint, etc.)¶

To get all dependencies on apt-based Linux (Ubuntu, Debian, Linux Mint, etc.) execute the following commands in the shell (might require root access).

# All possible ViZDoom dependencies,
# most are optional and required only to support alternative sound and music backends in the engine
# other can replace libraries that are included in the ViZDoom repository
apt install build-essential cmake git libsdl2-dev libboost-all-dev libopenal-dev \
zlib1g-dev libjpeg-dev tar libbz2-dev libgtk2.0-dev libfluidsynth-dev libgme-dev \
timidity libwildmidi-dev unzip

# Only essential ViZDoom dependencies
apt install build-essential cmake git libboost-all-dev libsdl2-dev libopenal-dev

# Python 3 dependencies (alternatively Anaconda 3 installed)
apt install python3-dev python3-pip
# or install Anaconda 3 and add it to PATH

dnf/yum-based distros (Fedora, RHEL, CentOS, Alma/Rocky Linux, etc.)¶

To get all dependencies on dnf/yum-based Linux (Fedora, RHEL, CentOS, Alma/Rocky Linux, etc.) execute the following commands in the shell (might require root access).

# Essential ZDoom dependencies
dnf install cmake git boost-devel SDL2-devel openal-soft-devel

# Python 3 dependencies (alternatively Anaconda 3 installed)
dnf install python3-devel python3-pip

Anaconda/Miniconda¶

If you do not have a root access, you can use a conda (e.g. miniconda) environment to install dependencies to your environment only:

conda install -c conda-forge boost cmake gtk2 sdl2

Note that to install ViZDoom in a conda environment you have to pull, build and install ViZDoom manually with

git clone https://github.com/mwydmuch/ViZDoom.git
cd ViZDoom
python setup.py build && python setup.py install

MacOS¶

To build ViZDoom on MacOS, the following dependencies are required:

CMake 3.12+
Clang 5.0+
Boost libraries 1.54.0+
Python 3.7+ for Python binding (optional)

Also some of additionally ZDoom dependencies are needed.

To get all the dependencies install homebrew first, than execute the following commands in the shell:

brew install cmake boost sdl2 openal-soft

Windows¶

CMake 3.12+
Visual Studio 2012+
Boost libraries 1.54.0+
Python 3.7+ for Python binding (optional)

Additionally, ZDoom dependencies are needed. Most of them (except Boost) are gathered in this repository: ViZDoomWinDepBin. You can download Boost from here.

Building via pip (recommended for Python users)¶

ViZDoom for Python can be build via pip on Linux, MacOS and Windows, and it is strongly recommended. Even when building using pip you still need to install dependencies.

To build the newest version from the repository run:

pip install git+https://github.com/mwydmuch/ViZDoom.git

git clone https://github.com/mwydmuch/ViZDoom.git
cd ViZDoom
pip install .

On Linux and MacOS dependencies should be found automatically. On Windows you need to manually set following environment variables:

BOOST_ROOT - the path to the directory with Boost libraries (e.g. C:\boost_1_76_0),
VIZDOOM_BUILD_GENERATOR_NAME - generator name (e.g. Visual Studio 16 2019),
VIZDOOM_WIN_DEPS_ROOT - the path to the directory with ZDoom dependencies (e.g. C:\ViZDoomWinDepBin).

The process of building ViZDoom this way on Windows is demonstarted in scripts/windows_build_wheels.bat.

Building manylinux wheels¶

To build manylinux wheels you need to install docker and cibuildwheel. Then on Linux and MacOS run in ViZDoom root directory:

cibuildwheel --platform linux

The binary ViZDoom wheels will be placed in wheelhouse directory. In case of building using cibuildwheel, the dependencies are installed automatically inside the docker container, so you do not need to install them manually in your system.

Building manually (not recommended)¶

Instructions below can be used to build ViZDoom manually. We recommend doing it only if you want to use C++ API, work on the ViZDoom, or if you have problems with pip installation.

Linux / MacOS¶

In ViZDoom’s root directory:

mkdir build
cd build
cmake .. -DCMAKE_BUILD_TYPE=Release -DBUILD_ENGINE=ON -DBUILD_PYTHON=ON
make

where -DBUILD_ENGINE=ON and -DBUILD_PYTHON=ON CMake options are optional (default ON).

Windows¶

Run CMake GUI or cmake command in cmd/powershell in ViZDoom root directory with the following paths provided:

BOOST_ROOT
BOOST_INCLUDEDIR
BOOST_LIBRARYDIR
PYTHON_INCLUDE_DIR (optional, for Python/Anaconda bindings)
PYTHON_LIBRARY (optional, for Python/Anaconda bindings)
ZDoom dependencies paths

In configuration select DBUILD_ENGINE and DBUILD_PYTHON (optional, default ON).
Use generated Visual Studio solution to build all parts of ViZDoom environment.

The process of building ViZDoom this way on Windows is demonstarted in scripts/windows_build_cmake.bat script.

Compilation output¶

Compilation output will be placed in build/bin and it should contain the following files.

bin/vizdoom / vizdoom.exe - ViZDoom executable
bin/vizdoom.pk3 - resources file used by ViZDoom (needed by ViZDoom executable)
bin/libvizdoom.a / vizdoom.lib - C++ ViZDoom static library
bin/libvizdoom.so / vizdoom.dll / libvizdoom.dylib - C++ ViZDoom dynamically linked library
bin/pythonX.X/vizdoom.so / vizdoom.pyd / vizdoom.dylib - ViZDoom Python X.X module
bin/pythonX.X/vizdoom - complete ViZDoom Python X.X package

Manual installation¶

To manually install Python package copy vizdoom_root_dir/build/bin/pythonX.X/vizdoom contents to python_root_dir/lib/pythonX.X/site-packages/site-packages/vizdoom.