Skip to main content

NVIDIA CUDA packages

This page is for people who wish to use conda environments to run CUDA-enabled software. To build CUDA packages, see Build NVIDIA CUDA packages.

CUDA prerequisites​

You must have an NVIDIA GPU on your machine and you must install the CUDA drivers. The CUDA driver cannot be installed with conda and must be installed on your system using an appropriate installation method. See the CUDA documentation for instructions on how to install the CUDA driver (Linux, Windows).

Conda CUDA packages are installable even if no CUDA driver or NVIDIA GPU is available, but they will not run properly. See Installing CUDA packages without a GPU for how to do this.

Installing CUDA-enabled packages​

You do not need to install the CUDA Toolkit yourself to use CUDA-enabled packages. They depend on the CUDA libraries they need, and conda installs those as dependencies. For example, to install PyTorch:

conda install -c conda-forge pytorch

If conda detects a CUDA driver (that is, the __cuda virtual package is available), it selects the CUDA-enabled build. To choose the major version of CUDA, add the cuda-version metapackage:

conda install -c conda-forge pytorch cuda-version=12

To require a CUDA-enabled build, match the build string:

conda install -c conda-forge "pytorch=*=cuda*"

Installing CUDA packages without a GPU​

All of the CUDA packages can be installed in an environment without a physical GPU or CUDA driver, such as on an HPC login node (where the compute nodes have GPUs but no internet access) or on free-tier CIs by setting the CONDA_OVERRIDE_CUDA environment variable to the desired CUDA version.

CONDA_OVERRIDE_CUDA="12.9" conda install tensorflow -c conda-forge

In cmd and PowerShell the variable stays set for the rest of the shell session.

Even if the package requires CUDA to run, this allows packaging and dependency resolution to be tested in a CPU-only environment.

Installing the CUDA Toolkit​

The sections below are for developers who need the CUDA compiler, headers, or tools. Most users do not need to install the full toolkit.

Basic Installation​

The easiest one-step solution to install the full CUDA Toolkit is to install the cuda metapackage with this command:

conda install -c conda-forge cuda cuda-version=12.9

Let's break down this command. We are requesting the installation of two metapackages: cuda and cuda-version.

The cuda metapackage pulls in all the components of the CUDA Toolkit (CTK) and is roughly equivalent to installing the CUDA Toolkit with traditional system package managers like apt or yum on Linux. Similarly to such package managers, the individual components may also be installed independently.

The cuda-version metapackage is used to select the version of CUDA to install. This metapackage is important because individual components of the CTK are typically versioned independently (the current versions may be found in the release notes). The cuda-version metapackage provides a standard way to install the version of a specific CUDA component corresponding to a given version of the CTK. This way, one never has to specify a particular version of any CTK package; one just specifies the cuda-version desired, then list packages needed and conda will take care of finding the right versions. The above command will install all components of CUDA from the latest patch release of the CUDA 12.x series.

note

The following CUDA components are not available as conda packages:

  • Driver libraries, such as (but not limited to)
    • libcuda
    • libnvidia-ml library
    • GPUDirect Storage (GDS)
  • Documentation and Samples
  • Fabric Manager
  • IMEX
  • NVSwitch Configuration and Query (NSCQ)
  • Nsight Systems

Installing individual components of the CUDA Toolkit​

Rather than installing all of CUDA at once, users may instead install just the packages that they need. For example, to install just libcublas-dev and libcusparse-dev one may run:

conda install -c conda-forge libcublas-dev libcusparse-dev cuda-version=13

The best way to get a current listing is to run:

conda install --dry-run -c conda-forge cuda cuda-version=13

For a complete listing of the packages that were originally created, see this issue.

Metapackages​

For convenience, a number of additional metapackages are available:

  • cuda-runtime / cuda-libraries: All CUDA runtime libraries needed to run a CUDA application
  • cuda-visual-tools: GUIs for visualizing and profiling such as Nsight™ Compute
  • cuda-command-line-tools: Command line tools for analyzing and profiling such as cupti, cuda-gdb, and Compute Sanitizer
  • cuda-tools: All tools for analyzing and profiling, both GUI (includes cuda-visual-tools) and CLI (includes cuda-command-line-tools)

Selecting ARM Device Variant​

Many of NVIDIA's CUDA packages are built for both SBSA and Tegra devices. For CUDA 12.9, Tegra devices are a separate ARM variant. To install packages built for CUDA 12.9 Tegra, add the arm-variant=*=tegra package to your environment. For CUDA 13.0 and later, the arm-variant package is no longer required. Tegra devices are no longer a separate architecture from SBSA.

conda install -c conda-forge pytorch "arm-variant=*=tegra"
info

Support for Tegra builds on conda-forge is only available for CUDA 12.9 and later. This means that only Orin (sm_87) and later devices are supported.

