1. 命令行与环境

CPython 解释器会扫描命令行和环境以获取各种设置。

CPython 实现细节: 其他实现的命令行方案可能有所不同。有关更多资源，请参阅 其他实现。

1.1. 命令行

调用 Python 时，可以指定以下任何选项

python [-bBdEhiIOPqRsSuvVWx?] [-c command | -m module-name | script | - ] [args]

当然，最常见的用例是简单地调用一个脚本

python myscript.py

1.1.1. 接口选项

解释器接口类似于 UNIX shell，但提供了一些额外的调用方法

  • 当标准输入连接到 tty 设备时调用，它会提示输入命令并执行它们，直到读取到 EOF（文件结束符，在 UNIX 上可以使用 Ctrl-D 生成，在 Windows 上可以使用 Ctrl-Z, Enter 生成）。有关交互模式的更多信息，请参阅 交互模式。

  • 当使用文件名参数或将文件作为标准输入调用时，它会从该文件中读取并执行脚本。

  • 当使用目录名参数调用时，它会从该目录中读取并执行一个适当命名的脚本。

  • 当使用 -c command 调用时，它会执行作为 command 给出的 Python 语句。此处 command 可以包含由换行符分隔的多个语句。前导空格在 Python 语句中很重要！

  • 当使用 -m module-name 调用时，会在 Python 模块路径中找到给定的模块并将其作为脚本执行。

在非交互模式下，整个输入在执行之前都会被解析。

一个接口选项会终止解释器消耗的选项列表，所有后续参数都将进入 sys.argv – 请注意，第一个元素，下标零 (sys.argv[0])，是一个反映程序源的字符串。

-c <command>

执行 command 中的 Python 代码。command 可以是一个或多个由换行符分隔的语句，并且像普通模块代码一样具有重要的前导空格。

如果给出此选项，sys.argv 的第一个元素将是 "-c"，并且当前目录将添加到 sys.path 的开头（允许在该目录中的模块作为顶级模块导入）。

引发一个 审计事件 cpython.run_command，参数为 command。

3.14 版本中的变化: command 在执行前会自动取消缩进。

-m <module-name>

在 sys.path 中搜索指定模块，并将其内容作为 __main__ 模块执行。

由于参数是 模块 名称，因此您不能给出文件扩展名（.py）。模块名称应该是一个有效的绝对 Python 模块名称，但实现可能并不总是强制执行此操作（例如，它可能允许您使用包含连字符的名称）。

包名称（包括命名空间包）也允许使用。当提供包名称而不是普通模块时，解释器将执行 <pkg>.__main__ 作为主模块。此行为与将目录和 zip 文件作为脚本参数传递给解释器的处理方式故意相似。

备注

此选项不能与内置模块和用 C 编写的扩展模块一起使用，因为它们没有 Python 模块文件。但是，它仍然可以用于预编译模块，即使原始源文件不可用。

如果给出此选项，sys.argv 的第一个元素将是模块文件的完整路径（在定位模块文件时，第一个元素将设置为 "-m"）。与 -c 选项一样，当前目录将添加到 sys.path 的开头。

-I 选项可用于在隔离模式下运行脚本，其中 sys.path 既不包含当前目录也不包含用户的 site-packages 目录。所有 PYTHON* 环境变量也被忽略。

许多标准库模块包含在作为脚本执行时调用的代码。一个例子是 timeit 模块

python -m timeit -s "setup here" "benchmarked code here"
python -m timeit -h # for details

引发一个 审计事件 cpython.run_module，参数为 module-name。

参见

runpy.run_module()

等效功能直接可用于 Python 代码

PEP 338 – 将模块作为脚本执行

3.1 版本中的变化: 提供包名以运行 __main__ 子模块。

3.4 版本中的变化: 命名空间包也受支持

-

从标准输入 (sys.stdin) 读取命令。如果标准输入是终端，则隐含 -i。

如果给出此选项，sys.argv 的第一个元素将是 "-"，并且当前目录将添加到 sys.path 的开头。

引发一个 审计事件 cpython.run_stdin，不带参数。

<script>

执行 script 中包含的 Python 代码，该 script 必须是一个文件系统路径（绝对或相对），指向一个 Python 文件、一个包含 __main__.py 文件的目录，或一个包含 __main__.py 文件的 zip 文件。

如果给出此选项，sys.argv 的第一个元素将是命令行中给出的脚本名称。

如果脚本名称直接指向一个 Python 文件，则包含该文件的目录将添加到 sys.path 的开头，并且该文件将作为 __main__ 模块执行。

如果脚本名称指向目录或 zip 文件，则脚本名称将添加到 sys.path 的开头，并且该位置的 __main__.py 文件将作为 __main__ 模块执行。

-I 选项可用于在隔离模式下运行脚本，其中 sys.path 既不包含脚本目录也不包含用户的 site-packages 目录。所有 PYTHON* 环境变量也被忽略。

引发一个 审计事件 cpython.run_file，参数为 filename。

