环境变量
备注
本节涉及影响 Numba 运行时的环境变量，关于编译时环境变量，请参见 构建时环境变量和可选组件的配置。
Numba 允许通过使用环境变量来改变其行为。除非另有说明，这些变量具有整数值，并且默认值为零。
为了方便，Numba 也支持使用配置文件来持久化配置设置。注意：要使用此功能，必须安装 pyyaml。
配置文件必须命名为 .numba_config.yaml ，并且存在于调用 Python 解释器的目录中。如果存在配置文件，则在搜索环境变量之前会读取该文件以获取配置设置。这意味着环境变量设置将覆盖从配置文件中获取的设置（配置文件用于设置永久偏好，而环境变量用于临时偏好）。
配置文件的格式是一个 YAML 格式的字典，它将下面的环境变量（不带 NUMBA_ 前缀）映射到所需的值。例如，要永久开启开发者模式（NUMBA_DEVELOPER_MODE 环境变量）和控制流图打印（NUMBA_DUMP_CFG 环境变量），创建一个包含以下内容的配置文件:
developer_mode: 1
dump_cfg: 1
这在基于终端背景颜色使用一组颜色方案的情况下特别有用。例如，如果终端背景颜色是黑色，dark_bg 颜色方案将非常适合，并且可以通过添加以下内容来永久设置：：
color_scheme: dark_bg
Jit 标志
这些变量全局覆盖 jit() 装饰器的标志。
调试
这些变量影响在编译 即时函数 期间打印输出的内容。
- NUMBA_DEVELOPER_MODE
如果设置为非零值，开发者模式将生成完整的回溯信息并禁用帮助指令。默认值为零。
- NUMBA_FULL_TRACEBACKS
如果设置为非零值，则在发生异常时启用完整的回溯。默认值由 NUMBA_DEVELOPER_MODE 设置。
- NUMBA_SHOW_HELP
如果设置为非零值，显示获取帮助的资源。默认值为零。
- NUMBA_CAPTURED_ERRORS
改变Numba在编译期间捕获和处理不继承自``numba.core.errors.NumbaError``的异常（例如标准Python异常）的方式。这不会影响运行时的异常处理。有效值为：
"old_style"(默认): 这是在 Numba 版本 <= 0.54.x 中存在的异常处理行为。Numba 将捕获并包装编译中发生的所有错误，并且根据编译阶段，它们很可能会作为TypingError或LoweringError消息的一部分具体化。"new_style"这将把任何不继承自numba.core.errors.NumbaError的异常，并且在编译期间引发的异常视为“硬错误”，即异常将传播并且编译将停止。这种新风格的目的是区分有意引发的异常和由于错误而发生的异常。例如，如果在@overload函数的类型推断中发生AttributeError，在这种新行为下，假设这是实现中的错误，并且由于此异常编译将停止。这种行为最终将成为默认行为。
- NUMBA_DISABLE_ERROR_MESSAGE_HIGHLIGHTING
如果设置为非零，错误消息高亮将被禁用。这在CI系统上运行测试套件时很有用。
- NUMBA_COLOR_SCHEME
更改错误报告中使用的配色方案（需要安装
colorama包才能工作）。有效值为：no_color没有添加颜色，只是粗体字重。dark_bg适用于深色背景的终端。light_bg适用于浅色背景的终端。blue_bg适用于蓝色背景的终端。jupyter_nb适用于在 Jupyter Notebooks 中使用。
默认值:
no_color。值的类型是string。
- NUMBA_HIGHLIGHT_DUMPS
如果设置为非零且已安装
pygments，则会对 Numba IR、LLVM IR 和汇编转储应用语法高亮。默认值为零。
- NUMBA_DISABLE_PERFORMANCE_WARNINGS
如果设置为非零值，性能警告的发送将被禁用。默认值为零。
- NUMBA_DEBUG
如果设置为非零值，在函数编译期间打印所有可能的调试信息。可以使用下面的其他变量获得更细粒度的控制。
- NUMBA_DEBUG_FRONTEND
如果设置为非零值，则在编译器前端操作期间打印调试信息，直至包括生成 Numba 中间表示。
- NUMBA_DEBUG_NRT
如果设置为非零值，则在运行时打印有关 Numba 运行时 (NRT) 引用计数操作的调试信息。如果设置为非零值，这还会在分配所有 NRT 分配区域时填充可识别的“标记”字节模式，分配时为
0xCB，释放时为0xDE，以帮助调试内存泄漏。
- NUMBA_NRT_STATS
如果设置为非零，启用 Numba 运行时 (NRT) 统计计数器。这些计数器在导入 Numba 时在整个进程中启用，并且是原子的。
- NUMBA_DEBUGINFO
如果设置为非零值，通过在
jit中设置debug选项的默认值，为整个应用程序启用调试。请注意，启用调试信息会显著增加每个编译函数的内存消耗。默认值等于 NUMBA_ENABLE_PROFILING 的值。
- NUMBA_EXTEND_VARIABLE_LIFETIMES
如果设置为非零值，将变量的生命周期延长到其生命周期结束的块的末尾。这在结合
NUMBA_DEBUGINFO时特别有用，因为它有助于值的内省。默认值为零。
- NUMBA_GDB_BINARY
设置用于 Numba 的
gdb支持的gdb二进制文件。这有两种形式：1) 二进制文件的路径和全名，以明确表达使用哪个二进制文件 2) 仅二进制文件的名称，将使用标准路径解析规则搜索当前路径。例如：/path/from/root/to/binary/name_of_gdb_binary或custom_gdb_binary_name。这是为了允许使用非默认位置和非默认名称的gdb。默认值为gdb。
- NUMBA_DEBUG_TYPEINFER
如果设置为非零值，打印出关于类型推断的调试信息。
- NUMBA_ENABLE_PROFILING
启用LLVM的JIT事件以支持对JIT函数的分析。在某些分析器下，此选项会自动启用。
- NUMBA_TRACE
如果设置为非零值，则跟踪某些函数调用（包括函数入口和出口事件，以及参数和返回值）。
- NUMBA_CHROME_TRACE
如果定义了，chrome 跟踪将被启用，并且这个变量指定了 chrome 跟踪 json 文件输出的文件路径。生成的文件可以通过基于 Chromium 的浏览器使用 chrome://tracing/ 上的配置查看器打开。
警告
此功能在多进程应用程序中不受支持。
- NUMBA_DUMP_CFG
如果设置为非零值，打印出编译函数的控制流图的相关信息。
- NUMBA_DUMP_IR
如果设置为非零，则打印出编译函数的Numba中间表示。
- NUMBA_DUMP_SSA
如果设置为非零值，在编译函数转换为静态单赋值（SSA）形式后，打印出Numba中间表示（IR）。
- NUMBA_DEBUG_PRINT_AFTER
在声明的传递（pass）后转储Numba IR。这对于调试由给定传递所做的IR更改非常有用。接受的值是：
任何传递名称（由类上的
.name()方法给出）以逗号分隔的多个传递名称，例如
"foo_pass,bar_pass"令牌
"all"，将在所有步骤之后打印。
默认值为
"none"，以防止输出。
- NUMBA_DUMP_ANNOTATION
如果设置为非零值，打印编译函数的类型注解。
- NUMBA_DUMP_LLVM
转储编译函数的未优化 LLVM 汇编源代码。未优化的代码通常非常冗长；因此，建议使用
NUMBA_DUMP_OPTIMIZED。
- NUMBA_DUMP_FUNC_OPT
在 LLVM “函数优化” 阶段之后，但在 “模块优化” 阶段之前，转储 LLVM 汇编源代码。这在开发 Numba 本身时非常有用，否则请使用
NUMBA_DUMP_OPTIMIZED。
- NUMBA_DUMP_OPTIMIZED
在所有优化过程后，转储编译函数的LLVM汇编源代码。输出包括原始函数及其CPython兼容的包装器（其名称以``wrapper.``开头）。请注意，函数通常也会被内联在包装器内部。
- NUMBA_DEBUG_ARRAY_OPT
转储与
parallel=Truejit 装饰器选项相关的处理调试信息。
- NUMBA_DEBUG_ARRAY_OPT_RUNTIME
转储与
parallel=Truejit 装饰器选项关联的运行时调度程序相关的调试信息。
- NUMBA_DEBUG_ARRAY_OPT_STATS
转储关于有多少操作符/调用被转换为并行for循环以及有多少被融合在一起的统计信息，这些信息与
parallel=Truejit装饰器选项相关联。
- NUMBA_PARALLEL_DIAGNOSTICS
如果设置为1到4之间的整数值（包括1和4），关于Numba进行的并行变换的诊断信息将被写入STDOUT。设置的值越高，生成的信息越详细。
- NUMBA_DUMP_ASSEMBLY
转储编译函数的本地汇编代码。
- NUMBA_LLVM_PASS_TIMINGS
设置为
1以在 LLVM 中启用通过时间的记录；例如NUMBA_LLVM_PASS_TIMINGS=1。参见 关于 LLVM 时间安排的注意事项。默认值:
0(关闭)
编译选项
- NUMBA_OPT
优化级别；通常这个选项直接传递给LLVM。它可以取值
0、1、2或3，这些值大致对应于许多命令行编译工具中的-O{value}标志。还支持值max，这是Numba特有的，它的效果是在引用计数操作修剪发生的阶段前后都以优化级别3运行。在某些情况下，这可能会提高性能，在其他情况下，它可能会阻碍性能，编译时间也是如此。这个选项的存在是为了让用户有机会选择适合他们应用的值。默认值: 3
- NUMBA_LOOP_VECTORIZE
如果设置为非零，启用 LLVM 循环向量化。
默认值: 1
- NUMBA_SLP_VECTORIZE
如果设置为非零值，启用 LLVM 超字级并行化矢量化。请注意，使用此功能偶尔会导致 LLVM 产生错误编译，因此默认情况下它是关闭的。
默认值: 0
- NUMBA_ENABLE_AVX
如果设置为非零，则在LLVM中启用AVX优化。默认情况下，在Sandy Bridge和Ivy Bridge架构上禁用此功能，因为在这些平台上有时会导致代码运行速度变慢。
- NUMBA_DISABLE_INTEL_SVML
如果设置为非零且Intel SVML可用，SVML的使用将被禁用。
- NUMBA_DISABLE_JIT
完全禁用JIT编译。
jit()装饰器的行为就像它不执行任何操作一样，并且装饰函数的调用会调用原始的Python函数而不是编译版本。如果你想在代码上运行Python调试器，这可能很有用。
- NUMBA_CPU_NAME
- NUMBA_CPU_FEATURES
覆盖 CPU 和 CPU 特性检测。通过设置
NUMBA_CPU_NAME=generic，将选择一个通用的 CPU 模型用于 CPU 架构，并且特性列表 (NUMBA_CPU_FEATURES) 默认为空。CPU 特性必须以+feature1,-feature2的格式列出，其中+表示启用，-表示禁用。例如，+sse,+sse2,-avx,-avx2启用了 SSE 和 SSE2，并禁用了 AVX 和 AVX2。这些设置传递给 LLVM 以配置编译目标。要获取可用选项的列表，请使用 LLVM 的
llc命令行工具，例如:llc -march=x86 -mattr=help
小技巧
要强制所有缓存功能（
@jit(cache=True)）生成可移植代码（在相同架构和操作系统内可移植），只需设置NUMBA_CPU_NAME=generic。
- NUMBA_FUNCTION_CACHE_SIZE
覆盖用于在内存中保留最近反序列化函数的函数缓存大小。在 Dask 这样的系统中，函数被多次反序列化是很常见的。Numba 会缓存函数，只要解释器中的某个地方有引用。这个缓存大小变量控制了多少不再被引用的函数也会被保留，以防它们在未来出现。这个实现的并不是真正的 LRU，但缓存的大尺寸应该足以应对大多数情况。
注意：这与编译缓存无关。
默认值: 128
- NUMBA_LLVM_REFPRUNE_PASS
开启 LLVM 传递级别的引用计数修剪传递，并禁用 Numba 中的基于正则表达式的实现。
默认值: 1 (开启)
- NUMBA_LLVM_REFPRUNE_FLAGS
当
NUMBA_LLVM_REFPRUNE_PASS开启时，这允许配置引用计数修剪LLVM传递中的子传递。有效值是以下任意组合，用 , 分隔（不区分大小写）：
all: 启用所有子通道。per_bb: 启用每基本块级别的剪枝，这与旧的基于正则表达式的实现相同。diamond: 启用跨基本块的剪枝，这是一种菱形模式，即具有入口处incref和出口处相应decref的单入口单出口CFG子图。fanout: 启用具有扇出模式的跨基本块剪枝，即一个单入口多出口的控制流图子图，其中入口有一个incref，每个出口有一个对应的decref。fanout_raise: 与fanout相同，但允许子图的出口节点引发异常，并且不需要相应的 decref。
例如，
all与per_bb, diamond, fanout, fanout_raise相同默认值: “all”
- NUMBA_USE_LLVMLITE_MEMORY_MANAGER
是否启用 llvmlite 的内置内存管理器。默认情况下，在 64 位 ARM 平台上启用它（Apple Silicon 上的 macOS 和 AArch64 上的 Linux），在这些平台上需要它来确保 ABI 合规性，特别是符合大型代码模型中 GOT 和文本段放置的要求。
此环境变量可用于覆盖默认设置并强制启用 (
1) 或禁用 (0)。通常不需要这样做，但为了调试和潜在的解决方法，提供了此选项。默认值: 无 (使用系统的默认值)
- NUMBA_USE_RVSDG_FRONTEND
开启实验性的 RVSDG 前端。它依赖于
numba-rvsdg包，并且仅部分支持 Python 3.11。当 RVSDG 前端完全替代旧前端时，此选项将被移除。默认值: 0 (关闭)
缓存选项
编译缓存的选项。
GPU 支持
- NUMBA_DISABLE_CUDA
如果设置为非零，禁用CUDA支持。
- NUMBA_FORCE_CUDA_CC
如果设置，强制 CUDA 计算能力为给定的版本（类型为
major.minor的字符串），无论连接的设备如何。
- NUMBA_CUDA_DEFAULT_PTX_CC
使用
cuda.compile_ptx编译为 PTX 时，默认的目标计算能力（类型为major.minor的字符串）。默认值为 5.0，这是当前支持的最新版本 CUDA 工具包（目前为 12.4）中最低的非弃用计算能力。
- NUMBA_ENABLE_CUDASIM
如果设置，不要为GPU编译和执行代码，而是使用CUDA模拟器。用于调试目的。
- NUMBA_CUDA_ARRAY_INTERFACE_SYNC
是否在通过 CUDA Array Interface 导入的对象提供的流上进行同步。默认为 1。如果设置为 0，则不进行同步，Numba（和其他 CUDA 库）的用户负责确保在流上的同步正确性。
- NUMBA_CUDA_LOG_LEVEL
用于调试目的。如果没有配置其他日志记录，此变量的值是CUDA API调用的日志级别。默认值是
CRITICAL- 要在标准错误上跟踪所有API调用，请将其设置为DEBUG。
- NUMBA_CUDA_LOG_API_ARGS
默认情况下，CUDA API 调用日志仅提供被调用函数的名称。将此变量设置为 1 还会在日志中包含 Driver API 调用参数的值。
- NUMBA_CUDA_DRIVER
CUDA 驱动库所在的目录路径。通常情况下，这不需要设置，因为 Numba 可以在标准位置找到驱动。然而，如果驱动位于非标准位置，可以使用此变量。
- NUMBA_CUDA_LOG_SIZE
CUDA 驱动 API 操作生成的日志的缓冲区大小。默认值为 1024，通常不需要修改 - 但是，如果 API 调用中的错误产生了大量输出并且似乎被截断（例如，可能是由于多个长函数名），那么可以使用此变量来增加缓冲区大小并查看完整的错误消息。
- NUMBA_CUDA_VERBOSE_JIT_LOG
CUDA 驱动是否应生成详细的日志消息。默认为 1，表示启用详细消息。在正常情况下不应修改此设置。
- NUMBA_CUDA_PER_THREAD_DEFAULT_STREAM
当设置为1时，默认流是每个线程的默认流。当设置为0时，默认流是传统的默认流。默认值为0，表示传统的默认流。有关传统和每个线程默认流的解释，请参见 流同步行为 。
此变量仅在使用 Numba 的内部 CUDA 绑定时有效果；当使用 NVIDIA 绑定时，请使用环境变量
CUDA_PYTHON_CUDA_PER_THREAD_DEFAULT_STREAM代替。参见
NVIDIA Bindings 文档中的 默认流部分。
- NUMBA_CUDA_LOW_OCCUPANCY_WARNINGS
如果网格大小相对于流多处理器（SM）的数量太小，则启用警告。此选项默认开启（默认值为1）。
检查的启发式方法是
gridsize < 2 * (SM 数量)。注意：没有警告并不意味着 gridsize 相对于 SM 数量是好的。禁用此警告将减少 CUDA API 调用（在 JIT 编译期间），因为启发式方法需要在当前上下文中检查设备上可用的 SM 数量。
- NUMBA_CUDA_WARN_ON_IMPLICIT_COPY
如果内核在启动时使用主机内存，这将强制在设备和主机之间进行复制，启用警告。此选项默认开启（默认值为1）。
- NUMBA_CUDA_USE_NVIDIA_BINDING
当设置为1时，Numba将尝试使用 NVIDIA CUDA Python绑定 来调用驱动程序API，而不是使用其自己的ctypes绑定。默认值为0（关闭），因为NVIDIA绑定目前缺少对每个线程默认流和分析器API的支持。
- NUMBA_CUDA_INCLUDE_PATH
CUDA 包含文件的位置。这在将 CUDA C/C++ 源代码链接到 Python 内核时使用，并且需要正确设置以使 CUDA 包含文件对链接的 C/C++ 源代码可用。在 Linux 上，它默认为
/usr/local/cuda/include。在 Windows 上，默认值为$env:CUDA_PATH\include。
线程控制
- NUMBA_NUM_THREADS
如果设置，并行CPU目标的线程池中的线程数将采用此值。必须大于零。此值与
OMP_NUM_THREADS和MKL_NUM_THREADS无关。Default value: The number of CPU cores on the system as determined at run time. This can be accessed via
numba.config.NUMBA_DEFAULT_NUM_THREADS.另请参阅 设置线程数 部分，了解如何在运行时设置线程数。
- NUMBA_THREADING_LAYER
此环境变量控制用于CPU并行目标（
@vectorize(target='parallel')、@guvectorize(target='parallel')和@njit(parallel=True)）的并发执行库。变量类型为字符串，默认值为default，它将根据运行时可用的内容选择一个线程层。有效值为（有关这些值的更多信息，请参阅 线程层文档）：default- 根据当前运行时可用的内容选择一个线程层。safe- 选择一个既支持 fork 又线程安全的线程层（需要 TBB 包）。forksafe- 选择一个支持 fork 安全的线程层。threadsafe- 选择一个线程安全的线程层。tbb- 由 Intel TBB 支持的线程层。omp- 一个由 OpenMP 支持的线程层。workqueue- 一个简单的内置任务调度器，用于工作共享。