Skip to main content

How to write a recipe that depends on CUDA

Recipes for packages that depend on the CUDA Toolkit typically are more complicated compared to other compiled-code recipes. This guide covers best practices and common situations for recipes that depend on CUDA.

Add the CUDA compiler​

Add the {{ compiler('cuda') }} template to your recipe to install NVCC and enable CUDA variants in your feedstock. Remember to rerender.

requirements:
build:
- ${{ compiler('cuda') }}

Pin the host environment​

Pin the cuda-version package to cuda_compiler_version in the host environment, so that any host dependencies are compatible with the CUDA compiler.

requirements:
host:
- cuda-version ${{ cuda_compiler_version }}.*

Only use the required CUDA components​

Do not use CUDA metapackages (e.g. cuda-toolkit) to specify dependencies. Instead, specify only the minimal subset of CUDA components that your package requires (e.g. libcufft-dev). Specifying a -dev/-devel package as a host requirement makes your package require the corresponding non-dev package at run time, because the -dev/-devel packages have run_exports.

Build both CUDA and non-CUDA variants​

If your recipe has separate variants for CUDA and non-CUDA builds:

  1. Use the cuda_compiler_version variable as a switch for the CUDA requirements.
  2. Give the CUDA variant a higher build number than the non-CUDA variant, so the solver prefers it where it can be installed.
  3. Add the __cuda virtual package as a runtime requirement of the CUDA variant. This makes the CUDA variant uninstallable on machines without a CUDA driver, which would otherwise download large GPU packages needlessly. Users without a CUDA driver get the non-CUDA variant instead.

For example:

context:
build_number: 0

build:
# Prefer the CUDA variant when it is installable
number: ${{ build_number + (100 if cuda_compiler_version != "None" else 0) }}

requirements:
build:
- if cuda_compiler_version != "None":
then: ${{ compiler('cuda') }}
host:
- if cuda_compiler_version != "None":
then:
- libcublas-dev
- cuda-version ${{ cuda_compiler_version }}.*
run:
# Makes the CUDA variant uninstallable without a CUDA driver
- if: cuda_compiler_version != "None"
then: __cuda

Support CUDA Enhanced Compatibility​

If your package's code already supports CUDA Enhanced Compatibility, make these changes to the recipe so that the conda package supports it too:

  1. Ignore the run exports from any CTK library -dev/-devel packages that your package depends on. Otherwise, the run exports would require runtime libraries with versions equal to or greater than the versions used to build the package.
  2. Ignore the run exports of the cuda-version package.
  3. Add explicit runtime dependencies (or constraints for soft/optional dependencies) that specify the desired version range for the dependencies whose run exports you ignored.

For example, because of run exports in the libcublas-dev package, a package that requires libcublas has a run requirement on libcublas corresponding to {{ cuda_compiler_version }} or newer. To make it compatible with all CUDA minor versions from the same CUDA major version family, add the following:

requirements:
build:
- ${{ compiler('cuda') }}
host:
- libcublas-dev
- cuda-version ${{ cuda_compiler_version }}.*
run:
# Since we've ignored the run export from libcublas-dev, we pin
# libcublas manually. Having a pin_compatible on cuda-version with
# max_pin='x' and min_pin='x' will constrain libcublas to the same
# major version as what we pinned in host.
- ${{ pin_compatible('cuda-version', max_pin='x', min_pin='x') }}
- libcublas
# Ignore run exports from CUDA libraries in the host section
ignore_run_exports:
from_package:
- libcublas-dev
# Ignore cuda-version itself; do not ignore exports from
# compiler('cuda'), which has other needed exports
by_name:
- cuda-version

Set CUDA architecture targets​

Packages built on conda-forge should target broad compatibility across CUDA devices. This means passing explicit compiler arguments to NVCC to target all supported CUDA architectures instead of accepting the compiler's default target.

Use variables set by the CUDA compiler conda package​

The CUDA compiler package activation script automatically sets the environment variables CUDAARCHS and NVCC_GENCODE to all supported CUDA architectures for the target host platform when CONDA_BUILD is detected and when they are not already set. Use these environment variables in your build script instead of hard-coding architectures. You then do not need to update your build scripts when new architectures become available in new releases of the CUDA Toolkit.

Use variables set by the PyTorch conda package​

The libtorch/pytorch packages similarly set CF_TORCH_CUDA_ARCH_LIST in their activation scripts. To keep the CUDA targets of a PyTorch module up to date, set TORCH_CUDA_ARCH_LIST=${CF_TORCH_CUDA_ARCH_LIST} in your build environment.

