Skip to main content
The quickest way to install Basilisk is via pip:
pip install bsk
This installs a pre-compiled wheel for your platform and Python version. Supported Python versions are 3.9 through 3.13.
The pip-installed package does not include the supportData folder. Data files are managed by pooch and downloaded to a system cache directory on first use. See the question below on how to access data file paths.
If you need to build from source (for example, to enable the opNav module or use external C++ modules), follow the build-from-source instructions using python conanfile.py.
Run the bskExamples command after installing Basilisk:
bskExamples
This downloads a copy of the tutorial example scripts to your current directory. The examples are the recommended starting point for learning how to use Basilisk — run them from the basilisk/examples/ folder to see working simulations.
Yes, but you must build Basilisk from source. Pre-compiled pip wheels do not support external C++ module integration.To add an external module:
  1. Place your module source files in the src/externalModules/ directory.
  2. Rebuild Basilisk using python conanfile.py.
  3. Import your module in Python using from Basilisk.externalModules import myModule.
Your SWIG *.i file must include the necessary Basilisk SWIG helpers. See the coding guidelines for required includes.
Navigate to the basilisk/src/ directory and run pytest:
cd basilisk/src
pytest
To run tests faster using multiple parallel processes:
pytest -n auto
To run the complete test suite including C/C++ gtest unit tests:
python run_all_test.py
To generate an HTML validation report:
pytest --report
On Windows, running pytest directly from within basilisk/src/ may fail with ImportError due to Python path resolution. Navigate into the specific subdirectory you want to test before running pytest.
When reporting a bug, include your Basilisk version (import Basilisk; print(Basilisk.__version__)), OS, Python version, and a minimal reproducing example.
Basilisk uses a publish-subscribe message passing system to connect modules. Each module declares typed input messages (which it reads) and output messages (which it writes). Modules are connected by subscribing an input message to an output message:
# Module A writes to attGuidOutMsg
# Module B reads from attGuidInMsg
moduleB.attGuidInMsg.subscribeTo(moduleA.attGuidOutMsg)
Messages are strongly typed. The C++ types for input and output messages are ReadFunctor<SomeMsgPayload> and Message<SomeMsgPayload> respectively. C-based modules use SomeMsg_C structs.You can also create standalone messages in Python to inject data directly:
from Basilisk.architecture import messaging

attRefMsg = messaging.AttRefMsgPayload()
attRefMsg.sigma_RN = [0.1, 0.2, 0.0]
attRefMsgContainer = messaging.AttRefMsg_C()
attRefMsgContainer.write(attRefMsg)
All message connections must be established before calling InitializeSimulation().
Starting in version 2.9.0, supportData files are no longer bundled in the pip package. Basilisk uses pooch to download and cache data files.Use the data path utility to get a portable, platform-independent path:
from Basilisk.utilities import dataFileToPath

spicePath = dataFileToPath("EphemerisData/de430.bsp")
This works for both pip-installed and source-built versions. On first use, pooch downloads the file to a system cache directory.
Do not hard-code paths like supportData/EphemerisData/de430.bsp in your scripts — these paths will fail on pip-installed versions.
For most cases, delete the dist3 folder and rebuild:
rm -rf dist3
python conanfile.py
If you still see stale dependency issues, also delete the .conan2 cache in your home directory:
rm -rf ~/.conan2
python conanfile.py
Note that deleting .conan2 forces all dependencies to be re-downloaded on the next build.
PyCharm can auto-complete Basilisk module variables and commands if you add the Basilisk package to the project structure.
  1. Open Settings → Project → Project Structure.
  2. Add the directory containing the Basilisk package as a source root.
  3. PyCharm will index the package and provide auto-complete for module attributes.
See the PyCharm Project Structure documentation for detailed steps.
Basilisk integrates with the Vizard visualization application. To enable it in a simulation script:
from Basilisk.utilities import vizSupport

# Enable visualization (set saveFile to record for offline playback)
viz = vizSupport.enableUnityVisualization(scSim, simTaskName, scObject)
# viz = vizSupport.enableUnityVisualization(scSim, simTaskName, scObject,
#                                           saveFile="mySimulation")
Check whether vizInterface was built before running Vizard-specific code:
if vizSupport.vizFound:
    viz = vizSupport.enableUnityVisualization(...)
Vizard 2.3.1 and newer is supported by the current release.
Basilisk supports MuJoCo as an alternate dynamics engine alongside the native spacecraft dynamics. To use it:
  1. Build Basilisk from source with MuJoCo support enabled.
  2. Create an MJScene object and add MJBody, MJJoint, and actuator objects to it.
  3. Add the MJScene to your simulation task.
Example scenarios demonstrating MuJoCo dynamics include scenarioAttitudeFeedbackRWMuJoCo and scenarioFormationFlyingWithDrag. Run bskExamples to download them.
MuJoCo integration is actively developed. Additional capabilities including landing dynamics and expanded actuator support are in progress.
Basilisk supports Python 3.9 through 3.13. Pre-compiled pip wheels are available for all supported versions on macOS, Linux, and Windows.Python 3.8 support was deprecated in version 2.8.0 and will be removed in a future release.The current release adds cp313 wheel builds for Python 3.13 with updated SWIG ABI support.
All new modules must:
  1. Include a unit test file (filename beginning with test_).
  2. Include a .rst documentation file (follow the template in src/moduleTemplates/).
  3. Have unit test methods with documentation strings.
  4. Include a copyright statement with the current year.
  5. Follow the Coding Guidelines.
  6. Include a release-note snippet in docs/source/Support/bskReleaseNotesSnippets/.
For example scenarios placed in the examples/ folder, add a unit test in src/tests/ that imports and runs the example file, and link the example in examples/_default.rst.See CONTRIBUTING.md for the full PR workflow.

Build docs developers (and LLMs) love

Get started for freeTalk to us