Skip to main content
These instructions cover a clean macOS setup. Basilisk supports Python 3.9 – 3.14 on both Intel and Apple Silicon (M-series) Macs.
If you have an M-series Mac, download a Python build that targets the ARM64 architecture. The python.org installer provides Universal binaries for Python 3.9 and later.

​
Required tools

1

Install Xcode

Download Xcode from the Mac App Store. After the download finishes, launch Xcode once to let it complete the component installation, then install the command-line tools:
xcode-select --install
2

Install Python 3

Download and run the macOS installer from python.org. This configures your system for Python 3 and can be upgraded by downloading a newer installer later.Alternatively, use Homebrew:
brew install python3
Confirm the installation:
python3 --version
3

Clone the repository

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

Create a virtual environment

A virtual environment isolates Basilisk’s dependencies from the rest of your system.
python3 -m venv .venv
source .venv/bin/activate
Your prompt will show (.venv) when the environment is active. To deactivate it later:
deactivate
5

Install build dependencies

This installs CMake, Conan, SWIG, and other build tools:
pip3 install -r requirements_dev.txt
Conan repository configuration is handled automatically by conanfile.py.
6

Build Basilisk

From the Basilisk root directory, run:
python3 conanfile.py
This fetches C++ dependencies, generates an Xcode project inside dist3/, and compiles the project. A first build typically takes 15–30 minutes depending on your hardware and the options you enable.
The default build type is Release. When you open the project in Xcode, build using Product → Build For → Profiling to stay in Release mode. Using the regular Build action builds for Debug, which will fail to find the Conan-installed Release libraries.
7

Verify the build

Run one of the example scripts to confirm everything works:
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 project file.
--buildTypeReleaseRelease or Debug.
--clean—Delete dist3/ before configuring for a fresh build.
--pathToExternalModules—Path to an external modules folder. See Custom modules.
Example — build with opNav, no Vizard, and a clean distribution folder: 
python3 conanfile.py --clean --opNav True --vizInterface False

​
Building in Xcode (IDE)

If you want to configure the project without compiling immediately — useful during development — disable the automatic build step: 
python3 conanfile.py --buildProject False
Then open dist3/basilisk.xcodeproj in Xcode. Set the active scheme to ALL_BUILD, and build with Product → Build For → Profiling.

​
Speeding up builds with sccache

sccache caches compiled C++ object files, dramatically reducing clean-build times. 
brew install sccache
Set these environment variables before building: 
export CMAKE_C_COMPILER_LAUNCHER=sccache
export CMAKE_CXX_COMPILER_LAUNCHER=sccache
Check cache statistics after a build: 
sccache --show-stats

​
Running tests

python run_all_test.py

​
Common issues

Run:
xcode-select -p
The output should be /Applications/Xcode.app/Contents/Developer. If you see /Library/Developer/CommandLineTools or another path, reset the developer directory:
sudo xcode-select --reset
Clear the CMake cache (delete dist3/) and run python3 conanfile.py again.
A macOS update can invalidate the compiler path or invalidate cached build artifacts. Perform a clean build:
python3 conanfile.py --clean
Clone the repository into the default directory first, then move the folder to your preferred location after cloning completes.

Build docs developers (and LLMs) love

Get started for freeTalk to us