5.2. CUDA 环境变量

5.2.1.1. CUDA_VISIBLE_DEVICES

该环境变量控制哪些 GPU 设备对 CUDA 应用程序可见，以及枚举这些设备的顺序。

• 如果未设置该变量，则所有 GPU 设备均可见。

• 如果将该变量设置为空字符串，则所有 GPU 设备均不可见。

可能的值：以逗号分隔的 GPU 标识符序列。

GPU 标识符以如下形式提供：

• 整数索引：这些索引对应于 GPU 在系统中的序号，由nvidia-smi确定，从 0 开始。例如，设置CUDA_VISIBLE_DEVICES=2,1会使设备 0 不可见，并在设备 1 之前枚举设备 2。

  • 如果遇到无效索引，则只有索引出现在列表中该无效索引之前的设备才可见。例如，设置CUDA_VISIBLE_DEVICES=0,2,-1,1会使设备 0 和 2 可见，而设备 1 不可见，因为它出现在无效索引-1之后。

• GPU UUID 字符串：这些字符串应遵循nvidia-smi -L给出的相同格式，例如GPU-8932f937-d72c-4106-c12f-20bd9faed9f6。不过，为方便起见，也允许使用缩写形式；只需从 GPU UUID 的开头起指定足够多的位数，以便在目标系统中唯一标识该 GPU。例如，假设系统中没有其他 GPU 具有相同前缀，那么CUDA_VISIBLE_DEVICES=GPU-8932f937就可能是引用上述 GPU UUID 的一种有效方式。

• 多实例 GPU（MIG）支持：MIG-<GPU-UUID>/<GPU instance ID>/<compute instance ID>。例如，MIG-GPU-8932f937-d72c-4106-c12f-20bd9faed9f6/1/2。仅支持枚举单个 MIG 实例。

cudaGetDeviceCount()API 返回的设备数量仅包括可见设备，因此，使用整数设备标识符的 CUDA API 仅支持 [0, 可见设备数量 - 1] 范围内的序号。GPU 设备的枚举顺序决定了序号值。例如，在CUDA_VISIBLE_DEVICES=2,1的情况下，调用cudaSetDevice(0)会将设备 2 设置为当前设备，因为它最先被枚举到，并被分配了序号 0。此后调用cudaGetDevice(&device_ordinal)也会将device_ordinal设置为 0，对应于设备 2。

示例：

nvidia-smi -L # Get list of GPU UUIDs
CUDA_VISIBLE_DEVICES=0,1
CUDA_VISIBLE_DEVICES=GPU-8932f937-d72c-4106-c12f-20bd9faed9f6
CUDA_VISIBLE_DEVICES=MIG-GPU-8932f937-d72c-4106-c12f-20bd9faed9f6/1/2

5.2.1.2. CUDA_DEVICE_ORDER

该环境变量控制 CUDA 枚举可用设备的顺序。

可选值：

• FASTEST_FIRST：使用简单的启发式方法，按从最快到最慢的顺序枚举可用设备（默认）。

• PCI_BUS_ID：按 PCI 总线 ID 的升序枚举可用设备。PCI 总线 ID 可通过nvidia-smi --query-gpu=name,pci.bus_id获取。

示例：

CUDA_DEVICE_ORDER=FASTEST_FIRST
CUDA_DEVICE_ORDER=PCI_BUS_ID
nvidia-smi --query-gpu=name,pci.bus_id # Get list of PCI bus IDs

5.2.1.3. CUDA_MANAGED_FORCE_DEVICE_ALLOC

该环境变量改变多 GPU 系统中统一内存的物理存储方式。

可选值：数值，可以为零或非零。

• 非零值：强制驱动程序使用设备内存进行物理存储。进程中使用的所有支持托管内存的设备都必须具备对等兼容性。否则，将返回cudaErrorInvalidDevice。

• 0：默认行为。

示例：

CUDA_MANAGED_FORCE_DEVICE_ALLOC=0
CUDA_MANAGED_FORCE_DEVICE_ALLOC=1 # force device memory

5.2.2.1. CUDA_CACHE_DISABLE

该环境变量控制磁盘上的即时（JIT）编译缓存的行为。禁用 JIT 缓存会强制 CUDA 应用程序在每次执行时进行 PTX 到 CUBIN 的编译，除非在二进制文件中找到了适用于运行架构的 CUBIN 代码。同一缓存还用于存储最终化后的 cubin，设置此环境变量也会在必要时强制对 cubin 进行最终化。

禁用 JIT 缓存会增加应用程序首次执行时的加载时间。不过，这有助于减少应用程序占用的磁盘空间，以及诊断不同驱动程序版本或构建标志带来的差异。