参见

runpy.run_path()

等效功能直接可用于 Python 代码

如果没有给出接口选项，则隐含 -i，sys.argv[0] 是一个空字符串 ("")，并且当前目录将添加到 sys.path 的开头。此外，如果您的平台支持，还会自动启用 Tab 补全和历史编辑（请参阅 Readline 配置）。

参见

调用解释器

3.4 版本中的变化: 自动启用 Tab 补全和历史编辑。

1.1.2. 通用选项

-?
-h
--help

打印所有命令行选项和相应环境变量的简短描述并退出。

--help-env

打印 Python 特有环境变量的简短描述并退出。

在 3.11 版本中新增。

--help-xoptions

打印实现特定的 -X 选项的描述并退出。

在 3.11 版本中新增。

--help-all

打印完整的用法信息并退出。

在 3.11 版本中新增。

-V
--version

打印 Python 版本号并退出。示例输出可能如下

Python 3.8.0b2+

当给定两次时，打印更多关于构建的信息，例如

Python 3.8.0b2+ (3.8:0c076caaa8, Apr 20 2019, 21:55:00)
[GCC 6.2.0 20161005]

3.6 版本新增: -VV 选项。

1.1.3. 其他选项

-b

当将 bytes 或 bytearray 转换为 str 而未指定编码，或比较 bytes 或 bytearray 与 str，或比较 bytes 与 int 时，发出警告。当此选项给定两次时（-bb），则发出错误。

3.5 版本中的变化: 也影响 bytes 与 int 的比较。

-B

如果给定，Python 在导入源模块时不会尝试写入 .pyc 文件。另请参阅 PYTHONDONTWRITEBYTECODE。

--check-hash-based-pycs default|always|never

控制基于哈希的 .pyc 文件的验证行为。参阅 缓存字节码失效。当设置为 default 时，已检查和未检查的基于哈希的字节码缓存文件将根据其默认语义进行验证。当设置为 always 时，所有基于哈希的 .pyc 文件，无论是否已检查，都将根据其对应的源文件进行验证。当设置为 never 时，基于哈希的 .pyc 文件将不根据其对应的源文件进行验证。

基于时间戳的 .pyc 文件的语义不受此选项影响。

-d

开启解析器调试输出（仅限专家）。另请参阅 PYTHONDEBUG 环境变量。

此选项需要 Python 的调试构建，否则将被忽略。

-E

忽略所有可能已设置的 PYTHON* 环境变量，例如 PYTHONPATH 和 PYTHONHOME。

另请参阅 -P 和 -I (isolated) 选项。

-i

执行后进入交互模式。

在以下任何情况下，使用 -i 选项都将进入交互模式

  • 当脚本作为第一个参数传递时

  • 当使用 -c 选项时

  • 当使用 -m 选项时

即使 sys.stdin 似乎不是终端，交互模式也会启动。PYTHONSTARTUP 文件不会被读取。

当脚本引发异常时，这对于检查全局变量或堆栈跟踪很有用。另请参阅 PYTHONINSPECT。

-I

在隔离模式下运行 Python。这也隐含了 -E、-P 和 -s 选项。

在隔离模式下，sys.path 既不包含脚本目录，也不包含用户的 site-packages 目录。所有 PYTHON* 环境变量也被忽略。可能会施加进一步的限制以防止用户注入恶意代码。

在 3.4 版本加入。

-O

删除断言语句和所有依赖于 __debug__ 值的代码。通过在 .pyc 扩展名之前添加 .opt-1 来增加编译（字节码）文件的文件名（参阅 PEP 488）。另请参阅 PYTHONOPTIMIZE。

3.5 版本中的变化: 根据 PEP 488 修改 .pyc 文件名。

-OO

执行 -O，并丢弃文档字符串。通过在 .pyc 扩展名之前添加 .opt-2 来增加编译（字节码）文件的文件名（参阅 PEP 488）。

3.5 版本中的变化: 根据 PEP 488 修改 .pyc 文件名。

-P

不要将可能不安全的路径添加到 sys.path

  • python -m module 命令行: 不要预置当前工作目录。

  • python script.py 命令行: 不要预置脚本的目录。如果它是符号链接，解析符号链接。

  • python -c code 和 python (REPL) 命令行: 不要预置空字符串，这意味着当前工作目录。

另请参阅 PYTHONSAFEPATH 环境变量，以及 -E 和 -I（隔离）选项。

在 3.11 版本中新增。

-q

即使在交互模式下，也不显示版权和版本信息。

在 3.2 版本加入。

-R

启用哈希随机化。此选项仅在 PYTHONHASHSEED 环境变量设置为 random 以外的任何值时才有效，因为哈希随机化默认是启用的。

在以前的 Python 版本中，此选项会启用哈希随机化，因此字符串和字节对象的 __hash__() 值会以不可预测的随机值“加盐”。尽管它们在单个 Python 进程中保持不变，但在重复调用 Python 时它们是不可预测的。

