NVIDIA cuFile (CUDA 12)

1.14.1.1 · active · verified Sun Mar 29

nvidia-cufile-cu12 is a Python distribution package that provides the underlying NVIDIA cuFile GPUDirect Storage (GDS) libraries specifically compiled for CUDA 12. These libraries enable a direct data path for Direct Memory Access (DMA) transfers between GPU memory and storage, bypassing the CPU to increase bandwidth and decrease latency. It is generally consumed as a dependency by higher-level Python libraries like `cuda-python` (which exposes `cuda.bindings.cufile`) or other GPU-accelerated data science tools. The current version is 1.14.1.1, with a release cadence tied to CUDA Toolkit updates.

Warnings

gotcha Installing `nvidia-cufile-cu12` along with other `nvidia-*cu12` packages can sometimes lead to prolonged dependency resolution times with `pip`.
Fix: Ensure `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.
gotcha Python 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.
Fix: Ensure 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.
breaking The `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.
Fix: Switch to using `get_cuda_native_handle()` for retrieving the underlying address of CUDA objects.
gotcha The 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.
Fix: For full GPUDirect Storage functionality, use a Linux environment with appropriate hardware and kernel modules (e.g., `nvidia-fs.ko`).

Install

pip install nvidia-cufile-cu12 Recommended installation
pip install --extra-index-url https://pypi.nvidia.com nvidia-cufile-cu12 If experiencing download issues

Imports

cufile
```
from cuda.bindings import cufile
```
The 'nvidia-cufile-cu12' package itself does not expose a direct 'cufile' top-level module. Functionality is provided via the `cuda-python` package's `cuda.bindings.cufile` module, which links against the libraries installed by `nvidia-cufile-cu12`.

Quickstart

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()

view raw JSON →