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.
- v0 (meta.yaml)
- v1 (recipe.yaml)
requirements:
build:
- {{ compiler('cuda') }}
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.
- v0 (meta.yaml)
- v1 (recipe.yaml)
requirements:
host:
- cuda-version {{ cuda_compiler_version }}.*
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:
- Use the
cuda_compiler_versionvariable as a switch for the CUDA requirements. - Give the CUDA variant a higher build number than the non-CUDA variant, so the solver prefers it where it can be installed.
- Add the
__cudavirtual 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:
- v0 (meta.yaml)
- v1 (recipe.yaml)
{% set 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:
- {{ compiler('cuda') }} # [cuda_compiler_version != "None"]
host:
- libcublas-dev # [cuda_compiler_version != "None"]
- cuda-version {{ cuda_compiler_version }}.* # [cuda_compiler_version != "None"]
run:
# Makes the CUDA variant uninstallable without a CUDA driver
- __cuda # [cuda_compiler_version != "None"]
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:
- Ignore the run exports from any CTK library
-dev/-develpackages 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. - Ignore the run exports of the
cuda-versionpackage. - 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:
- v0 (meta.yaml)
- v1 (recipe.yaml)
build:
# Ignore run exports from CUDA libraries in the host section
ignore_run_exports_from:
- libcublas-dev
# Ignore cuda-version itself; do not ignore exports from
# compiler('cuda'), which has other needed exports
ignore_run_exports:
- cuda-version
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
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:
- build.sh
- bld.bat
export TORCH_CUDA_ARCH_LIST="$CF_TORCH_CUDA_ARCH_LIST"
set 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.
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.
# 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"
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.
- v0 (meta.yaml)
- v1 (recipe.yaml)
# Variant variables must be referenced in the recipe or conda-smithy strips them
# from the build matrix
env:
- 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 }}
test:
requires:
# Otherwise cuda-arch would float up to the newest allowed version
- cuda-arch {{ cuda_arch_version }}
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:
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
- cudnn-feedstock (
meta.yaml) - kokkos-feedstock (
recipe.yaml, with multiple variants)
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:
- v0 (meta.yaml)
- v1 (recipe.yaml)
build:
...
missing_dso_whitelist:
- "*/nvcuda.dll" # [win]
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.