{"id":6014,"library":"numba-cuda","title":"Numba CUDA Target","description":"Numba-cuda provides a CUDA target for the Numba Python JIT compiler, enabling Python functions to be compiled and executed on NVIDIA GPUs. It allows users to write custom GPU kernels and device functions directly in a subset of Python. The library, currently at version 0.30.0, is actively developed by NVIDIA, with its release cycle now decoupled from the main Numba project to facilitate more frequent updates and new feature development.","status":"active","version":"0.30.0","language":"python","source_language":"en","source_url":"https://github.com/NVIDIA/numba-cuda","tags":["cuda","gpu","numba","jit","high-performance-computing","nvidia","parallel-computing","python"],"install":[{"cmd":"pip install numba-cuda","lang":"bash","label":"PyPI"},{"cmd":"conda install -c conda-forge numba-cuda","lang":"bash","label":"Conda (conda-forge)"}],"dependencies":[{"reason":"Core JIT compiler, numba-cuda is a target extension.","package":"numba"},{"reason":"Kernels often operate on NumPy arrays, which are automatically transferred to/from the device.","package":"numpy"},{"reason":"Used for NVVM bindings and interacting with the CUDA Driver API (since v0.29.0).","package":"cuda-python"},{"reason":"Runtime dependency for CUDA-enabled GPUs; required for compilation and execution. Install via `conda` or NVIDIA CUDA SDK.","package":"cudatoolkit","optional":true}],"imports":[{"note":"All CUDA-specific functionality is exposed through the `numba.cuda` module.","symbol":"cuda","correct":"from numba import cuda"}],"quickstart":{"code":"import numpy as np\nfrom numba import cuda\nimport os\n\n# Check for CUDA availability (runtime dependency)\nif not cuda.is_available():\n    print(\"CUDA is not available. Please ensure you have an NVIDIA GPU and CUDA drivers installed.\")\n    exit()\n\n# Define a CUDA kernel\n@cuda.jit\ndef add_vectors(x, y, out):\n    idx = cuda.grid(1)\n    if idx < len(out):\n        out[idx] = x[idx] + y[idx]\n\n# Host-side code\nN = 1000000\nx_host = np.arange(N, dtype=np.float32)\ny_host = np.arange(N, dtype=np.float32)\nout_host = np.empty_like(x_host)\n\n# Allocate memory on the device and copy data\nx_device = cuda.to_device(x_host)\ny_device = cuda.to_device(y_host)\nout_device = cuda.device_array_like(out_host)\n\n# Configure the kernel launch\nthreadsperblock = 256\nblockspergrid = (N + (threadsperblock - 1)) // threadsperblock\n\n# Launch the kernel\nadd_vectors[blockspergrid, threadsperblock](x_device, y_device, out_device)\n\n# Copy the result back to the host\nout_device.copy_to_host(out_host)\n\n# Verify the result\nexpected_out = x_host + y_host\nassert np.allclose(out_host, expected_out)\nprint(\"Vector addition on GPU successful!\")","lang":"python","description":"This quickstart demonstrates a basic vector addition using a Numba CUDA kernel. It covers defining a kernel with `@cuda.jit`, allocating and transferring data between host (CPU) and device (GPU) memory, configuring and launching the kernel, and copying results back to the host. Ensure you have a CUDA-enabled GPU and appropriate drivers installed."},"warnings":[{"fix":"Always include `pip install numba-cuda` (or `conda install numba-cuda`) in your environment setup alongside `numba`.","message":"The built-in CUDA target in the main `numba` package is deprecated. New features and most bug fixes are now exclusively implemented in `numba-cuda`. While the old target remains for compatibility, it's strongly recommended to install `numba-cuda` for active development and to ensure access to the latest capabilities.","severity":"deprecated","affected_versions":"Numba v0.61.0 and later when not explicitly installing numba-cuda."},{"fix":"Ensure your `try-except` blocks are robust to potential changes in error types. For maximum compatibility, catch broader exception types or consult release notes if you encounter unexpected `TypingError` propagation.","message":"In `numba-cuda` v0.28.0, there was an attempt to shift error classes from `numba.core.errors.TypingError` to `numba.cuda.errors` namespaces. This caused compatibility issues with existing code that relied on catching the old error types and was subsequently reverted. Users should be aware that such internal error type changes can be breaking.","severity":"breaking","affected_versions":"v0.28.0 (reverted in subsequent patches)"},{"fix":"Avoid relying on Numba's internal implementation details. Stick to the public API documented in `numba.cuda` for memory management (`cuda.to_device`, `cuda.device_array`), kernel launching, and device interactions.","message":"The internal `DeviceArray` implementation underwent refactoring, and certain internal `enums` and `ctypes` code were removed in `numba-cuda` v0.23.0 and v0.28.0 respectively. Code that directly interacted with these internal components or undocumented APIs may break.","severity":"breaking","affected_versions":"v0.23.0, v0.28.0"},{"fix":"Pass empty or pre-allocated device arrays as arguments to your kernel, and have the kernel write its output into these arrays. Copy the results back to the host after kernel execution if needed.","message":"Numba CUDA kernel functions cannot return values. Any results computed within a kernel must be written to arrays passed as arguments to the kernel. This is a common pattern in CUDA C/C++ and applies to Numba CUDA kernels as well.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Run your kernel once with dummy data to trigger compilation, then measure the execution time of subsequent calls. Use `cuda.synchronize()` to ensure all GPU operations have completed before measuring elapsed time.","message":"The first call to a Numba CUDA kernel includes the Just-In-Time (JIT) compilation overhead, which can be significant. For accurate performance benchmarking, always time subsequent calls to the kernel after the initial compilation has completed (e.g., by performing a 'warm-up' run).","severity":"gotcha","affected_versions":"All versions"},{"fix":"Ensure your target GPU has compute capability 5.0 or higher. Upgrade your NVIDIA drivers and CUDA Toolkit to version 11.2 or newer.","message":"Support for NVIDIA GPUs with compute capability less than 5.0 is deprecated and will be removed in future releases. Additionally, Numba-CUDA requires a minimum CUDA Toolkit version of 11.2.","severity":"breaking","affected_versions":"All versions (deprecation active)"}],"env_vars":null,"search_vec":"'0.30.0':50 'activ':52 'allow':29 'compil':16,22 'comput':83,87 'cuda':2,6,9,76 'current':47 'custom':33 'cycl':59 'decoupl':61 'develop':53,75 'devic':37 'direct':39 'enabl':17 'execut':24 'facilit':68 'featur':74 'frequent':70 'function':19,38 'gpu':34,77 'gpus':27 'high':81 'high-performance-comput':80 'jit':15,79 'kernel':35 'librari':46 'main':64 'new':73 'numba':1,5,13,65,78 'numba-cuda':4 'nvidia':26,55,84 'parallel':86 'parallel-comput':85 'perform':82 'project':66 'provid':7 'python':14,18,44,88 'releas':58 'subset':42 'target':3,10 'updat':71 'user':30 'version':49 'write':32","created_at":"2026-04-14T18:38:13.776301+00:00","updated_at":"2026-04-17T15:11:22.643139+00:00","problems":[{"fix":"Ensure `numba-cuda` is installed using `pip install numba-cuda` or, if using Anaconda, `conda install -c nvidia numba-cuda`. For older Numba installations where CUDA was part of the main package, use `conda install numba cudatoolkit`.","cause":"This error occurs when the `numba-cuda` package, or the `numba` package which includes CUDA support, is not installed or not correctly accessible in the Python environment being used.","error":"ModuleNotFoundError: No module named 'numba.cuda'"},{"fix":"Verify that NVIDIA GPU drivers are installed and up-to-date, that the CUDA Toolkit is installed and its paths (e.g., `CUDA_HOME`, `PATH`, `LD_LIBRARY_PATH`) are correctly configured, and that a CUDA-enabled GPU is present and functional. Restarting the system can sometimes resolve temporary driver issues. On Linux with `multiprocessing`, ensure CUDA is not initialized before forking processes.","cause":"Numba-CUDA cannot find or initialize a compatible CUDA-enabled GPU device, often due to missing or incorrectly installed NVIDIA GPU drivers, CUDA Toolkit, or issues with environment variables (e.g., `LD_LIBRARY_PATH`).","error":"numba.cuda.cudadrv.error.CudaSupportError: Error at driver init: Call to cuInit results in CUDA_ERROR_NO_DEVICE (100)"},{"fix":"Carefully review the `blockspergrid` and `threadsperblock` arguments passed to your CUDA kernel and ensure they are valid for your GPU and array sizes. Check any dynamic shared memory allocations and boundary conditions within your kernel logic.","cause":"This runtime error typically indicates an issue with the parameters passed to a CUDA kernel launch, such as invalid grid or block dimensions, an incorrect shared memory size, or attempting to access device memory out of bounds.","error":"numba.cuda.cudadrv.driver.CudaAPIError: [1] Call to cuLaunchKernel results in CUDA_ERROR_INVALID_VALUE"},{"fix":"Ensure that your CUDA Toolkit version is compatible with your NVIDIA GPU driver. If using `conda`, installing `cudatoolkit` via `conda install cudatoolkit` ensures a compatible version is used with Numba. You might need to update or downgrade your CUDA Toolkit/driver to match the supported PTX version. For Numba, you can specify the compute capability (sm_XX) for compilation if needed.","cause":"This error means there's a mismatch between the PTX (Parallel Thread Execution) version generated by Numba and the PTX version supported by your installed CUDA driver and toolkit. This often happens after a GPU driver update or when using different versions of CUDA Toolkit during compilation and runtime.","error":"numba.cuda.cudadrv.driver.CudaAPIError: [CUresult.CUDA_ERROR_UNSUPPORTED_PTX_VERSION]"},{"fix":"Ensure that data types used within your Numba CUDA kernel are explicitly defined and compatible with Numba's type system. Prefer `numba.types` (e.g., `numba.types.int64`) over `numpy` types (e.g., `np.int64`) for device functions and array allocation within CUDA kernels. Debugging with `@cuda.jit(debug=True)` can help identify the exact location of type inference failure.","cause":"This `TypingError` occurs when Numba's type inference fails, often because of incompatible data types used within a CUDA kernel, particularly when mixing standard NumPy types with Numba's internal types or when Numba cannot determine a unified type.","error":"numba.errors.TypingError: Failed in nopython mode pipeline (step: nopython frontend) type object 'numpy.int64' has no attribute 'is_precise'"}],"ecosystem":"pypi","meta_description":null,"install_score":null,"quickstart_score":null,"quickstart_tag":null,"pypi_latest":"0.30.2","cli_name":"","cli_version":null,"type":"library","homepage":"https://nvidia.github.io/numba-cuda/","github":"https://github.com/NVIDIA/numba-cuda","docs":"https://nvidia.github.io/numba-cuda/","changelog":null,"pypi":"https://pypi.org/project/numba-cuda/","npm":null,"openapi_spec":null,"status_page":null,"smithery":null,"categories":["ai-ml","data"],"base_url":null,"auth_type":null,"provenance":{"verified_status":"passing","verified_at":"2026-06-28","last_verified":"2026-06-28","next_check":"2026-07-28","install_tag":null}}