Install & Compatibility
Where this runs
tested against v1.14.1.1 · pip install
no network on importno background threads
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
muslpy 3.10–3.910 runs
build_error
glibcpy 3.10–3.910 runs
installs and imports cleanly · install 1.6s · import 0.000s · 22MB
19MB installed
● package 19MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
cufile
✓ from nvidia.cufile import cufile
✗ from nvidia.cufile import cufile
This conceptual quickstart demonstrates how to access the `cufile` module through `cuda.bindings` after installing `cuda-python` and `nvidia-cufile-cu12`. Direct, runnable examples of cuFile operations are highly dependent on specific hardware (NVIDIA GPU), a GPUDirect Storage enabled filesystem, and a properly configured NVIDIA driver, making a universally runnable snippet impractical without such a setup. It outlines the typical high-level steps for interacting with the cuFile API in Python.
# The 'nvidia-cufile-cu12' package provides the underlying C/C++ cuFile libraries.
# To interact with cuFile from Python, you typically use the 'cuda-python' package.
# Install cuda-python: pip install cuda-python numpy
import numpy as np
from cuda.bindings import cufile, driver
# NOTE: This quickstart is conceptual and requires a system with GPUDirect Storage
# enabled, a compatible filesystem, and appropriate NVIDIA hardware/driver setup.
# A simple 'hello world' is not feasible without such infrastructure.
def conceptual_cufile_usage():
print("Initializing CUDA driver and cuFile (conceptual)...")
try:
# Initialize CUDA driver (required for cuFile operations)
driver.cuInit(0)
# Open cuFile driver
cufile.driver_open()
# --- Example: Hypothetical buffered read/write setup ---
# In a real scenario, you'd perform operations like:
# 1. Allocate GPU memory (e.g., using CuPy or PyTorch on device)
# 2. Register the buffer with cuFile (cufile.buf_register)
# 3. Open a file for GPUDirect Storage (e.g., POSIX open on a supported filesystem)
# 4. Register the file handle with cuFile (cufile.handle_register)
# 5. Perform I/O operations (cufile.read, cufile.write)
# 6. Deregister handles and buffers (cufile.handle_deregister, cufile.buf_deregister)
print("cuFile driver opened successfully. Real I/O requires extensive setup.")
print("Please refer to NVIDIA GPUDirect Storage documentation for full usage.")
except Exception as e:
print(f"An error occurred during conceptual cuFile initialization: {e}")
finally:
try:
# Close cuFile driver
cufile.driver_close()
print("cuFile driver closed (conceptual).")
except Exception as e:
print(f"Error closing cuFile driver: {e}")
if __name__ == "__main__":
conceptual_cufile_usage()
Debug
Known issues
gotchaInstalling `nvidia-cufile-cu12` along with other `nvidia-*cu12` packages can sometimes lead to prolonged dependency resolution times with `pip`.fixEnsure `pip` and `setuptools` are up-to-date (`python -m pip install --upgrade pip setuptools`). If issues persist, consider providing stricter version constraints for dependencies or using `conda` for environment management.
affects: All versions
gotchaPython bindings for CUDA libraries, including `cuda.bindings.cufile`, require a CUDA driver on your system that is compatible with the installed CUDA Toolkit version. Mismatches can lead to import errors or runtime failures.fixEnsure your NVIDIA GPU driver is up-to-date and compatible with the CUDA Toolkit version corresponding to the `cu12` suffix (i.e., CUDA 12.x). You may need to explicitly install a specific version of `cuda-python` (e.g., `pip install cuda-python==12.x`) to match your driver if auto-resolution fails.
affects: All versions
breakingThe `cuda.bindings` module (which provides `cuda.bindings.cufile`) deprecated using `int(cuda_obj)` to retrieve the underlying address of a CUDA object in `cuda-bindings` version 13.0.0.fixSwitch to using `get_cuda_native_handle()` for retrieving the underlying address of CUDA objects.
affects: >=13.0.0 of cuda-python
gotchaThe cuFile APIs, and by extension `cuda.bindings.cufile`, are primarily supported on Linux for GPUDirect Storage functionality. Usage on Windows may be limited or require WSL2 with specific configurations.fixFor full GPUDirect Storage functionality, use a Linux environment with appropriate hardware and kernel modules (e.g., `nvidia-fs.ko`).
affects: All versions
breakingThe script failed due to `ModuleNotFoundError: No module named 'numpy'`, indicating that the `numpy` package is not installed in the environment.fixEnsure `numpy` is installed in your Python environment by running `pip install numpy` or including it in your project's `requirements.txt` file. If using a virtual environment, ensure it is activated before installation.
affects: All versions
breaking`nvidia-cufile-cu12` currently does not provide pre-built wheels for Python 3.13 or for musl libc-based distributions like Alpine Linux. This leads to `pip` being unable to find a compatible distribution.fixUse a glibc-based Linux distribution (e.g., Ubuntu, Debian, CentOS) and a Python version for which pre-built wheels are available (currently Python 3.8-3.12). Check the package's official PyPI page for the most up-to-date information on supported versions and platforms.
affects: All versions (when used with Python 3.13 or Alpine Linux)
Upgrade
Version history
1.14.1.1latest on PyPI · released Jun 5, 2025
Audit
Dependencies
cuda-pythonrequiredProvides the official Python bindings (cuda.bindings.cufile) that utilize these underlying libraries.
numpyrequiredRequired by cuda.bindings.cufile for memory operations.
torchrequiredOften used in environments leveraging GPUDirect Storage; implicitly depends on other nvidia-*cu12 packages.
cupyrequiredCommonly used for GPU-accelerated array computing in conjunction with CUDA libraries.