{"id":7362,"library":"libkvikio-cu12","title":"KvikIO (CUDA 12)","description":"KvikIO is a Python and C++ library designed for high-performance file I/O, providing Python and C++ bindings to cuFile, which enables GPUDirect Storage (GDS). As part of the RAPIDS suite, it efficiently handles both host and device (GPU) memory I/O. The library is actively maintained with frequent, typically monthly or bi-monthly, releases aligned with the broader RAPIDS ecosystem. The current version is 26.4.0.","status":"active","version":"26.4.0","language":"en","source_language":"en","source_url":"https://github.com/rapidsai/kvikio","tags":["gpu","io","storage","rapids","cuda","gpudirect-storage","cufile"],"install":[{"cmd":"pip install libkvikio-cu12","lang":"bash","label":"PyPI"}],"dependencies":[{"reason":"Required for GPU array operations and integration with KvikIO's device memory handling.","package":"cupy-cuda12x","optional":false},{"reason":"Standard array library, often used in conjunction with CuPy.","package":"numpy","optional":false},{"reason":"Optional backend for reading and writing Zarr arrays directly to GPU memory.","package":"zarr","optional":true},{"reason":"Underlying NVIDIA CUDA libraries are essential for GPU acceleration and GPUDirect Storage functionality. Not a Python package, but a system dependency.","package":"CUDA Toolkit (12.x)","optional":false}],"imports":[{"symbol":"kvikio","correct":"import kvikio"},{"note":"CuFile is typically accessed via `kvikio.cufile.CuFile` or directly imported.","wrong":"import kvikio.CuFile","symbol":"CuFile","correct":"from kvikio.cufile import CuFile"}],"quickstart":{"code":"import os\nimport cupy\nfrom kvikio.cufile import CuFile\n\n# Ensure a temporary file path is available\nfile_path = os.environ.get('KVIKIO_TEST_FILE_PATH', '/tmp/kvikio-example-data.bin')\n\n# Create a CuPy array on the GPU\na = cupy.arange(100, dtype=cupy.int64)\n\nprint(f\"Writing CuPy array to {file_path} using KvikIO...\")\n# Write the array to a file using KvikIO\nwith CuFile(file_path, 'w') as f:\n    f.write(a)\n\nprint(f\"Reading data from {file_path} back into a CuPy array...\")\n# Read data back into a new CuPy array\nb = cupy.empty_like(a)\nwith CuFile(file_path, 'r') as f:\n    f.read(b)\n\n# Verify the data\nassert cupy.array_equal(a, b)\nprint(\"Data written and read successfully, and arrays match!\")\n\n# Clean up the test file\nif os.path.exists(file_path):\n    os.remove(file_path)\n    print(f\"Cleaned up {file_path}\")","lang":"python","description":"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."},"warnings":[{"fix":"Ensure a compatible NVIDIA GPU and CUDA Toolkit (12.x) are installed and properly configured in your environment.","message":"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`.","severity":"breaking","affected_versions":">=25.12.00"},{"fix":"Migrate to Zarr 3 where possible or implement compression/decompression outside of KvikIO. Check the KvikIO documentation for updated Zarr integration patterns.","message":"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.","severity":"breaking","affected_versions":">=25.10.00"},{"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).","message":"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.","severity":"breaking","affected_versions":">=25.08.00"},{"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.","message":"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.","severity":"gotcha","affected_versions":"All versions"},{"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.","message":"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.","severity":"breaking","affected_versions":">=24.12.00"}],"env_vars":null,"last_verified":"2026-04-16T00:00:00.000Z","next_check":"2026-07-15T00:00:00.000Z","problems":[{"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`.","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.","error":"ERROR: Could not build wheels for kvikio which use PEP 517 and cannot be installed directly"},{"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.","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.","error":"RuntimeError: cuFile API error or GPUDirect Storage (GDS) not available."},{"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.","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.","error":"AssertionError: Not all elements are equal (when comparing CuPy arrays after read/write)"}]}