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

You can use the PyKokkos Docker image to develop PyKokkos itself, as well as develop and run applications. We recommend to use dev-container/build-container.sh script in order to build and use Docker container only for personal usage on Nvidia GPUs.

The command will build developer container in wizard format, which means you need to answer or skip some question regarding container name, opened ports, ssh keys and so on. You can skip all of the questions with Enter and script will use default values. After container is build, you can enter container, using entered/default values.

In container, enter pykokkos directory and build pykokkos as it described in Native Installation.

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 -n pyk python=3.13 -y
conda env update -n pyk -f base/environment.yml
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):

python install_base.py install --verbose -- \
   -DENABLE_VIEW_RANKS=3 \             # maximum number of view ranks enabled
   -DENABLE_MEMORY_TRAITS=OFF \        # disable memory space concept
   -DENABLE_THREADS=OFF \              # disable pthreads execution space
   -DENABLE_LAYOUTS=ON \               # enable layout left/right ordering
   -DENABLE_CUDA=ON \                  # enable cuda execution space
   -DENABLE_OPENMP=ON \                # enable openmp execution space

CMake Flags ===================== ================== PyKokkos Flags Description ===================== ================= ENABLE_VIEW_RANKS Set this value to the max number of ranks needed for Kokkos::View<…>. E.g. value of 4 means Kokkos::View<int*****, Kokkos::HostSpace> cannot be returned to python ENABLE_LAYOUTS Build support for layouts (long NVCC compile times) ENABLE_MEMORY_TRAITS Build support for memory traits (long NVCC compile times) ENABLE_THREADS Build Kokkos submodule with Pthread support ENABLE_OPENMP Build Kokkos submodule with OpenMP support ENABLE_CUDA Build Kokkos submodule with CUDA support ENABLE_HIP Build Kokkos submodule with HIP support ARCH Kokkos GPU architecture, required for HIP builds

Note

Ensure that amdclang++ is used for building HIP device code by passing -DCMAKE_CXX_COMPILER=amdclang++ as a CMake flag.

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.

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

conda install -c conda-forge pybind11 cupy patchelf
pip install --user -e .

Note

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

---

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.13/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.