可选值：

• 1：禁用 PTX JIT 和二进制最终化缓存。

• 0：启用 PTX JIT 缓存（默认）。

示例：

CUDA_CACHE_DISABLE=1 # disables caching
CUDA_CACHE_DISABLE=0 # enables caching

5.2.2.2. CUDA_CACHE_PATH

该环境变量指定即时（JIT）编译缓存的目录路径。同一缓存还用于存储最终化后的 cubin。

可选值：缓存目录的绝对路径（具有适当的访问权限）。默认值为：

• 在 Windows 上，为%APPDATA%\NVIDIA\ComputeCache

• 在 Linux 上，为~/.nv/ComputeCache

示例：

CUDA_CACHE_PATH=~/tmp

5.2.2.3. CUDA_CACHE_MAXSIZE

该环境变量指定即时（JIT）编译缓存的大小，以字节为单位。超过此大小的二进制文件不会被缓存。如果需要，会从缓存中逐出较旧的二进制文件，以便为较新的二进制文件腾出空间。同一缓存还用于存储最终化后的 cubin。

可选值：字节数。默认值为：

• 在桌面/服务器平台上，为1073741824（1 GiB）

• 在嵌入式平台上，为268435456（256 MiB）

最大大小为4294967296（4 GiB）。

示例：

CUDA_CACHE_MAXSIZE=268435456 # 256 MiB

5.2.2.4. CUDA_FORCE_PTX_JIT和CUDA_FORCE_JIT

这些环境变量指示 CUDA 驱动程序忽略应用程序中嵌入的任何 CUBIN，转而对嵌入的 PTX 代码执行即时（JIT）编译。

强制 JIT 编译会增加应用程序首次执行时的加载时间。不过，这可用于验证应用程序中是否嵌入了 PTX 代码，以及其即时编译是否正常运行。这确保了与未来架构的前向兼容性。

CUDA_FORCE_PTX_JIT会覆盖CUDA_FORCE_JIT。

可选值：

• 1：强制进行 PTX JIT 编译。

• 0：默认行为。

示例：

CUDA_FORCE_PTX_JIT=1

5.2.2.5. CUDA_DISABLE_PTX_JIT和CUDA_DISABLE_JIT

这些环境变量禁用对嵌入的 PTX 代码的即时（JIT）编译，并使用应用程序中嵌入的兼容 CUBIN。

如果核函数没有嵌入的二进制代码，或者嵌入的二进制代码是针对不兼容的架构编译的，则该核函数将无法加载。这些环境变量可用于验证应用程序是否为每个核函数生成了兼容的 CUBIN 代码。有关更多详细信息，请参阅二进制兼容性一节。

CUDA_DISABLE_PTX_JIT会覆盖CUDA_DISABLE_JIT。

可选值：

• 1：禁用 PTX JIT 编译。

• 0：默认行为。

示例：

CUDA_DISABLE_PTX_JIT=1

5.2.2.6. CUDA_FORCE_PRELOAD_LIBRARIES

该环境变量影响NVVM和即时（JIT）编译所需库的预加载。

可选值：

• 1：这会强制驱动程序在初始化期间预加载NVVM和即时（JIT）编译所需的库。这会增加内存占用和 CUDA 驱动程序初始化所需的时间。要避免涉及多个线程的某些死锁情况，必须设置此环境变量。

• 0：默认行为。

示例：

CUDA_FORCE_PRELOAD_LIBRARIES=1

5.2.3.1. CUDA_LAUNCH_BLOCKING

该环境变量指定禁用还是启用异步核函数启动。

禁用异步执行会导致执行速度变慢，但有助于调试。它会强制 GPU 工作从 CPU 的角度来看同步运行。这样便可以在触发错误的具体 API 调用处观察到 CUDA API 错误，而不是在后续执行过程中才观察到。同步执行有助于调试。

可选值：

• 1：禁用异步执行。

• 0：异步执行（默认）。

示例：

CUDA_LAUNCH_BLOCKING=1

5.2.3.2. CUDA_DEVICE_MAX_CONNECTIONS

该环境变量控制并发计算引擎连接和复制引擎连接（工作队列）的数量，将两者均设置为指定值。如果独立的 GPU 任务，即从不同 CUDA 流中启动的核函数或复制操作，映射到同一个工作队列，就会产生虚假依赖关系，由于使用了相同的底层资源，这可能导致 GPU 工作串行化。为降低出现此类虚假依赖关系的概率，建议通过此环境变量控制的工作队列数量大于或等于每个上下文中的活动 CUDA 流数量。