哈希随机化旨在提供保护，以防止因精心选择的输入而导致的拒绝服务，这些输入利用了字典构建的最坏情况性能，即 O(n2) 复杂度。有关详细信息，请参阅 http://ocert.org/advisories/ocert-2011-003.html。

PYTHONHASHSEED 允许您为哈希种子密钥设置固定值。

在 3.2.3 版中新增。

3.7 版本中的变化: 该选项不再被忽略。

-s

不要将 用户 site-packages 目录 添加到 sys.path。

另请参阅 PYTHONNOUSERSITE。

参见

PEP 370 – 每个用户的 site-packages 目录

-S

禁用模块 site 的导入及其对 sys.path 造成的 site 相关操作。如果 site 稍后被显式导入，也禁用这些操作（如果您希望它们被触发，请调用 site.main()）。

-u

强制标准输出和标准错误流不缓冲。此选项对标准输入流无效。

另请参阅 PYTHONUNBUFFERED。

3.7 版本中的变化: 标准输出和标准错误流的文本层现在不缓冲。

-v

每次初始化模块时打印一条消息，显示其加载位置（文件名或内置模块）。如果给定两次（-vv），则在搜索模块时，为每个被检查的文件打印一条消息。还提供退出时模块清理的信息。

3.10 版本中的变化: site 模块报告正在处理的 site 特定路径和 .pth 文件。

另请参阅 PYTHONVERBOSE。

-W arg

警告控制。Python 的警告机制默认会将警告消息打印到 sys.stderr。

最简单的设置是无条件地对进程发出的所有警告（即使是默认情况下被忽略的警告）应用特定的操作

-Wdefault  # Warn once per call location
-Werror    # Convert to exceptions
-Walways   # Warn every time
-Wall      # Same as -Walways
-Wmodule   # Warn once per calling module
-Wonce     # Warn once per Python process
-Wignore   # Never warn

操作名称可以根据需要缩写，解释器会将其解析为适当的操作名称。例如，-Wi 与 -Wignore 相同。

参数的完整形式是

action:message:category:module:lineno

空字段匹配所有值；可以省略尾随的空字段。例如 -W ignore::DeprecationWarning 会忽略所有 DeprecationWarning 警告。

action 字段如上所述，但仅适用于与其余字段匹配的警告。

message 字段必须匹配完整的警告消息；此匹配不区分大小写。

category 字段匹配警告类别（例如：DeprecationWarning）。这必须是一个类名；匹配测试消息的实际警告类别是否是指定警告类别的子类。

module 字段匹配（完全限定的）模块名称；此匹配区分大小写。

lineno 字段匹配行号，其中零匹配所有行号，因此等同于省略行号。

可以给出多个 -W 选项；当一个警告与多个选项匹配时，执行最后一个匹配选项的操作。无效的 -W 选项将被忽略（但是，当发出第一个警告时，会打印有关无效选项的警告消息）。

警告也可以使用 PYTHONWARNINGS 环境变量和 Python 程序内的 warnings 模块来控制。例如，warnings.filterwarnings() 函数可用于对警告消息使用正则表达式。

有关详细信息，请参阅 警告过滤器 和 描述警告过滤器。

-x

跳过源的第一行，允许使用非 Unix 形式的 #!cmd。这仅用于 DOS 特定的技巧。

-X

