Installation

We provide a Docker container for running applications and developing on Linux x86 systems with the Serial and OpenMP host execution space (see Using Docker). We provide detailed install instructions for all other operating systems and executions spaces (see Native Installation).

Using Docker

Currently deprecated. Work in progress. .. You can use the PyKokkos Docker image to develop PyKokkos itself, as .. well as develop and run applications. We recommend using the pk .. script for interacting with the image and containers.

Design Decision

At the moment, we decided to include the PyKokkos repository as a volume when starting a container, which enables the development workflow. Namely, the pk script will include the current local version of this repository, which means that any local modifications (e.g., a change in parallel_dispatch.py) will be used in the subsequent runs of the pk script. In the future, we might separate user and development workflows.

Limitations

One, as described above, you would need to modify the pk script if you are running code that is not part of this repository.

Two, if your code requires dependencies (e.g., python libraries not already included in the image), you would need to install it (temporarily) in the container or build your own image.

Native Installation

Clone pykokkos and create a conda environment:

git clone https://github.com/kokkos/pykokkos.git
cd pykokkos/
conda create --name pyk --file base/requirements.txt python=3.13
conda activate pyk

Once the necessary packages have been downloaded and installed, install base with required CMake flags (example performs an install with OpenMP and CUDA enabled):

See Kokkos CMake Options for a complete list of CMake flags. Other pykokkos configuration and installation options can be found in that project’s README. Note that this step will compile a large number of bindings which can take a while to complete.

Note

Please open an issue or reach out in the Kokkos slack #pykokkos channel if you run into any problems with base.

Once base has been installed, you can install pykokkos itself:

Note that cupy is only required if CUDA is enabled in base. In some cases, this might result in a cupy import error inside pykokkos similar to the following:

ImportError:
================================================================
Failed to import CuPy.

Original error:
ImportError: /lib/x86_64-linux-gnu/libstdc++.so.6: version `GLIBCXX_3.4.29' not found (required by /PATH/TO/ENV/lib/python3.11/site-packages/cupy/_core/core.cpython-311-x86_64-linux-gnu.so)

This is due to a mismatch in libstdc++.so versions between the system library which base depends on and the library in the conda environment which cupy depends on. This can be solved by setting the LD_PRELOAD environment variable to force loading of the correct library like so:

export LD_PRELOAD=/PATH/TO/ENV/lib/libstdc++.so.6

To verify that pykokkos has been installed correctly, install pytest and run the tests:

conda install pytest
python runtests.py

Note

Please open an issue or reach out in the Kokkos slack #pykokkos channel if you run into any problems with pykokkos.