Skip to main content
These instructions cover Debian-based distributions (Ubuntu, Debian) and Fedora. Basilisk supports Python 3.9 – 3.14 on Linux.
Building on Intel x86_64 processors is tested regularly. Linux on ARM processors has experimental support as of Basilisk 2.1.5, but is not part of the standard CI test matrix.
Depending on your system configuration, some apt-get or dnf commands below require sudo or root access.

​
Install system packages

# Update package lists
sudo apt-get update

# Core build tools (gcc, g++, make, etc.)
sudo apt-get install build-essential

# Python 3 and development headers
sudo apt-get install python3 python3-dev python3-setuptools python3-pip

# Tkinter (needed for certain visualization modules)
sudo apt-get install python3-tk

# Virtual environment support (replace x with your Python minor version, e.g. python3.12-venv)
sudo apt-get install python3.x-venv

# OpenCV dependency — only required if you enable opNav
sudo apt-get install libgtk2.0
Verify your Python version:
python3 --version

​
Build steps

1

Clone the repository

git clone https://github.com/AVSLab/basilisk.git
cd basilisk
2

Create a virtual environment

A virtual environment prevents package conflicts with other Python projects on your system.
python3 -m venv .venv
source .venv/bin/activate
For a specific Python version:
python3.12 -m venv .venv
source .venv/bin/activate
Your prompt will show (.venv) when the environment is active. To deactivate it later:
deactivate
If you choose not to use a virtual environment and install packages into your user directory, add ~/.local/bin to your PATH so that conan, cmake, and swig are available on the command line.
3

Install build dependencies

pip3 install -r requirements_dev.txt
This installs CMake (≥3.26), Conan (≥2.0.5), SWIG (≥4.2.1), and other build tools. Conan repository configuration is handled automatically by conanfile.py.
4

Build Basilisk

From the Basilisk root directory:
python3 conanfile.py
This fetches C++ dependencies with Conan, generates a makefile in dist3/, and compiles the project. A first build on a 4-core machine typically takes 20–40 minutes.
5

Verify the build

Run one of the example scripts:
cd examples
python3 scenarioBasicOrbit.py

​
Build options

Pass options to conanfile.py to customize the build:
OptionDefaultDescription
--vizInterfaceTrueInclude protobuf and ZeroMQ for Vizard connectivity.
--opNavFalseInclude OpenCV for visual navigation modules.
--mujocoFalseInclude MuJoCo physics integration (beta).
--buildProjectTrueCompile after generating the makefile.
--buildTypeReleaseRelease or Debug.
--clean—Delete dist3/ for a fresh build.
--pathToExternalModules—Path to an external modules folder. See Custom modules.
Example — build with opNav enabled and a clean distribution folder: 
python3 conanfile.py --clean --opNav True

​
Incremental builds

Running python3 conanfile.py deletes auto-generated messaging files, which are expensive to recompile. During development, configure once and then build incrementally from the dist3/ folder:
1

Configure without building

python3 conanfile.py --buildProject False
2

Build using make

cd dist3
make -j5
Adjust the -j value to one more than your number of CPU cores for optimal parallel compilation.

​
Speeding up builds with sccache

sccache caches compiled C++ object files to speed up subsequent builds. 
# Debian/Ubuntu
sudo apt-get install sccache

# Fedora
sudo dnf install sccache
Set these environment variables before building: 
export CMAKE_C_COMPILER_LAUNCHER=sccache
export CMAKE_CXX_COMPILER_LAUNCHER=sccache

​
Running tests

python run_all_test.py

Build docs developers (and LLMs) love

Get started for freeTalk to us