保留用于各种特定于实现的选项。CPython 目前定义了以下可能的值

  • -X faulthandler 用于启用 faulthandler。另请参阅 PYTHONFAULTHANDLER。

    在 3.3 版本加入。

  • -X showrefcount 在程序结束或交互式解释器中的每个语句之后，输出总引用计数和使用的内存块数量。这仅适用于 调试版本。

    在 3.4 版本加入。

  • -X tracemalloc 使用 tracemalloc 模块开始跟踪 Python 内存分配。默认情况下，回溯中只存储最新帧的跟踪。使用 -X tracemalloc=NFRAME 开始跟踪，回溯限制为 NFRAME 帧。有关更多信息，请参阅 tracemalloc.start() 和 PYTHONTRACEMALLOC。

    在 3.4 版本加入。

  • -X int_max_str_digits 配置 整数字符串转换长度限制。另请参阅 PYTHONINTMAXSTRDIGITS。

    在 3.11 版本中新增。

  • -X importtime 用于显示每次导入所需的时间。它显示模块名称、累积时间（包括嵌套导入）和自身时间（不包括嵌套导入）。请注意，其输出在多线程应用程序中可能会中断。典型用法是 python -X importtime -c 'import asyncio'。

    -X importtime=2 启用额外输出，指示导入的模块何时已加载。在这种情况下，字符串 cached 将在两个时间列中打印。

    另请参阅 PYTHONPROFILEIMPORTTIME。

    在 3.7 版本加入。

    3.14 版本中的变化: 增加了 -X importtime=2 以跟踪已加载模块的导入，并将 1 和 2 之外的值保留供将来使用。

  • -X dev: 启用 Python 开发模式，引入默认情况下过于昂贵的额外运行时检查。另请参阅 PYTHONDEVMODE。

    在 3.7 版本加入。

  • -X utf8 启用 Python UTF-8 模式。-X utf8=0 明确禁用 Python UTF-8 模式（即使它原本会自动激活）。另请参阅 PYTHONUTF8。

    在 3.7 版本加入。

  • -X pycache_prefix=PATH 允许将 .pyc 文件写入以给定目录为根的并行树，而不是代码树。另请参阅 PYTHONPYCACHEPREFIX。

    在 3.8 版本加入。

  • -X warn_default_encoding 在打开文件时使用特定于区域设置的默认编码时发出 EncodingWarning。另请参阅 PYTHONWARNDEFAULTENCODING。

    在 3.10 版本加入。

  • -X no_debug_ranges 禁用在代码对象中包含将额外位置信息（结束行、开始列偏移量和结束列偏移量）映射到每个指令的表。这在需要更小的代码对象和 pyc 文件以及在解释器显示回溯时抑制额外的视觉位置指示符时很有用。另请参阅 PYTHONNODEBUGRANGES。

    在 3.11 版本中新增。

  • -X frozen_modules 决定导入机制是否忽略冻结模块。值为 on 表示它们被导入，off 表示它们被忽略。如果这是一个已安装的 Python（正常情况），则默认值为 on。如果它正在开发中（从源代码树运行），则默认值为 off。请注意，importlib_bootstrap 和 importlib_bootstrap_external 冻结模块始终使用，即使此标志设置为 off。另请参阅 PYTHON_FROZEN_MODULES。

    在 3.11 版本中新增。

  • -X perf 启用对 Linux perf 分析器的支持。提供此选项后，perf 分析器将能够报告 Python 调用。此选项仅在某些平台上可用，如果当前系统不支持，则不起作用。默认值为“off”。另请参阅 PYTHONPERFSUPPORT 和 Python 对 Linux perf 分析器的支持。

    3.12 新版功能.

  • -X perf_jit 启用对带有 DWARF 支持的 Linux perf 分析器的支持。提供此选项后，perf 分析器将能够使用 DWARF 信息报告 Python 调用。此选项仅在某些平台上可用，如果当前系统不支持，则不起作用。默认值为“off”。另请参阅 PYTHON_PERF_JIT_SUPPORT 和 Python 对 Linux perf 分析器的支持。

    在 3.13 版本加入。

  • -X disable_remote_debug 禁用 PEP 768 中描述的远程调试支持。这包括在另一个进程中调度代码执行的功能和在当前进程中接收代码执行的功能。

    此选项仅在某些平台上可用，如果当前系统不支持，则不起作用。另请参阅 PYTHON_DISABLE_REMOTE_DEBUG 和 PEP 768。

    在 3.14 版本加入。

  • -X cpu_count=n 覆盖 os.cpu_count()、os.process_cpu_count() 和 multiprocessing.cpu_count()。n 必须大于或等于 1。此选项可能对需要限制容器系统 CPU 资源的用户有用。另请参阅 PYTHON_CPU_COUNT。如果 n 是 default，则不覆盖任何内容。

    在 3.13 版本加入。

  • -X presite=package.module 指定一个模块，该模块应在 site 模块执行之前和 __main__ 模块存在之前导入。因此，导入的模块不是 __main__。这可用于在 Python 初始化早期执行代码。Python 需要 以调试模式构建 才能存在此选项。另请参阅 PYTHON_PRESITE。

    在 3.13 版本加入。

  • -X gil=0,1 分别强制禁用或启用 GIL。将值设置为 0 仅在配置了 --disable-gil 的构建中可用。另请参阅 PYTHON_GIL 和 Free-threaded CPython。

    在 3.13 版本加入。

  • -X thread_inherit_context=0,1 使得 Thread 默认在启动时使用 Thread.start() 调用者的上下文副本。否则，线程将以空上下文启动。如果未设置，此选项的值在自由线程构建上默认为 1，否则为 0。另请参阅 PYTHON_THREAD_INHERIT_CONTEXT。

    在 3.14 版本加入。

  • -X context_aware_warnings=0,1 使得 warnings.catch_warnings 上下文管理器使用 ContextVar 来存储警告过滤器状态。如果未设置，此选项的值在自由线程构建上默认为 1，否则为 0。另请参阅 PYTHON_CONTEXT_AWARE_WARNINGS。

    在 3.14 版本加入。

  • -X tlbc=0,1 在配置了 --disable-gil 的构建中启用（1，默认）或禁用（0）线程局部字节码。禁用后，这也禁用了专门化的解释器。另请参阅 PYTHON_TLBC。

    在 3.14 版本加入。

它还允许传递任意值并通过 sys._xoptions 字典检索它们。

在 3.2 版本加入。

3.9 版本中的变化: 删除了 -X showalloccount 选项。

3.10 版本中的变化: 删除了 -X oldparser 选项。