CUDA C++ Core Libraries (CCCL)​

CCCL is a special case among CUDA packages. Due to 1) being header-only, 2) fast-moving, and 3) independently-evolving, consumers may want a different (newer) version of CCCL than the one corresponding to their CTK version. Instructions on how to install a suitable CCCL package from conda can be found in the CCCL README. See this issue for more information on the history of these packages.

CUDA package naming conventions​

CUDA libraries are split into separate packages with standard naming:

  • The base package (e.g., libcublas) provides runtime shared libraries.
  • The *-dev package includes headers, symlinks, and CMake files for compiling code that dynamically links the library.
  • The *-static package includes the static library for static linking. For build files, users may also needed to install the *-dev packages.

For example, libcublas is available as libcublas, libcublas-dev, and libcublas-static.

CUDA development metapackages​

The above discussion of naming also applies to metapackages. For instance, the cuda-libraries package contains all the runtime libraries, while cuda-libraries-dev also includes dependencies on the corresponding *-dev packages. In addition, for the purposes of development there are a few additional key metapackages:

  • cuda-compiler: All packages required to compile a minimal CUDA program (one that does not require e.g. extra math libraries like cuBLAS or cuSPARSE).

Compatibility between the conda-forge vs nvidia channels​

Understanding the difference between the CUDA packages on the conda-forge and nvidia channels requires a bit of history because of how the relationship has evolved over time. In particular, how these channels may or may not coexist will depend on the versions of CUDA that you need support for.

Pre-CUDA 12

Prior to CUDA 12, the only package available on conda-forge was the cudatoolkit package, a community-maintained, monolithic package containing the entire repackaged CTK. During the CUDA 11 release cycle, NVIDIA began developing a set of CUDA Toolkit packages in the nvidia channel. Unlike the monolithic conda-forge package, the nvidia channel distributed the CTK split into components such that each library was given its own package. This package organization made it possible to install separate components independently and better aligned the conda packaging ecosystem with other package managers, such as those for Linux distributions. However, this organization introduced a number of changes that were at times confusing -- such as the introduction of a cuda-toolkit (note the hyphen) metapackage that installs a partially overlapping set of components to the original cudatoolkit -- and at other times breaking, particularly in conda environments configured to pull packages from both conda-forge and the nvidia channel. Therefore, in a CUDA 11 world the conda-forge and nvidia channels were difficult to use in the same environment without some care.

CUDA 12.0-12.4

With the CUDA 12 release, NVIDIA contributed the new packaging structure to conda-forge, introducing the CUDA Toolkit packages that existed on the nvidia channel as a replacement for the old cudatoolkit package on conda-forge. This was done starting with CUDA 12.0 to indicate the breaking nature of these changes compared to the prior CUDA 11.x packaging in conda-forge. These packages became the standard mechanism for delivering CUDA conda packages. Due to the scale of the reorganization, the CUDA 12.0, 12.1, and 12.2 releases also involved numerous additional fixes to the packaging structure to better integrate them in the conda ecosystem. Due to the number of such changes that were required and the focus on improving the quality of these installations, no corresponding updates were provided for packages on the nvidia channel during this time period. While the conda-forge and nvidia channel package lists were the same (i.e. the same packages existed in both places with the same core contents like libraries and headers), the nvidia channel did not include many of the incremental fixes made on conda-forge to improve things like symlinks, static library handling, proper package constraints, etc. As a result, nvidia and conda-forge CUDA packages remained incompatible from CUDA 12.0-12.4.

CUDA 12.5+

With CUDA 12.5, the nvidia channel was fully aligned with conda-forge. Packages on both channels are identical, ensuring safe coexistence of the two channels within the same conda environment.

Additionally Anaconda has incorporated compatible CUDA 12 packages in its defaults channel.

Going forward, CUDA packages on the conda-forge and nvidia channels should be expected to remain compatible.

CUDA 13.4+

CUDA 13.3, is the last CTK release to the nvidia channel.

Going forward, CUDA packages should be retrieved from conda-forge.

Compiling CUDA code in your environment​

Beginning with CUDA 12.0, a full suite of CUDA packages is provided in conda-forge, including various metapackages that group components together. To compile CUDA host or device code in your environment, see CUDA package naming conventions and CUDA development metapackages.

Troubleshooting CUDA​

What if I see an error saying __cuda is too old?​

The __cuda virtual package is used by conda to represent the maximum CUDA version fully supported by the available CUDA driver. See the conda docs on virtual packages for more information.

To update the __cuda virtual package, you must install a newer driver:

If conda has incorrectly identified the CUDA driver, you can override by setting the CONDA_OVERRIDE_CUDA environment variable to a version number like "12.5" or "" to indicate that no CUDA driver is detected.