Installation

Installation#

Dependencies#

pykep has both C++ and Python dependencies.

On the C++ side, pykep depends on:

  • the heyoka C++ library (version ≥ 7, mandatory),

  • the Boost C++ libraries (version ≥ 1.73, mandatory),

  • the {fmt} library (version ≥ 10, mandatory),

  • the spdlog library (version ≥ 1.12, mandatory),

  • the xtensor and xtensor-blas libraries (version ≥ 0.26, mandatory),

  • the NLopt nonlinear optimization library (mandatory).

On the Python side, pykep requires Python ≥ 3.11 and depends on:

  • NumPy (mandatory),

  • pygmo (mandatory, for trajectory optimization problem interfaces),

  • heyoka.py (version ≥ 7, mandatory, for Taylor integration),

  • spiceypy (optional, for JPL SPICE ephemeris support),

  • sgp4 (optional, for SGP4 propagation of Earth-orbiting objects),

  • matplotlib (optional, for the built-in plotting utilities),

  • scipy (optional, for certain utility functions).

Packages#

conda#

conda is the recommended installation method, as it provides a fully managed scientific Python stack with all C++ dependencies resolved automatically.

Add conda-forge to your channels (if not already present) and install:

$ conda config --add channels conda-forge
$ conda config --set channel_priority strict
$ conda install pykep

The conda packages are maintained by the core development team and updated with each new release.

pip#

Binary wheels for pykep are also available on PyPI:

$ pip install pykep

Prebuilt wheels are currently provided for Linux (x86-64 and arm64).

Note

pykep bundles several C++ libraries inside its pip wheels. There is a non-negligible chance of conflicts with other packages that bundle the same C++ libraries. Installing via conda is strongly preferred whenever possible.

Installation from source#

Building from source is the recommended path when working on the development version of pykep or when you need a custom build configuration.

Warning

When building from source, make sure the compiler used is ABI-compatible with the compilers used to build pykep’s dependencies. Mixing incompatible compilers can cause hard-to-diagnose build or runtime errors.

pykep requires a compiler supporting C++23 and CMake ≥ 3.28.

Step 1 — Create and activate the development environment:

$ conda env create -f kep3_devel.yml
$ conda activate kep3_devel

This installs all mandatory C++ and Python dependencies into an isolated conda environment.

Step 2 — Configure and build:

$ cmake -S . -B build -G Ninja              \
    -DCMAKE_EXPORT_COMPILE_COMMANDS=1        \
    -DCMAKE_INSTALL_PREFIX="$CONDA_PREFIX"   \
    -DCMAKE_PREFIX_PATH="$CONDA_PREFIX"      \
    -Dkep3_BUILD_PYTHON_BINDINGS=ON
$ cmake --build build --target install --parallel

Step 3 — Verify the installation:

$ python -c "import pykep; print(pykep.__version__)"

CMake flags reference

Flag

Description

-DCMAKE_INSTALL_PREFIX="$CONDA_PREFIX"

Install into the active conda environment.

-DCMAKE_PREFIX_PATH="$CONDA_PREFIX"

Resolve dependencies from the active conda environment.

-Dkep3_BUILD_CPP_LIBRARY=ON

Build the kep3 C++ library from source (default). Set to OFF to use an already-installed kep3 located via find_package instead.

-Dkep3_BUILD_PYTHON_BINDINGS=ON

Build and install the pykep Python extension module.

-Dkep3_BUILD_TESTS=ON

Build the C++ unit-test suite.

-Dkep3_BUILD_BENCHMARKS=ON

Build the benchmark executables.

-DKEP3_VERBOSE_CONFIGURE=ON

Emit additional configure-time diagnostics.

-DCMAKE_BUILD_TYPE=Debug

Enable debug symbols (single-config generators only).

Verifying the installation#

After installation, confirm pykep is working correctly:

$ python -c "import pykep; print(pykep.__version__)"

To run the Python test suite:

$ python -m pytest /path/to/pykep/tests

Running the C++ test suite

To verify the C++ library itself, configure a build with kep3_BUILD_TESTS=ON and run the tests via CTest:

$ cmake -S . -B build -G Ninja              \
    -DCMAKE_PREFIX_PATH="$CONDA_PREFIX"      \
    -Dkep3_BUILD_TESTS=ON
$ cmake --build build --parallel
$ ctest --test-dir build --output-on-failure

Note

The -DCMAKE_INSTALL_PREFIX flag is not required when building tests only — nothing is installed. CTest discovers the test executables directly from the build tree.

Getting help#

If you encounter problems during installation, please open an issue on the GitHub issue tracker.