在 3.14 版中移除: -J 不再保留供 Jython 使用，现在没有特殊含义。

1.1.4. 控制颜色

Python 解释器默认配置为在某些情况下（例如显示回溯时）使用颜色突出显示输出。可以通过设置不同的环境变量来控制此行为。

将环境变量 TERM 设置为 dumb 将禁用颜色。

如果设置了 FORCE_COLOR 环境变量，则无论 TERM 的值如何，都将启用颜色。这在 CI 系统上很有用，因为它们不是终端，但仍然可以显示 ANSI 转义序列。

如果设置了 NO_COLOR 环境变量，Python 将禁用输出中的所有颜色。这优先于 FORCE_COLOR。

所有这些环境变量也用于其他工具来控制颜色输出。要仅在 Python 解释器中控制颜色输出，可以使用 PYTHON_COLORS 环境变量。此变量优先于 NO_COLOR，而 NO_COLOR 又优先于 FORCE_COLOR。

1.2. 环境变量

这些环境变量影响 Python 的行为，它们在命令行开关（除了 -E 或 -I）之前处理。通常，命令行开关在存在冲突时会覆盖环境变量。

PYTHONHOME

更改标准 Python 库的位置。默认情况下，库会在 prefix/lib/pythonversion 和 exec_prefix/lib/pythonversion 中搜索，其中 prefix 和 exec_prefix 是与安装相关的目录，两者都默认为 /usr/local。

当 PYTHONHOME 设置为单个目录时，其值会替换 prefix 和 exec_prefix。要为这些指定不同的值，请将 PYTHONHOME 设置为 prefix:exec_prefix。

PYTHONPATH

扩充模块文件的默认搜索路径。格式与 shell 的 PATH 相同：一个或多个由 os.pathsep 分隔的目录路径名（例如，Unix 上的冒号或 Windows 上的分号）。不存在的目录将被静默忽略。

除了普通目录外，单独的 PYTHONPATH 条目可以引用包含纯 Python 模块（以源代码或编译形式）的 zip 文件。扩展模块不能从 zip 文件导入。

默认搜索路径与安装相关，但通常以 prefix/lib/pythonversion 开头（请参阅上面的 PYTHONHOME）。它 总是 附加到 PYTHONPATH。

如上文 接口选项 所述，一个额外的目录将被插入到搜索路径中，位于 PYTHONPATH 之前。搜索路径可以在 Python 程序内部作为变量 sys.path 进行操作。

PYTHONSAFEPATH

如果此项设置为非空字符串，则不要在 sys.path 前面添加可能不安全的路径：有关详细信息，请参阅 -P 选项。

在 3.11 版本中新增。

PYTHONPLATLIBDIR

如果此项设置为非空字符串，它将覆盖 sys.platlibdir 值。

在 3.9 版本中新增。

PYTHONSTARTUP

如果这是一个可读文件的名称，那么在该文件中定义的 Python 命令将在交互模式下显示第一个提示之前执行。该文件在与交互式命令相同的命名空间中执行，这样在其中定义或导入的对象就可以在交互式会话中无需限定地使用。你也可以在此文件中更改提示符 sys.ps1 和 sys.ps2 以及钩子 sys.__interactivehook__。

启动时调用时，会引发一个 审计事件 cpython.run_startup，并以文件名作为参数。

PYTHONOPTIMIZE

如果此变量设置为非空字符串，则等同于指定 -O 选项。如果设置为整数，则等同于多次指定 -O。

PYTHONBREAKPOINT

如果此变量已设置，它将使用点路径表示法命名一个可调用对象。包含该可调用对象的模块将被导入，然后该可调用对象将由 sys.breakpointhook() 的默认实现运行，而 sys.breakpointhook() 本身是由内置函数 breakpoint() 调用的。如果未设置，或设置为空字符串，则等同于值“pdb.set_trace”。将其设置为字符串“0”会导致 sys.breakpointhook() 的默认实现不执行任何操作，而是立即返回。

在 3.7 版本加入。

PYTHONDEBUG

如果此变量设置为非空字符串，则等同于指定 -d 选项。如果设置为整数，则等同于多次指定 -d。

此环境变量需要 Python 的调试版本，否则将被忽略。

PYTHONINSPECT

如果此变量设置为非空字符串，则等同于指定 -i 选项。

此变量也可以通过 Python 代码使用 os.environ 进行修改，以在程序终止时强制进入检查模式。

引发一个 审计事件 cpython.run_stdin，不带参数。

版本 3.12.5 中已更改: （以及 3.11.10、3.10.15、3.9.20 和 3.8.20）发出审计事件。

版本 3.13 中已更改: 如果可能，使用 PyREPL，在这种情况下 PYTHONSTARTUP 也会执行。发出审计事件。

PYTHONUNBUFFERED

如果此变量设置为非空字符串，则等同于指定 -u 选项。

PYTHONVERBOSE

