{"id":2907,"library":"cuda-core","title":"cuda-core (Pythonic CUDA Driver API)","description":"The `cuda-core` library provides low-level Pythonic bindings to the NVIDIA CUDA Driver API. It enables direct interaction with NVIDIA GPUs for tasks like device querying, memory management, context creation, and kernel launches. As part of the broader `cuda-python` project, it is currently at version 0.7.0 and often sees updates aligned with new CUDA Toolkit releases.","status":"active","version":"0.7.0","language":"en","source_language":"en","source_url":"https://github.com/cuda-python/cuda-python","tags":["GPU","CUDA","deep-learning","performance","nvidia","driver-api"],"install":[{"cmd":"pip install cuda-core","lang":"bash","label":"Install cuda-core"}],"dependencies":[{"reason":"Required for the quickstart code example (data generation for device memory transfer).","package":"numpy","optional":true}],"imports":[{"note":"The primary way to import the core CUDA Driver API bindings.","symbol":"cuda.core","correct":"import cuda.core as drv"},{"note":"Import specific exception class for error handling.","symbol":"CUException","correct":"from cuda.core import CUException"}],"quickstart":{"code":"import cuda.core as drv\nimport numpy as np\n\ntry:\n    # Initialize the CUDA driver API\n    drv.init()\n\n    # Get device count\n    device_count = drv.cuDeviceGetCount()\n    if device_count == 0:\n        print(\"No CUDA devices found. Ensure GPU drivers and CUDA Toolkit are installed.\")\n    else:\n        print(f\"Found {device_count} CUDA device(s).\")\n        \n        # Get the first device and create a context\n        device = drv.cuDeviceGet(0)\n        # Flags: 0 for default context creation\n        context = drv.cuCtxCreate(0, device)\n        print(f\"Created CUDA context on device 0: {device}\")\n\n        # Prepare host data\n        host_data = np.arange(10, dtype=np.int32)\n        print(f\"Host data: {host_data}\")\n\n        # Allocate memory on the device\n        device_ptr = drv.cuMemAlloc(host_data.nbytes)\n        print(f\"Allocated {host_data.nbytes} bytes on device at address: {device_ptr}\")\n\n        # Copy host data to device\n        drv.cuMemcpyHtoD(device_ptr, host_data.ctypes.data, host_data.nbytes)\n        print(\"Copied host data to device.\")\n\n        # Example: Copy device data back to host (optional, for verification)\n        retrieved_data = np.empty_like(host_data)\n        drv.cuMemcpyDtoH(retrieved_data.ctypes.data, device_ptr, retrieved_data.nbytes)\n        print(f\"Retrieved data from device: {retrieved_data}\")\n\n        # Clean up: Free device memory and destroy context\n        drv.cuMemFree(device_ptr)\n        drv.cuCtxDestroy(context)\n        print(\"Successfully freed device memory and destroyed context.\")\n\nexcept drv.CUException as e:\n    print(f\"CUDA Error: {e}. This often indicates issues with CUDA Toolkit installation, drivers, or device availability.\")\n    print(\"Please ensure you have a compatible NVIDIA GPU, up-to-date drivers, and a correctly installed CUDA Toolkit.\")\nexcept Exception as e:\n    print(f\"An unexpected Python error occurred: {e}\")","lang":"python","description":"This quickstart initializes the CUDA driver, queries available devices, creates a CUDA context, allocates memory on the GPU, copies data from host to device, and then cleans up resources. It also includes basic error handling for common CUDA issues."},"warnings":[{"fix":"Before installing `cuda-core`, ensure you have a compatible NVIDIA GPU and have installed the appropriate NVIDIA GPU drivers and CUDA Toolkit from NVIDIA's developer website. The `cuda-python` project's documentation often provides compatibility matrices.","message":"The `cuda-core` library provides bindings to the CUDA Driver API and *requires a compatible NVIDIA CUDA Toolkit to be installed on the system* (including drivers, runtime, and developer headers). It is not a standalone Python package that ships with CUDA itself.","severity":"breaking","affected_versions":"All"},{"fix":"Always pair `drv.cuMemAlloc` (or `cuMemAllocManaged`) with a corresponding `drv.cuMemFree`. Utilize `try...finally` blocks for robust resource cleanup, especially when handling contexts and memory pointers.","message":"As a low-level Driver API, `cuda-core` necessitates explicit memory management. Users must manually allocate and deallocate GPU memory using functions like `drv.cuMemAlloc` and `drv.cuMemFree`. Failing to free allocated memory can lead to GPU memory leaks and resource exhaustion.","severity":"gotcha","affected_versions":"All"},{"fix":"Understand the distinction between the Driver API (`cuda.core`) and the Runtime API (`cuda.cudart`). For higher-level abstractions, consider using `cuda.cudart` or other libraries built on CUDA, such as CuPy, PyTorch, or TensorFlow, which handle much of the low-level complexity for you.","message":"`cuda.core` binds directly to the CUDA Driver API, which is lower-level than the CUDA Runtime API (often used implicitly by `nvcc` and libraries like `cuda.cudart`). It doesn't provide high-level abstractions like automatic memory management, unified memory, or stream synchronization helpers out-of-the-box.","severity":"gotcha","affected_versions":"All"},{"fix":"Consult the `cuda-python` project documentation and NVIDIA's compatibility tables to ensure all components (GPU driver, CUDA Toolkit, and `cuda-core` package) are compatible with each other and your hardware. Often, updating drivers or using a specific CUDA Toolkit version can resolve these issues.","message":"Mismatches between the `cuda-core` Python package version, the system's installed CUDA Toolkit version, and the NVIDIA GPU driver version can lead to `drv.CUException` errors (e.g., `CUDA_ERROR_NOT_INITIALIZED`, `CUDA_ERROR_NO_DEVICE`, `CUDA_ERROR_INVALID_DEVICE`).","severity":"gotcha","affected_versions":"All"}],"env_vars":null,"last_verified":"2026-04-11T00:00:00.000Z","next_check":"2026-07-10T00:00:00.000Z"}