Install

Basilisk can be installed either from PyPI as a prebuilt wheel or built locally from source. The prebuilt wheels include all build options, such as optical navigation and MuJoCo dynamics, but do not support linking external C++ modules, as this requires rebuilding Basilisk.

If you want to use custom C++ modules, or prefer smaller install sizes by excluding unused features, you must build Basilisk from source. See the Building from Source for more information.

Note

We are currently investigating ways to allow users to link external C++ modules while using the prebuilt PyPI wheel. Stay tuned!

The easiest way to install Basilisk is using pip to install the prebuilt package from PyPI. Run:

pip install bsk

Or, if using uv (a modern Python package manager):

uv pip install bsk

This installs the latest stable version of Basilisk and all dependencies. To install a specific version, run:

pip install bsk==<version>

Replace <version> with the desired release number, e.g. 2.9.0.

Prebuilt wheel availability:

  • Windows: Windows 10/11 (x86_64)

  • macOS: macOS 11+ (x86_64 and Apple Silicon arm64)

  • Linux: Manylinux 2.24+ (x86_64, aarch64)

All wheels are built as ABI3 packages for Basilisk supported Python versions.

Note

On unsupported systems or Python versions, pip will automatically download the source archive (.tar.gz) and build Basilisk locally. This requires a C++ compiler toolchain and standard build tools to be installed on your system.

To keep the wheel size smaller, the large BSK data files are not installed by default. If the user wants to use a script that that needs BSK data it will be downloaded automatically using pooch. If you want to force all data to be downloaded at once, then go to the command line, change the current directory to be inside the environment where Basilisk was pip installed, and run the command:

bskLargeData

This command runs a python file stored in the src/utilities folder. The pip install process automatically creates this console command in the current python environment to call this python file. The file directly downloads the missing large BSK data files and put them into the local Basilisk python package installation.