如果此变量设置为非空字符串，则等同于指定 -v 选项。如果设置为整数，则等同于多次指定 -v。

PYTHONCASEOK

如果设置了此变量，Python 将忽略 import 语句中的大小写。这仅适用于 Windows 和 macOS。

PYTHONDONTWRITEBYTECODE

如果此变量设置为非空字符串，Python 在导入源模块时将不会尝试写入 .pyc 文件。这等同于指定 -B 选项。

PYTHONPYCACHEPREFIX

如果设置了此变量，Python 将在指定路径下写入 .pyc 文件，而不是在源树中的 __pycache__ 目录中。这等同于指定 -X pycache_prefix=PATH 选项。

在 3.8 版本加入。

PYTHONHASHSEED

如果未设置此变量或将其设置为 random，则使用随机值作为字符串和字节对象的哈希种子。

如果 PYTHONHASHSEED 设置为整数值，则它被用作生成哈希随机化所涵盖的类型的 hash() 的固定种子。

其目的是允许可重复的哈希，例如用于解释器本身的自测试，或允许一组 Python 进程共享哈希值。

该整数必须是范围 [0,4294967295] 内的十进制数。指定值 0 将禁用哈希随机化。

在 3.2.3 版中新增。

PYTHONINTMAXSTRDIGITS

如果此变量设置为整数，则它用于配置解释器的全局 整数字符串转换长度限制。

在 3.11 版本中新增。

PYTHONIOENCODING

如果在运行解释器之前设置此项，它将覆盖用于 stdin/stdout/stderr 的编码，语法为 encodingname:errorhandler。 encodingname 和 :errorhandler 两部分都是可选的，其含义与 str.encode() 中的相同。

对于 stderr，:errorhandler 部分被忽略；处理程序将始终为 'backslashreplace'。

版本 3.4 中已更改: encodingname 部分现在是可选的。

版本 3.6 中已更改: 在 Windows 上，除非同时指定 PYTHONLEGACYWINDOWSSTDIO，否则此变量指定的编码对于交互式控制台缓冲区将被忽略。通过标准流重定向的文件和管道不受影响。

PYTHONNOUSERSITE

如果设置了此变量，Python 将不会把 user site-packages directory 添加到 sys.path。

参见

PEP 370 – 每用户 site-packages 目录

PYTHONUSERBASE

定义了 用户基本目录，用于计算 用户 site-packages 目录 的路径以及 python -m pip install --user 的 安装路径。

参见

PEP 370 – 每用户 site-packages 目录

PYTHONEXECUTABLE

如果设置了此环境变量，sys.argv[0] 将被设置为其值，而不是通过 C 运行时获取的值。仅适用于 macOS。

PYTHONWARNINGS

这等同于 -W 选项。如果设置为逗号分隔的字符串，则等同于多次指定 -W，其中列表后部的过滤器优先于列表前部的过滤器。

最简单的设置是无条件地对进程发出的所有警告（即使是默认情况下被忽略的警告）应用特定的操作

PYTHONWARNINGS=default  # Warn once per call location
PYTHONWARNINGS=error    # Convert to exceptions
PYTHONWARNINGS=always   # Warn every time
PYTHONWARNINGS=all      # Same as PYTHONWARNINGS=always
PYTHONWARNINGS=module   # Warn once per calling module
PYTHONWARNINGS=once     # Warn once per Python process
PYTHONWARNINGS=ignore   # Never warn

有关详细信息，请参阅 警告过滤器 和 描述警告过滤器。

PYTHONFAULTHANDLER

如果此环境变量设置为非空字符串，则在启动时调用 faulthandler.enable()：为 SIGSEGV、SIGFPE、SIGABRT、SIGBUS 和 SIGILL 信号安装一个处理程序以转储 Python 回溯。这等同于 -X faulthandler 选项。

在 3.3 版本加入。

PYTHONTRACEMALLOC

如果此环境变量设置为非空字符串，则使用 tracemalloc 模块开始跟踪 Python 内存分配。变量的值是跟踪回溯中存储的最大帧数。例如，PYTHONTRACEMALLOC=1 只存储最新的帧。有关更多信息，请参阅 tracemalloc.start() 函数。这等同于设置 -X tracemalloc 选项。

在 3.4 版本加入。

PYTHONPROFILEIMPORTTIME

如果此环境变量设置为 1，Python 将显示每次导入所需的时间。如果设置为 2，Python 将包含已加载的导入模块的输出。这等同于设置 -X importtime 选项。

在 3.7 版本加入。

版本 3.14 中已更改: 添加了 PYTHONPROFILEIMPORTTIME=2 以跟踪已加载模块的导入。

PYTHONASYNCIODEBUG

如果此环境变量设置为非空字符串，则启用 asyncio 模块的 调试模式。

在 3.4 版本加入。

PYTHONMALLOC

设置 Python 内存分配器和/或安装调试钩子。

设置 Python 使用的内存分配器系列

