{"id":546,"library":"nvidia-cublas-cu12","title":"NVIDIA cuBLAS Runtime Library (CUDA 12.x)","description":"nvidia-cublas-cu12 provides the native runtime libraries for NVIDIA's CUBLAS (CUDA Basic Linear Algebra Subprograms) on CUDA 12.x enabled systems. It's a GPU-accelerated library designed for high-performance linear algebra operations crucial for AI, machine learning, and high-performance computing (HPC) applications. This Python package acts as a runtime dependency for other Python libraries that leverage cuBLAS functionalities, rather than exposing a direct Python API itself. The current version is 12.9.2.10, and it is actively maintained with frequent updates.","status":"active","version":"12.9.2.10","language":"python","source_language":"en","source_url":"https://pypi.org/project/nvidia-cublas-cu12/","tags":["cuda","nvidia","cublas","blas","gpu","hpc","deep learning","machine learning","runtime"],"install":[{"cmd":"pip install nvidia-cublas-cu12","lang":"bash","label":"Install latest version"}],"dependencies":[{"reason":"Required base CUDA NVRTC runtime library for CUDA 12.x compatibility.","package":"nvidia-cuda-nvrtc-cu12","optional":false},{"reason":"An example of a higher-level Python library that can use nvidia-cublas-cu12 as an optional backend for accelerated linear algebra. Requires installing with `[cu12]` extra.","package":"nvmath-python","optional":true},{"reason":"Deep learning frameworks like PyTorch often depend on specific nvidia-*cu12 packages for CUDA acceleration.","package":"torch","optional":true}],"imports":[{"note":"nvidia-cublas-cu12 is a runtime dependency, not a Python library with direct callable symbols. Its functionality is accessed indirectly by libraries like CuPy or PyTorch.","symbol":"libcublas","correct":"This package does not expose direct Python imports. It provides native shared libraries (e.g., libcublas.so, cublas.dll) that other Python libraries link against."}],"quickstart":{"code":"import os\n# nvidia-cublas-cu12 itself does not have direct Python imports or a quickstart.\n# Its purpose is to provide the underlying shared libraries for other Python packages.\n# For example, nvmath-python can leverage it.\n# To use a library that depends on nvidia-cublas-cu12, you'd typically install it like:\n# pip install nvmath-python[cu12] cupy-cuda12x\n\n# Example of how a dependent library (like nvmath-python or CuPy) *might*\n# indicate the presence of cuBLAS. This code is conceptual, not direct use of this package.\n# Replace with actual usage from a wrapper library if available and runnable.\n\ntry:\n    # Attempt to import a library that *uses* cuBLAS if installed\n    import cupy as cp\n    print(f\"CuPy version: {cp.__version__}\")\n    print(f\"CuPy CUDA enabled: {cp.cuda.is_available()}\")\n    if cp.cuda.is_available():\n        a = cp.random.rand(5, 5)\n        b = cp.random.rand(5, 5)\n        c = a @ b # This operation would internally use cuBLAS\n        print(f\"CuPy matrix multiplication (via cuBLAS if linked) successful.\\nResult shape: {c.shape}\")\n    else:\n        print(\"CuPy is installed but CUDA is not available. Ensure drivers and CUDA runtime are correctly set up.\")\nexcept ImportError:\n    print(\"CuPy not installed. Install with `pip install cupy-cuda12x` to test CUDA functionality.\")\nexcept Exception as e:\n    print(f\"An error occurred during CuPy test: {e}\")\n\n# The presence of `nvidia-cublas-cu12` itself can be verified at the system level.\n# For direct validation of the package installation:\nimport pkg_resources\ntry:\n    distribution = pkg_resources.get_distribution('nvidia-cublas-cu12')\n    print(f\"\\nPackage 'nvidia-cublas-cu12' is installed. Version: {distribution.version}\")\nexcept pkg_resources.DistributionNotFound:\n    print(\"Package 'nvidia-cublas-cu12' not found. Please install it.\")","lang":"python","description":"This package primarily installs native runtime shared libraries, and does not provide a direct Python API for end-user interaction. Its functionality is exposed through higher-level Python wrappers like CuPy or frameworks like PyTorch. The quickstart demonstrates how to verify the installation of the `nvidia-cublas-cu12` package and conceptually shows how a dependent library like CuPy would leverage the underlying CUBLAS functionality if properly set up. For actual usage of cuBLAS operations, refer to the documentation of libraries that wrap cuBLAS (e.g., `nvmath-python`, `CuPy`, `PyTorch`)."},"warnings":[{"fix":"Ensure all `nvidia-*cuXX` packages, the system CUDA Toolkit, and any dependent libraries (e.g., PyTorch, TensorFlow, CuPy) are aligned to the same major CUDA version (e.g., CUDA 12.x for `cu12`). Regularly update GPU drivers.","message":"Major version numbers (e.g., `cu12` vs. `cu11`) indicate compatibility with specific CUDA Toolkit versions. Mixing `nvidia-cublas-cu12` with libraries compiled for older CUDA versions (e.g., `cu11`) or an incompatible system CUDA toolkit can lead to runtime errors like 'undefined symbols' or 'failed to load shared library'.","severity":"breaking","affected_versions":"All versions"},{"fix":"If you need to build applications that link against cuBLAS, install the full NVIDIA CUDA Toolkit appropriate for your system and target CUDA version, in addition to or instead of the PyPI package.","message":"The `pip` wheels for `nvidia-cublas-cu12` are intended for runtime use and do not include developer tools (like `nvcc`) or header files necessary for compiling applications against cuBLAS. For development purposes (e.g., building custom CUDA extensions), a full NVIDIA CUDA Toolkit installation is typically required.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Explicitly set a workspace for cuBLAS operations when capturing them in CUDA graphs using `cublasSetWorkspace()`. Refer to the cuBLAS documentation for details on workspace management.","message":"When using cuBLAS functions within CUDA graphs in cuBLAS 12.x, not explicitly providing a workspace can lead to `cudaErrorNotSupported (801)` due to stream-ordered memory allocations. This is a change from older cuBLAS versions.","severity":"gotcha","affected_versions":"cuBLAS 12.x and later"},{"fix":"Ensure `LD_LIBRARY_PATH` (Linux) or `PATH` (Windows) includes the directory where the native CUDA and cuBLAS libraries are installed. For pip installations, these are typically within the Python environment's `site-packages` directory or a system-wide CUDA installation. `CUDA_HOME` should point to your CUDA installation directory.","message":"Incorrect `LD_LIBRARY_PATH` or `CUDA_HOME` environment variables can prevent Python applications from finding the installed native cuBLAS shared libraries, resulting in 'cannot open shared object file' errors.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Ensure all necessary runtime and testing dependencies, such as CuPy, are installed in your environment if you intend to fully verify CUDA functionality.","message":"Testing of CUDA-dependent functionality for `nvidia-cublas-cuXX` may be skipped or incomplete if required libraries like CuPy (e.g., `cupy-cuda12x`) are not installed.","severity":"gotcha","affected_versions":"All versions"},{"fix":"To install this package, you must first install `nvidia-pyindex` to configure pip to use the NVIDIA Python Package Index. The correct installation sequence is: `pip install nvidia-pyindex` followed by `pip install nvidia-cublas-cu12`.","message":"The package `nvidia-cublas-cu12` (and similar `nvidia-*cuXX` packages) available on PyPI.org are often placeholder projects. These packages are primarily hosted on the NVIDIA Python Package Index.","severity":"breaking","affected_versions":"All versions"}],"env_vars":null,"last_verified":"2026-05-12T14:53:39.682Z","next_check":"2026-06-26T00:00:00.000Z","problems":[{"fix":"Ensure the NVIDIA CUDA Toolkit is correctly installed and its 'lib64' directory (e.g., '/usr/local/cuda-12.x/lib64') is included in the 'LD_LIBRARY_PATH' environment variable. For example: 'export LD_LIBRARY_PATH=/usr/local/cuda/lib64:$LD_LIBRARY_PATH'.","cause":"The system cannot find the 'libcublas.so.12' shared library, typically due to an incorrect 'LD_LIBRARY_PATH' environment variable, an incomplete CUDA Toolkit installation, or a version mismatch between the CUDA Toolkit and the consuming application.","error":"cannot open shared object file: libcublas.so.12: No such file or directory"},{"fix":"Verify that your CUDA driver and toolkit versions are compatible with your deep learning framework (e.g., PyTorch, TensorFlow). Update GPU drivers to the latest stable version, ensure sufficient GPU memory is available for the operation, and consider restarting your kernel or system.","cause":"The cuBLAS library failed to initialize, often due to incompatible CUDA driver/toolkit versions, insufficient GPU memory, or an unstable GPU environment.","error":"RuntimeError: cuda error: cublas_status_not_initialized"},{"fix":"Ensure your Python environment (OS, architecture, Python version) matches the available pre-built wheels for 'nvidia-cublas-cu12'. If installing PyTorch, use the specific installation command from the PyTorch website that matches your CUDA version and platform. For Docker environments, avoid Alpine-based images if PyTorch only provides 'glibc' wheels.","cause":"This error from pip or uv indicates an incompatibility between the requested 'nvidia-cublas-cu12' version (often a dependency of a deep learning framework like PyTorch) and the system's platform (OS, architecture, Python version) for which no pre-built wheel is available.","error":"Distribution 'nvidia-cublas-cu12==X.Y.Z' can't be installed because it doesn't have a source distribution or wheel for the current platform"},{"fix":"In your 'CMakeLists.txt', ensure you explicitly call 'find_package(CUDAToolkit REQUIRED)' (for CMake 3.17+). Verify that the CUDA Toolkit is correctly installed and discoverable; you might need to set environment variables like 'CUDA_PATH' or 'CUDAToolkit_ROOT' to help CMake find it. Also, ensure cuBLAS workspace is correctly configured to avoid allocation issues within graphs.","cause":"When building C/C++ projects with CMake that depend on cuBLAS, this error occurs because CMake cannot locate the 'CUDA::cublas' target. This typically happens if 'find_package(CUDAToolkit)' was not called, failed, or the CUDA Toolkit installation is incomplete or not properly configured for CMake discovery.","error":"Target \"CUDA::cublas\" links to target \"CUDA::cublas\" but the target was not found. Perhaps a find_package() call is missing for an IMPORTED target, or an ALIAS target is missing?"}],"ecosystem":"pypi","meta_description":null,"install_score":0,"install_tag":"stale","quickstart_score":0,"quickstart_tag":"stale","pypi_latest":null,"install_checks":{"last_tested":"2026-05-12","tag":"stale","tag_description":"widespread failures or data too old to trust","results":[{"runtime":"python:3.10-alpine","python_version":"3.10","os_libc":"alpine (musl)","variant":"default","exit_code":1,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":null,"mem_mb":null,"disk_size":null},{"runtime":"python:3.10-slim","python_version":"3.10","os_libc":"slim (glibc)","variant":"default","exit_code":1,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":null,"mem_mb":null,"disk_size":null},{"runtime":"python:3.11-alpine","python_version":"3.11","os_libc":"alpine (musl)","variant":"default","exit_code":1,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":null,"mem_mb":null,"disk_size":null},{"runtime":"python:3.11-slim","python_version":"3.11","os_libc":"slim (glibc)","variant":"default","exit_code":1,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":null,"mem_mb":null,"disk_size":null},{"runtime":"python:3.12-alpine","python_version":"3.12","os_libc":"alpine (musl)","variant":"default","exit_code":1,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":null,"mem_mb":null,"disk_size":null},{"runtime":"python:3.12-slim","python_version":"3.12","os_libc":"slim (glibc)","variant":"default","exit_code":1,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":null,"mem_mb":null,"disk_size":null},{"runtime":"python:3.13-alpine","python_version":"3.13","os_libc":"alpine (musl)","variant":"default","exit_code":1,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":null,"mem_mb":null,"disk_size":null},{"runtime":"python:3.13-slim","python_version":"3.13","os_libc":"slim (glibc)","variant":"default","exit_code":1,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":null,"mem_mb":null,"disk_size":null},{"runtime":"python:3.9-alpine","python_version":"3.9","os_libc":"alpine (musl)","variant":"default","exit_code":1,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":null,"mem_mb":null,"disk_size":null},{"runtime":"python:3.9-slim","python_version":"3.9","os_libc":"slim (glibc)","variant":"default","exit_code":1,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":null,"mem_mb":null,"disk_size":null}]},"quickstart_checks":{"last_tested":"2026-04-23","tag":"stale","tag_description":"widespread failures or data too old to trust","results":[{"runtime":"python:3.10-alpine","exit_code":0},{"runtime":"python:3.10-slim","exit_code":-1},{"runtime":"python:3.11-alpine","exit_code":1},{"runtime":"python:3.11-slim","exit_code":-1},{"runtime":"python:3.12-alpine","exit_code":1},{"runtime":"python:3.12-slim","exit_code":-1},{"runtime":"python:3.13-alpine","exit_code":1},{"runtime":"python:3.13-slim","exit_code":-1},{"runtime":"python:3.9-alpine","exit_code":1},{"runtime":"python:3.9-slim","exit_code":-1}]}}