Installation¶

KCoral can be installed from a prebuilt package or built from source. Install the client on the machine that submits programs. If you also host a KCoral server, install the server dependencies on each machine that runs it.

Python 3.10 or newer is required. Use a virtual environment so the installation does not modify your system Python:

python3 -m venv .venv
source .venv/bin/activate
python -m pip install --upgrade pip

Run the installation commands below with this environment active.

Method 1: Install a prebuilt package¶

Prebuilt wheels are available on PyPI.

Install the client¶

python -m pip install kcoral

This installs the package with client dependencies. Running the client needs no GPU.

Verify that the client imports successfully:

python -c "from kcoral import Client, Program; print('KCoral client is ready')"

Install the server¶

The server requires Linux on x86-64 or AArch64 with glibc 2.28 or newer. Install the server extra:

python -m pip install 'kcoral[server]'

The server extra supports both GPU execution and CPU compilation. See system requirements.

Method 2: Build from source¶

Use a source installation to modify KCoral or install a specific revision.

Get the source¶

git clone https://github.com/mlc-ai/kcoral.git
cd kcoral

Run the remaining source installation commands from this repository directory.

Install in editable mode¶

Install the client:

python -m pip install -e .

To include the server dependencies, use:

python -m pip install -e '.[server]'

These builds are pure Python. A Router deployment also needs the Rust router and node supervisor, which run on Linux. Install Rust 1.87 or newer with Cargo and a C/C++ build toolchain, then build them into the package:

KCORAL_BUILD_RUST=1 python -m pip install -e '.[server]'

Server system requirements¶

The server runs on Linux. Its Python dependencies are installed by the server extra; the GPU driver and system tools below must be installed separately.

Server mode	Purpose	Hardware
GPU (`--device gpu`)	Compile, execute, and benchmark kernels	NVIDIA GPU and driver
CPU (`--device cpu`)	Compile CUDA C for execution on a GPU server	No GPU or GPU driver required

Compiling CUDA C in either mode requires the CUDA toolkit and a compatible C++ compiler.

Install bubblewrap 0.8.0 or newer for filesystem isolation. On Debian/Ubuntu:

sudo apt install bubblewrap

The host or container must also permit unprivileged user namespaces. If the server’s startup check cannot launch bubblewrap, it warns and runs without filesystem isolation; see the isolation guide above for configuration.

For deployment, see Launch the server and Remote Compilation.

Prepare for local compilation (optional)¶

If you want to compile CUDA C libraries on the client, as in the benchmark tutorial, install the CUDA toolkit and a compatible C++ compiler on that machine. Add TVM FFI and its C++ build dependencies to the active client environment:

python -m pip install 'apache-tvm-ffi[cpp]>=0.1.14.post0'

These additional dependencies are needed only when compiling locally. The KCoral server extra already includes the TVM FFI build dependencies for server-side compilation.