安装 调试钩子

  • debug：在 默认内存分配器 之上安装调试钩子。

  • malloc_debug：与 malloc 相同，但也会安装调试钩子。

  • pymalloc_debug：与 pymalloc 相同，但也会安装调试钩子。

  • mimalloc_debug：与 mimalloc 相同，但也会安装调试钩子。

在 3.6 版本加入。

版本 3.7 中已更改: 添加了 "default" 分配器。

PYTHONMALLOCSTATS

如果设置为非空字符串，Python 将在每次创建新的 pymalloc 对象区域时和在关闭时打印 pymalloc 内存分配器 的统计信息。

如果 PYTHONMALLOC 环境变量用于强制使用 C 库的 malloc() 分配器，或者如果 Python 未配置 pymalloc 支持，则此变量将被忽略。

版本 3.6 中已更改: 此变量现在也可用于以发布模式编译的 Python。如果设置为空字符串，则现在无效。

PYTHONLEGACYWINDOWSFSENCODING

如果设置为非空字符串，则默认的 文件系统编码和错误处理程序 模式将分别恢复为 3.6 之前的值“mbcs”和“replace”。否则，将使用新的默认值“utf-8”和“surrogatepass”。

这也可以在运行时使用 sys._enablelegacywindowsfsencoding() 启用。

可用性：Windows。

3.6 新增: 有关更多详细信息，请参阅 PEP 529。

PYTHONLEGACYWINDOWSSTDIO

如果设置为非空字符串，则不使用新的控制台读取器和写入器。这意味着 Unicode 字符将根据活动控制台代码页进行编码，而不是使用 utf-8。

如果标准流被重定向（到文件或管道）而不是引用控制台缓冲区，则此变量将被忽略。

可用性：Windows。

在 3.6 版本加入。

PYTHONCOERCECLOCALE

如果设置为值 0，则会导致主 Python 命令行应用程序跳过将传统的基于 ASCII 的 C 和 POSIX 区域设置强制转换为功能更强大的基于 UTF-8 的替代方案。

如果此变量未设置（或设置为非 0 的值），并且 LC_ALL 区域设置覆盖环境变量也未设置，并且为 LC_CTYPE 类别报告的当前区域设置是默认的 C 区域设置，或者是显式基于 ASCII 的 POSIX 区域设置，则 Python CLI 将在加载解释器运行时之前尝试按以下顺序配置 LC_CTYPE 类别的区域设置：

  • C.UTF-8

  • C.utf8

  • UTF-8

如果成功设置其中一个区域设置类别，则在 Python 运行时初始化之前，LC_CTYPE 环境变量也将在当前进程环境中相应设置。这确保了除了解释器本身和在同一进程中运行的其他区域设置感知组件（例如 GNU readline 库）之外，更新后的设置也将在子进程中（无论这些进程是否正在运行 Python 解释器）以及查询环境而不是当前 C 区域设置的操作中（例如 Python 自己的 locale.getdefaultlocale()）可见。

配置这些区域设置之一（无论是显式还是通过上述隐式区域设置强制转换）会自动为 sys.stdin 和 sys.stdout 启用 surrogateescape 错误处理程序（sys.stderr 继续使用 backslashreplace，就像在任何其他区域设置中一样）。此流处理行为可以使用 PYTHONIOENCODING 照常覆盖。

出于调试目的，将 PYTHONCOERCECLOCALE=warn 设置将导致 Python 在 stderr 上发出警告消息，如果区域设置强制转换被激活，或者如果当 Python 运行时初始化时，一个 会 触发强制转换的区域设置仍然处于活动状态。

另请注意，即使禁用区域设置强制转换，或者当它未能找到合适的区域设置时，PYTHONUTF8 在传统的基于 ASCII 的区域设置中仍会默认激活。必须同时禁用这两个功能才能强制解释器使用 UTF-8 而不是 ASCII 作为系统接口。

可用性：Unix。

3.7 新增: 有关更多详细信息，请参阅 PEP 538。

PYTHONDEVMODE

如果此环境变量设置为非空字符串，则启用 Python 开发模式，引入额外的运行时检查，这些检查默认情况下启用成本太高。这等同于设置 -X dev 选项。

在 3.7 版本加入。

PYTHONUTF8

如果设置为 1，则启用 Python UTF-8 模式。

如果设置为 0，则禁用 Python UTF-8 模式。

设置任何其他非空字符串将在解释器初始化期间导致错误。

在 3.7 版本加入。

PYTHONWARNDEFAULTENCODING

如果此环境变量设置为非空字符串，则在使用特定于区域设置的默认编码时发出 EncodingWarning。

有关详细信息，请参阅 选择性 EncodingWarning。

在 3.10 版本加入。

PYTHONNODEBUGRANGES

如果设置了此变量，它将禁用在代码对象中将额外位置信息（结束行、开始列偏移量和结束列偏移量）映射到每个指令的表的包含。当需要更小的代码对象和 pyc 文件以及在解释器显示回溯时抑制额外的视觉位置指示器时，这很有用。

