KvikIO (CUDA 12)

Common errors

• ERROR: Could not build wheels for kvikio which use PEP 517 and cannot be installed directly

  cause This error typically occurs when `pip` attempts to build KvikIO from source, but required build dependencies (like a C++ compiler, CUDA Toolkit headers, or Cython) are missing or misconfigured in the environment.
  fix Ensure you have a C++ compiler (e.g., `gcc`), the CUDA Toolkit (12.x) installed and accessible, and potentially `cython`. For most users, installing via `conda` or `mamba` from the `rapidsai` channel is recommended to handle complex dependencies automatically: `mamba install -c rapidsai -c conda-forge kvikio`.

• RuntimeError: cuFile API error or GPUDirect Storage (GDS) not available.

  cause KvikIO attempted to use cuFile/GDS but failed. This could be due to missing NVIDIA drivers, an incorrectly configured cuFile system, an unsupported file system, or GDS not being enabled/compatible with your hardware/software stack.
  fix Verify NVIDIA drivers are up to date, cuFile is installed and configured (refer to NVIDIA documentation), and that your storage system (NVMe, NVMe-oF) and kernel modules support GDS. You can try setting the environment variable `KVIKIO_COMPAT_MODE=ON` to force KvikIO to fall back to POSIX I/O if GDS is not critical for your use case.

• AssertionError: Not all elements are equal (when comparing CuPy arrays after read/write)

  cause Data corruption or incomplete I/O. This can happen if buffers are not correctly sized, file operations are interrupted, or if there are issues with unaligned reads/writes when GDS is active but not properly handled.
  fix Double-check buffer sizes, file offsets, and ensure I/O operations complete fully. For GDS performance-critical paths, confirm byte ranges are 4KB-aligned. Also, check for file system integrity and sufficient disk space.

Warnings

• breaking KvikIO versions 25.12.00 and newer (including 26.x.x) no longer support building or running without a CUDA installation. A working CUDA 12 Toolkit is a hard requirement for `libkvikio-cu12`.
  Fix: Ensure a compatible NVIDIA GPU and CUDA Toolkit (12.x) are installed and properly configured in your environment.
• breaking Starting with version 25.10.00, Python nvCOMP bindings and direct Zarr 2 support have been removed. Users relying on these specific features for compression or Zarr 2 may need to adjust their workflows or use older KvikIO versions.
  Fix: Migrate to Zarr 3 where possible or implement compression/decompression outside of KvikIO. Check the KvikIO documentation for updated Zarr integration patterns.
• breaking Version 25.08.00 removed CUDA 11 from its supported dependencies. Users on older CUDA environments (e.g., CUDA 11) must use KvikIO versions prior to 25.08.00 or upgrade their CUDA environment to 12.x.
  Fix: Upgrade your CUDA installation to version 12.x or downgrade `libkvikio-cu12` to a version compatible with your CUDA environment (e.g., <25.08.00).
• gotcha For optimal performance with GPUDirect Storage, I/O operations (reads/writes) should be aligned to a GPU page boundary (typically 4KB). Unaligned operations may still work but KvikIO has to split them, which can reduce performance.
  Fix: Ensure file offsets and buffer offsets are multiples of 4096 bytes when performing I/O for maximum efficiency. Use `file.align_offset(offset)` if available or manage offsets manually.
• breaking In version 24.12.00, KvikIO shifted to being built as a shared library and introduced a new 'AUTO' compatibility mode. This may affect linking for C++ users and change default fallback behavior for Python users when GDS is unavailable.
  Fix: C++ users should adjust their build systems to link against the shared library. Python users experiencing unexpected I/O behavior can explicitly set the `KVIKIO_COMPAT_MODE` environment variable (e.g., `OFF` for enforced cuFile, `ON` for POSIX fallback) to manage compatibility mode.

Install

• pip install libkvikio-cu12 PyPI

Imports

• kvikio

  import kvikio

• CuFile
  wrong:

  import kvikio.CuFile

  correct:

  from kvikio.cufile import CuFile

  CuFile is typically accessed via `kvikio.cufile.CuFile` or directly imported.

Quickstart

This quickstart demonstrates how to write a CuPy array (GPU memory) to a file and read it back using KvikIO's CuFile API. It mimics Python's built-in `open()` and file operations, but operates on GPU device memory directly, leveraging GPUDirect Storage if available.

import os
import cupy
from kvikio.cufile import CuFile

# Ensure a temporary file path is available
file_path = os.environ.get('KVIKIO_TEST_FILE_PATH', '/tmp/kvikio-example-data.bin')

# Create a CuPy array on the GPU
a = cupy.arange(100, dtype=cupy.int64)

print(f"Writing CuPy array to {file_path} using KvikIO...")
# Write the array to a file using KvikIO
with CuFile(file_path, 'w') as f:
    f.write(a)

print(f"Reading data from {file_path} back into a CuPy array...")
# Read data back into a new CuPy array
b = cupy.empty_like(a)
with CuFile(file_path, 'r') as f:
    f.read(b)

# Verify the data
assert cupy.array_equal(a, b)
print("Data written and read successfully, and arrays match!")

# Clean up the test file
if os.path.exists(file_path):
    os.remove(file_path)
    print(f"Cleaned up {file_path}")