For example, in your build script:

export TORCH_CUDA_ARCH_LIST="$CF_TORCH_CUDA_ARCH_LIST"

Set your own CUDA architecture targets​

If your package only supports a subset of all CUDA architectures, depend on the cuda-arch metapackage to express the minimum compute capability it supports. Packages that use one of the options above do not need cuda-arch.

For example, a package built with cuda-arch=6.0 is only installable when a user's least capable device has compute capability 6.0 (Pascal) or later. Users who see __cuda_arch errors should read the user guide.

note

Using cuda-arch to split a package into multiple cuda-arch variants makes it more difficult to generate lock files which include the package. Because the lock file will only lock one of the variants at a time, multiple lock files will need to be created or consumers of the lock file may experience sub-optimal performance or uninstallable lock files depending on their hardware configuration.

See Lock files and CUDA packages for more information.

Define the minimum architecture​

In your conda_build_config.yaml, define the minimum supported target architecture and the build arguments that you want to use for it. Leave no compatibility gaps between the minimum target and the highest target.

conda_build_config.yaml
# CMake reads CUDAARCHS and passes it to NVCC
CUDAARCHS:
- "70-real;80-real;90-real;90-virtual"

# The minimum compute capability your build supports
cuda_arch_version:
- "7.0"
warning

The variable holding the minimum architecture MUST be named cuda_arch_version. conda-forge-ci-setup looks for this name to decide what value to set for CONDA_OVERRIDE_CUDA_ARCH on the build runner.

Always include PTX for the highest architecture targeted by your build. The plugin reports only the minimum compute capability on the system, so a machine may have a mix of newer and older devices.

Pin cuda-arch in the recipe​

Pass the architecture flags to the build, and pin cuda-arch in host and in the test environments. The cuda-arch metapackage has run_exports, so a package with cuda-arch in host automatically gets the matching run requirement. The name of the environment variable that carries the architecture flags depends on your build system; CUDAARCHS is used here for CMake.

build:
script:
env:
# Variant variables must be referenced in the recipe or conda-smithy strips
# them from the build matrix
CUDAARCHS: ${{ CUDAARCHS }}

requirements:
build:
- ${{ compiler('cuda') }}
host:
# Pin the minimum supported arch so that dependencies are compatible with it too
- cuda-arch ${{ cuda_arch_version }}.*

tests:
- requirements:
run:
# Otherwise cuda-arch would float up to the newest allowed version
- cuda-arch ${{ cuda_arch_version }}.*

Use architecture-specific instruction sets​

If your program benefits from instruction sets such as 90a or 120f, use them. Every sm_90 device also supports sm_90a, and every sm_120 device also supports sm_120f. Sub-architectures such as 100f cannot be expressed as cuda-arch versions but can still be targeted at build time.

These instruction sets are not forward-compatible, so include non-specific PTX for the highest target architecture:

conda_build_config.yaml
TORCH_CUDA_ARCH_LIST:
- "8.0 9.0a 10.0a 10.0f 10.0+PTX"

cuda_arch_version:
- "8.0"

Here 10.0+PTX provides forward compatibility. 9.0+PTX is unnecessary because any device it would run on also supports 9.0a or 10.0+PTX.

Real world examples​

Fix nvcuda.dll not found on Windows​

nvcuda.dll is part of the NVIDIA driver and is not available on the Windows CI machines because no GPU is physically present. As a result, you might get linking errors in the postprocessing steps of conda build:

WARNING (arrow-cpp,Library/bin/arrow_cuda.dll): $RPATH/nvcuda.dll not found in packages,
sysroot(s) nor the missing_dso_whitelist.

.. is this binary repackaging?

For now, you will have to add nvcuda.dll to the missing_dso_whitelist:

build:
...
dynamic_linking:
missing_dso_allowlist:
- if: win
then: "*/nvcuda.dll"

Adopt a new CUDA version​

As new CUDA versions come out regularly, periodically conda-forge needs to decide how many versions will be supported within resource constraints. As of August 2026, conda-forge supports CUDA 12 and 13.

conda-forge manages the adoption of a new CUDA major version with a migration. The migration bot opens a pull request in your feedstock with the changes needed to build for the new version.

To update to the latest supported versions outside of a migration, or if your feedstock no longer builds old CUDA versions, rerender the feedstock. There may be other fixes needed for the feedstock depending on when it was last updated.