在 3.11 版本中新增。

PYTHONPERFSUPPORT

如果此变量设置为非零值，它将启用对 Linux perf 分析器的支持，以便它可以检测到 Python 调用。

如果设置为 0，则禁用 Linux perf 分析器支持。

另请参阅 -X perf 命令行选项和 Python 对 Linux perf 分析器的支持。

3.12 新版功能.

PYTHON_PERF_JIT_SUPPORT

如果此变量设置为非零值，它将启用对 Linux perf 分析器的支持，以便它可以使用 DWARF 信息检测到 Python 调用。

如果设置为 0，则禁用 Linux perf 分析器支持。

另请参阅 -X perf_jit 命令行选项和 Python 对 Linux perf 分析器的支持。

在 3.13 版本加入。

PYTHON_DISABLE_REMOTE_DEBUG

如果此变量设置为非空字符串，它将禁用 PEP 768 中描述的远程调试功能。这包括在另一个进程中调度代码执行的功能和在当前进程中接收代码执行的功能。

另请参阅 -X disable_remote_debug 命令行选项。

在 3.14 版本加入。

PYTHON_CPU_COUNT

如果此变量设置为正整数，它将覆盖 os.cpu_count() 和 os.process_cpu_count() 的返回值。

另请参阅 -X cpu_count 命令行选项。

在 3.13 版本加入。

PYTHON_FROZEN_MODULES

如果此变量设置为 on 或 off，它将决定导入机制是否忽略冻结模块。值为 on 表示它们被导入，off 表示它们被忽略。对于非调试版本（正常情况）默认为 on，对于调试版本默认为 off。请注意，即使此标志设置为 off，importlib_bootstrap 和 importlib_bootstrap_external 冻结模块也始终会被使用。

另请参阅 -X frozen_modules 命令行选项。

在 3.13 版本加入。

PYTHON_COLORS

如果此变量设置为 1，解释器将对各种输出进行着色。将其设置为 0 则禁用此行为。另请参阅 控制颜色。

在 3.13 版本加入。

PYTHON_BASIC_REPL

如果此变量设置为任何值，解释器将不会尝试加载需要 readline 的基于 Python 的 REPL，而是使用传统的基于解析器的 REPL。

在 3.13 版本加入。

PYTHON_HISTORY

此环境变量可用于设置 .python_history 文件的位置（默认情况下，它位于用户主目录中的 .python_history）。

在 3.13 版本加入。

PYTHON_GIL

如果此变量设置为 1，则全局解释器锁 (GIL) 将被强制启用。将其设置为 0 则强制禁用 GIL（需要使用 --disable-gil 构建选项配置 Python）。

另请参阅 -X gil 命令行选项，它优先于此变量，以及 Free-threaded CPython。

在 3.13 版本加入。

PYTHON_THREAD_INHERIT_CONTEXT

如果此变量设置为 1，则 Thread 默认情况下在启动时会使用 Thread.start() 调用者的上下文副本。否则，新线程将以空上下文启动。如果未设置，此变量在自由线程构建中默认为 1，否则为 0。另请参阅 -X thread_inherit_context。

在 3.14 版本加入。

PYTHON_CONTEXT_AWARE_WARNINGS

如果设置为 1，则 warnings.catch_warnings 上下文管理器将使用 ContextVar 来存储警告过滤器状态。如果未设置，此变量在自由线程构建中默认为 1，否则为 0。请参阅 -X context_aware_warnings。

在 3.14 版本加入。

PYTHON_JIT

在支持实验性即时编译的版本中，此变量可以在解释器启动时强制禁用 (0) 或启用 (1) JIT。

在 3.13 版本加入。

PYTHON_TLBC

如果设置为 1，则启用线程局部字节码。如果设置为 0，则禁用线程局部字节码和专用解释器。仅适用于使用 --disable-gil 配置的版本。

另请参阅 -X tlbc 命令行选项。

在 3.14 版本加入。

1.2.1. 调试模式变量

PYTHONDUMPREFS

如果设置了此变量，Python 将在解释器关闭后转储仍然存活的对象和引用计数。

需要使用 --with-trace-refs 构建选项配置 Python。

PYTHONDUMPREFSFILE

如果设置了此变量，Python 将在解释器关闭后转储仍然存活的对象和引用计数，并将其写入以此环境变量值作为路径的文件中。

需要使用 --with-trace-refs 构建选项配置 Python。

在 3.11 版本中新增。

PYTHON_PRESITE

如果此变量设置为模块，则该模块将在解释器生命周期的早期导入，在 site 模块执行之前，以及 __main__ 模块创建之前。因此，导入的模块不会被视为 __main__。

这可用于在 Python 初始化早期执行代码。

要导入子模块，请使用 package.module 作为值，就像在 import 语句中一样。

另请参阅 -X presite 命令行选项，它优先于此变量。

需要使用 --with-pydebug 构建选项配置 Python。

在 3.13 版本加入。