设置此环境变量也会修改复制连接的数量，除非已通过CUDA_DEVICE_MAX_COPY_CONNECTIONS环境变量显式设置了该数量。

可选值：1至32个连接，默认为8（假定未使用 MPS）

示例：

CUDA_DEVICE_MAX_CONNECTIONS=16

5.2.3.3. CUDA_DEVICE_MAX_COPY_CONNECTIONS

该环境变量控制参与复制操作的并发复制连接（工作队列）的数量。它仅影响计算能力为 8.0 及以上的设备。

如果两者都已设置，CUDA_DEVICE_MAX_COPY_CONNECTIONS会覆盖通过CUDA_DEVICE_MAX_CONNECTIONS设置的复制连接数量。

可选值：1至32个连接，默认为8（假定未使用 MPS）

示例：

CUDA_DEVICE_MAX_COPY_CONNECTIONS=16

5.2.3.4. CUDA_SCALE_LAUNCH_QUEUES

该环境变量指定可用于启动工作的队列（命令缓冲区）大小的缩放因子，即设备上可入队的待处理核函数或主机/设备复制操作的总数的缩放因子。

可选值：0.25x、0.5x、2x、4x

• 除0.25x、0.5x、2x或4x之外的任何值均被解释为1x。

示例：

CUDA_SCALE_LAUNCH_QUEUES=2x

5.2.3.5. CUDA_GRAPHS_USE_NODE_PRIORITY

该环境变量控制 CUDA 图的执行优先级相对于其从启动该图的流所继承的流优先级的关系。

CUDA_GRAPHS_USE_NODE_PRIORITY会覆盖图实例化时的cudaGraphInstantiateFlagUseNodePriority标志。

可选值：

• 0：继承启动该图的流的优先级（默认）。

• 1：遵循各节点的启动优先级。CUDA 运行时将节点级优先级视为对已就绪、可运行的图节点的调度提示。

示例：

CUDA_GRAPHS_USE_NODE_PRIORITY=1

5.2.3.6. CUDA_DEVICE_WAITS_ON_EXCEPTION

该环境变量控制发生异常（错误）时 CUDA 应用程序的行为。

启用后，CUDA 应用程序将在发生设备端异常时暂停并等待，从而可以附加调试器（例如cuda-gdb），以便在进程退出或继续执行之前检查 GPU 的实时状态。

可选值：

• 0：默认行为。

• 1：发生设备异常时暂停。

示例：

CUDA_DEVICE_WAITS_ON_EXCEPTION=1

5.2.3.7. CUDA_DEVICE_DEFAULT_PERSISTING_L2_CACHE_PERCENTAGE_LIMIT

该环境变量控制 GPU 的 L2 缓存中为持久化访问预留的默认“留出”部分，以 L2 大小的百分比表示。

它适用于支持持久化 L2 缓存的 GPU，具体而言，是指使用CUDA 多进程服务（MPS）时，计算能力为 8.0 或更高的设备。必须在启动 CUDA MPS 控制守护进程之前设置该环境变量，即在运行nvidia-cuda-mps-control -d命令之前设置。

可选值：0 到 100 之间的百分比值，默认为 0。

示例：

CUDA_DEVICE_DEFAULT_PERSISTING_L2_CACHE_PERCENTAGE_LIMIT=25 # 25%

5.2.3.8. CUDA_DISABLE_PERF_BOOST

在 Linux 主机上，将此环境变量设置为 1 会阻止提升设备性能状态，而是可以基于各种启发式方法隐式选择 pstate。此选项有可能用于降低功耗，但由于动态选择性能状态，在某些场景中可能会导致更高的延迟。

示例：

CUDA_DISABLE_PERF_BOOST=1 # perf boost disabled, Linux only.
CUDA_DISABLE_PERF_BOOST=0 # default behavior

5.2.3.9. CUDA_PREFER_SPINLOCKS_ON_HOST

此环境变量向 CUDA 驱动程序和运行时提供提示，使其在某些内部主机端同步路径中优先采用基于自旋的加锁模式。在此模式下，内部锁可能会主动轮询以检查是否可用，而不是阻塞并让出 CPU。这可以通过避免内核态切换和唤醒开销，降低短时间持有的锁的同步延迟，从而改善低到中等争用情况下的快速路径性能（例如，多个主机线程争用同一个 CUDA 对象或执行上下文时）。基于自旋的加锁不提供调度器辅助的公平性或优先级继承。在主机线程被抢占、超额订阅或混合工作负载的情况下，启用基于自旋的加锁可能会增加优先级反转、饥饿或系统响应性下降的风险。

可选值：

• 0：默认行为。

