Skip to content

Update install instructions #317

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
IvanGrigorik merged 3 commits into from
Dec 19, 2025
Merged

Update install instructions #317

Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
516da8b
Update install instructions
Nov 25, 2025
cbf2b36
Apply suggestion from @kennykos
kennykos Nov 26, 2025
eaa92d8
update install instructions
IvanGrigorik Dec 18, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
99 changes: 57 additions & 42 deletions docs/installation.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -2,38 +2,41 @@
Installation
============

We recommend using Docker for running applications and developing (see
:ref:`Using Docker<using_docker>`, but detailed installation
instructions are available (see :ref:`Native
Installation<native_installation>`).
We provide a Docker container for running applications and developing
on Linux x86 systems with the Serial and OpenMP host execution space
(see :ref:`Using Docker<using_docker>`).
We provide detailed install instructions for all other
operating systems and executions spaces
(see :ref:`Native Installation<native_installation>`).

.. _using_docker:

Using Docker
------------

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

To run an application in a container, you can execute the following
command:
.. To run an application in a container, you can execute the following
.. command:

.. code-block:: bash
.. .. code-block:: bash

./pk pk_example examples/kokkos-tutorials/workload/01.py
.. ./pk pk_example examples/kokkos-tutorials/workload/01.py

The command above will pull the image from the Docker Hub, run a
container, include this repository as a volume, and run the example
application from the given path.
.. The command above will pull the image from the Docker Hub, run a
.. container, include this repository as a volume, and run the example
.. application from the given path.

If you would like to run another example application, you can simply
change the path (the last argument in the command above).
.. If you would like to run another example application, you can simply
.. change the path (the last argument in the command above).

Note that code you are running should be in the PyKokkos repository.
If you would like to run from another directory you will need to
include the directory as a volume; take a look at the ``pk`` script in
that case.
.. Note that code you are running should be in the PyKokkos repository.
.. If you would like to run from another directory you will need to
.. include the directory as a volume; take a look at the ``pk`` script in
.. that case.

Design Decision
^^^^^^^^^^^^^^^
Expand Down Expand Up @@ -61,43 +64,52 @@ already included in the image), you would need to install it
Native Installation
-------------------

Clone `pykokkos-base <https://github.com/kokkos/pykokkos-base>`_ and
Clone `pykokkos <https://github.com/kokkos/pykokkos>`_ and
create a conda environment:

.. code-block:: bash

git clone https://github.com/kokkos/pykokkos-base.git
cd pykokkos-base/
conda create --name pyk --file requirements.txt python=3.11
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 ``pykokkos-base`` with CUDA and OpenMP enabled:
install ``base`` with required CMake flags (example performs an install with OpenMP and CUDA enabled):

.. code-block:: bash

python setup.py install -- -DENABLE_LAYOUTS=ON -DENABLE_MEMORY_TRAITS=OFF -DENABLE_VIEW_RANKS=3 -DENABLE_CUDA=ON -DENABLE_THREADS=OFF -DENABLE_OPENMP=ON

Other ``pykokkos-base`` configuration and installation options can be
PYKOKKOS_BASE_SETUP_ARGS="\
-DKokkos_ENABLE_THREADS=OFF \ # trigger pthreads execution space
-DKokkos_ENABLE_OPENMP=ON \ # trigger openmp execution space
-DENABLE_CUDA=ON \ # trigger cuda execution space
-DENABLE_HIP=OFF \ # trigger hip execution space
-DENABLE_LAYOUTS=ON \ # trigger layout left/right ordering
-DENABLE_MEMORY_TRAITS=OFF \ # trigger memory space concept
-DENABLE_VIEW_RANKS=3 \ # maximum number of view ranks enabled
" \
python install_base.py install
See `Kokkos CMake Options <https://kokkos.org/kokkos-kernels/docs/cmake-keywords.html>`_ for a complete list of CMake flags.
Other ``pykokkos`` configuration and installation options can be
found in that project's `README
<https://github.com/kokkos/pykokkos-base/blob/main/README.md>`_. Note
<https://github.com/kokkos/pykokkos/blob/main/base/README.md>`_. Note
that this step will compile a large number of bindings which can take
a while to complete. Please open an issue if you run into any problems
with ``pykokkos-base``.
a while to complete.

Once ``pykokkos-base`` has been installed, clone ``pykokkos`` and
install its requirements:
.. note::
Please open an issue
or reach out in the `Kokkos slack <https://kokkos.org/community/chat/>`_
**#pykokkos** channel
if you run into any problems
with ``base``.

.. code-block:: bash
Once ``base`` has been installed, you can install ``pykokkos`` itself:

cd ..
git clone https://github.com/kokkos/pykokkos.git
cd pykokkos/
.. code-block:: bash
conda install -c conda-forge pybind11 cupy patchelf
pip install --user -e .

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

.. code-block::
Expand All @@ -110,7 +122,7 @@ error inside ``pykokkos`` similar to the following:
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 ``pykokkos-base`` depends on and the library in
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:
Expand All @@ -128,8 +140,11 @@ To verify that ``pykokkos`` has been installed correctly, install
python runtests.py

.. note::

Please open an issue for help with installation.
Please open an issue
or reach out in the `Kokkos slack <https://kokkos.org/community/chat/>`_
**#pykokkos** channel
if you run into any problems
with ``pykokkos``.

.. toctree::
:maxdepth: 2
Expand Down