环境变量

注意

本节涉及影响 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_BOUNDSCHECK

如果设置为 0 或 1，则分别全局禁用或启用边界检查。如果未设置变量或设置为空字符串，则默认使用传递给给定函数的 jit() 装饰器的 boundscheck 标志。有关更多信息，请参阅 @jit 的文档。

请注意，由于 Numba 的限制，边界检查目前生成的异常消息与 NumPy 的不匹配。如果您设置 NUMBA_FULL_TRACEBACKS=1，则包含轴、索引和形状信息的完整异常消息将打印到终端。

调试

这些变量影响 JIT 函数编译期间打印的内容。

NUMBA_DEVELOPER_MODE: 如果设置为非零值，开发者模式将生成完整的追溯信息并禁用帮助说明。默认值为零。

NUMBA_FULL_TRACEBACKS: 如果设置为非零值，则在发生异常时启用完整追溯。默认为 NUMBA_DEVELOPER_MODE 设置的值。

NUMBA_SHOW_HELP: 如果设置为非零值，则显示获取帮助的资源。默认值为零。

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_SYS_MONITORING

控制 Numba 中对 Python sys.monitoring 功能的支持。默认禁用（设置为零）。启用（设置为非零值）后，允许使用 sys.monitoring 的性能分析工具与 Numba 代码协同工作。目前已使用 cProfile 进行测试，其他监控工具可能有效但无法保证。

仅适用于 Python 3.12 及更高版本。否则，它将不起作用。

NUMBA_ENABLE_PROFILING: 启用 LLVM 的 JIT 事件，以支持对 JIT 编译函数的性能分析。此选项在某些性能分析器下会自动启用。

NUMBA_TRACE: 如果设置为非零值，则跟踪某些函数调用（函数进入和退出事件，包括参数和返回值）。

NUMBA_CHROME_TRACE: 如果已定义，则启用 Chrome 跟踪，此变量指定 Chrome 跟踪 JSON 文件输出的文件路径。生成的文件可以使用基于 Chromium 的浏览器在 chrome://tracing/ 的性能分析器中打开。

警告

多进程应用程序不支持此功能。

NUMBA_DUMP_BYTECODE: 如果设置为非零值，则打印已编译函数的 Python 字节码。

NUMBA_DUMP_CFG: 如果设置为非零值，则打印已编译函数的控制流图信息。

NUMBA_DUMP_IR: 如果设置为非零值，则打印已编译函数的 Numba 中间表示。

NUMBA_DUMP_SSA: 如果设置为非零值，则打印转换为静态单赋值 (SSA) 形式后的 Numba 中间表示。

NUMBA_DEBUG_PRINT_AFTER

在声明的遍（或多遍）之后转储 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=True jit 装饰器选项相关的处理调试信息。

NUMBA_DEBUG_ARRAY_OPT_RUNTIME: 转储与 parallel=True jit 装饰器选项相关的运行时调度器调试信息。

NUMBA_DEBUG_ARRAY_OPT_STATS: 转储关于有多少运算符/调用转换为并行 for 循环以及有多少被融合的统计信息，这些信息与 parallel=True jit 装饰器选项相关。

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_JIT_COVERAGE: 设置为 1 以启用 JIT 编译器对已编译源代码行的覆盖数据报告。默认为 0（关闭）。

另请参阅

故障排除和提示和 Numba 架构。

编译选项

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: 启用块间剪枝，即钻石形模式，例如一个单入口单出口 CFG 子图，其中入口处有一个 incref，出口处有一个相应的 decref。
fanout: 启用块间剪枝，即扇出模式，例如一个单入口多出口 CFG 子图，其中入口处有一个 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_DEBUG_CACHE: 如果设置为非零值，则打印关于 JIT 编译缓存操作的信息。

NUMBA_CACHE_DIR

覆盖缓存目录的位置。如果已定义，这应该是一个有效的目录路径。

如果未定义，Numba 将按以下顺序选择缓存目录

树内缓存。将缓存放在相应源文件旁边，位于 __pycache__ 目录下，遵循 .pyc 文件的存储方式。
用户范围缓存。使用 Appdirs 包中的 appdirs.user_cache_dir 将缓存放在用户应用程序目录中。
IPython 缓存。将缓存放在 IPython 特定的应用程序目录中。存储在 IPython.paths.get_ipython_cache_dir() 返回的目录下 numba_cache 中进行。

另请参阅缓存共享文档和缓存清理文档

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 数组接口导入的对象提供的流上进行同步。此项默认为 1。如果设置为 0，则不进行同步，Numba 用户（以及其他 CUDA 库的用户）负责确保流同步的正确性。

NUMBA_CUDA_LOG_LEVEL: 用于调试目的。如果没有配置其他日志记录，此变量的值即为 CUDA API 调用的日志记录级别。默认值为 CRITICAL - 要在标准错误中跟踪所有 API 调用，请将其设置为 DEBUG。

NUMBA_CUDA_LOG_API_ARGS: 默认情况下，CUDA API 调用日志仅提供被调用函数的名称。将此变量设置为 1 还会将驱动程序 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 绑定文档中的默认流章节。

NUMBA_CUDA_LOW_OCCUPANCY_WARNINGS

如果网格大小相对于流式多处理器 (SM) 的数量太小，则启用警告。此选项默认开启（默认值为 1）。

检查的启发式规则是 gridsize < 2 * (number of SMs) 是否成立。注意：没有警告并不意味着网格大小相对于 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。

默认值： 运行时确定的系统 CPU 核心数。可以通过 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 - 一个简单的内置工作共享任务调度器。

NUMBA_THREADING_LAYER_PRIORITY: 此环境变量控制 CPU 并行目标（@vectorize(target='parallel')、@guvectorize(target='parallel') 和 @njit(parallel=True)）并发执行所使用的库的优先级顺序。变量类型是字符串，默认值为 tbb omp workqueue，优先级根据字符串从左到右的位置决定，最左侧的优先级最高。有效值是这三个选项的任意排列（有关这些的更多信息，请参阅线程层文档）。