• 1：内部同步优先使用自旋锁。

示例：

CUDA_PREFER_SPINLOCKS_ON_HOST=1

5.2.3.10. CUDA_AUTO_BOOST [[已弃用]]

该环境变量影响 GPU 时钟的“自动提升”行为，即动态提升时钟频率。它会覆盖nvidia-smi工具的“自动提升”选项，即nvidia-smi --auto-boost-default=0。

5.2.4.1. CUDA_MODULE_LOADING

该环境变量影响 CUDA 运行时加载模块的方式，具体而言，是其初始化设备代码的方式。

可选值：

• DEFAULT：默认行为，等同于LAZY。

• LAZY：特定核函数的加载会延迟到使用cuModuleGetFunction()或cuKernelGetFunction()API 调用提取 CUDA 函数句柄CUfunc时。在这种情况下，当 CUBIN 中的第一个核函数被加载或其中的第一个变量被访问时，才会加载该 CUBIN 中的数据。

  • 驱动程序在首次调用核函数时加载所需代码；后续调用不会产生额外开销。这会减少启动时间和 GPU 内存占用。

• EAGER：在程序初始化时完整加载 CUDA 模块和核函数。CUBIN、FATBIN 或 PTX 文件中的所有核函数和数据都会在对应的cuModuleLoad*和cuLibraryLoad*驱动程序 API 调用时完整加载。

  • 启动时间更长，GPU 内存占用更高。核函数启动开销是可预测的。

示例：

CUDA_MODULE_LOADING=EAGER
CUDA_MODULE_LOADING=LAZY

5.2.4.2. CUDA_MODULE_DATA_LOADING

该环境变量影响 CUDA 运行时加载与模块关联的数据的方式。

这是对CUDA_MODULE_LOADING中针对核函数的设置的补充。此环境变量不会影响核函数的LAZY或EAGER加载。如果未设置此环境变量，数据加载行为将继承自CUDA_MODULE_LOADING。

可选值：

• DEFAULT：默认行为，等同于LAZY。

• LAZY：模块数据的加载会延迟到需要 CUDA 函数句柄CUfunc时。在这种情况下，当 CUBIN 中的第一个核函数被加载或其中的第一个变量被访问时，才会加载该 CUBIN 中的数据。

  • 延迟加载数据可能需要上下文同步，这可能会降低并发执行速度。

• EAGER：CUBIN、FATBIN 或 PTX 文件中的所有数据都会在对应的cuModuleLoad*和cuLibraryLoad*API 调用时完整加载。

示例：

CUDA_MODULE_DATA_LOADING=EAGER

5.2.4.3. CUDA_BINARY_LOADER_THREAD_COUNT

设置加载设备二进制文件时使用的 CPU 线程数量。设置为 0 时，使用的 CPU 线程数量被设置为默认值 1。

可选值：

• 要使用的线程数量，为整数。默认为 0，此时使用 1 个线程。

示例：

CUDA_BINARY_LOADER_THREAD_COUNT=4

5.2.4.4. CUDA_DEVICE_DEFAULT_STACK_SIZE_MAX

当此环境变量设置为1时，驱动程序会在对应的cuModuleLoad*调用期间，根据该模块中所有函数的最大需求，预先为每个线程分配足以满足最坏情况下需求的栈内存。默认情况下，CUDA 驱动程序按需分配每个线程的栈内存：当核函数启动所需的栈大于当前可用的栈时，驱动程序会在执行前扩充分配的内存。

可选值：

• 0或未设置：在核函数启动时按需扩充栈内存（默认）。

• 1：在模块加载时预先分配最大栈内存。

示例：

CUDA_DEVICE_DEFAULT_STACK_SIZE_MAX=1

5.2.5.1. CUDA_LOG_FILE

该环境变量指定一个位置，对于返回错误的受支持 CUDA API 调用，会在错误发生时将描述性错误日志消息打印到该位置。

例如，如果尝试使用无效的网格配置（如kernel<<<1, dim3(1,1,128)>>>(...)）启动核函数，该核函数将无法启动，且cudaGetLastError()将返回通用的invalid configuration argument错误。
如果设置了CUDA_LOG_FILE环境变量，用户就可以在日志中看到以下描述性错误消息：[CUDA][E] Block Dimensions (1,1,128) include one or more values that exceed the device limit of (1024,1024,64)，并轻松确定所指定的线程块 z 维度无效。有关更多详细信息，请参阅错误日志管理。

可选值：stdout、stderr或有效的文件路径（具有适当的访问权限）

示例：

CUDA_LOG_FILE=stdout
CUDA_LOG_FILE=/tmp/dbg_cuda_log