Install & Usage of Cytnx¶

Cytnx publishes prebuilt Python wheels, so installing the Python API does not require a compiler or a CUDA toolkit. The recommended way to get one is Pixi, which creates a project-local environment from a lock file so everyone working from the same project gets the same versions.

If you want to call Cytnx from C++, or you need a build option the wheels are not compiled with, see Using the C++ API below.

Install with Pixi¶

Install Pixi by following the Pixi installation guide.
Create a project, pin a Python version Cytnx has wheels for, and add Cytnx:

pixi init my-project
cd my-project
pixi add "python=3.12"
pixi add --pypi cytnx

Run Python inside that environment:

pixi run python

Important

Pin the Python version. A bare pixi add python takes the newest CPython conda-forge offers, which is already past the newest Python Cytnx builds wheels for; the resolve then fails, reporting that it needs cp315 while Cytnx publishes only cp39 through cp314. Any version in Supported platforms works, and 3.12 is a safe default.

Adding Cytnx before any Python at all fails differently, with No Python interpreter found in the dependencies.

Warning

The current release on PyPI, cytnx 1.1.1, installs but then fails on import cytnx with AttributeError: module 'importlib' has no attribute 'util'. The bug is fixed in the development branch but is not in a release yet.

Until the next patch release, take Cytnx from the nightly wheel index, which is built from the development branch:

pixi add --pypi cytnx --index https://pypi.anaconda.org/cytnx-nightly-wheels/simple

The nightly index carries every build, so this first resolve can take a few minutes. It is not stuck.

Note

We do not publish a native Windows wheel at this stage. On Windows, please use WSL.

GPU (CUDA) support¶

The CUDA build is a separate package, cytnx-cuda. It is currently published only on the nightly index, and only for Linux on x86_64:

pixi add --pypi cytnx-cuda --index https://pypi.anaconda.org/cytnx-nightly-wheels/simple

The wheel bundles the CUDA runtime libraries it needs, so no system CUDA toolkit is required. An NVIDIA GPU and a sufficiently recent driver are, of course, needed to run on the GPU.

Install with pip¶

If you are not using Pixi, the wheels install with pip like any other package. Use a virtual environment so the install does not touch your system Python, and create it with a Python version from Supported platforms:

python3.12 -m venv cytnx-env
source cytnx-env/bin/activate
pip install cytnx

Note

pip cannot be told to prefer one index over another: with --extra-index-url it considers every index together and picks the highest version, and a nightly such as 1.1.1.dev202610071206 sorts below the 1.1.1 release. So pip install --pre --extra-index-url ... quietly installs the release, not the nightly. To get a nightly with pip, pin one exactly:

pip install --extra-index-url https://pypi.anaconda.org/cytnx-nightly-wheels/simple \
    cytnx==1.1.1.devYYYYMMDDHHMM

picking a version from the nightly index. Pixi and uv both resolve a named index directly and need no such pin.

Supported platforms¶

The released wheels cover CPython 3.9 through 3.14 on:

Platform	CPU (`cytnx`)	CUDA (`cytnx-cuda`)
Linux x86_64	yes	yes (nightly only)
Linux aarch64	yes	no
macOS, Apple silicon	yes (macOS 14+)	no
macOS, Intel	yes (macOS 15+)	no
Windows	no, use WSL	no, use WSL

The Linux wheels require glibc 2.27 or newer; musl-based distributions such as Alpine are covered by separate musllinux wheels. There is no source distribution on PyPI, so a platform without a wheel has to build from source as described in Advanced Install of Cytnx.

Checking the installation¶

Importing cytnx and creating a tensor is enough to confirm the install works:

In Python:

import cytnx

print(cytnx.__version__)
A = cytnx.ones(4)
print(A)

Output>>

Total elem: 4
type  : Double (Float64)
cytnx device: CPU
Shape : (4)
[1.00000e+00 1.00000e+00 1.00000e+00 1.00000e+00 ]

Note

Run this from any directory other than a clone of the Cytnx source tree. Inside the source tree the local cytnx/ directory shadows the installed package and the import fails.

Using the C++ API¶

The wheels install only the compiled Python extension; they do not carry the C++ headers or a linkable libcytnx. To build your own C++ code against Cytnx, build and install the C++ library directly with CMake and consume it via find_package(Cytnx), as described in Advanced Install of Cytnx.