1. 命令行与环境

为获取各种设置信息，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 来产生此字符）。 有关交互模式的更多信息，请参阅 交互模式。

• 用文件名参数或以标准输入文件调用时，读取，并执行该脚本文件。

• 用目录名参数调用时，从该目录读取、执行适当名称的脚本。

• When called with -c command, it executes the Python statement(s) given as command. Here command may contain multiple statements separated by newlines.

• 用 -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 # 获取详情

引发一个 审计事件 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 代码，该参数应为（绝对或相对）文件系统路径，指向 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 专属环境变量的简短描述然后退出。

Added in version 3.11.

--help-xoptions

打印实现专属 -X 选项的简短描述然后退出。

Added in version 3.11.

--help-all

打印完整使用信息然后退出。

Added in version 3.11.

-V

--version

输出 Python 版本号并退出。示例如下：

Python 3.8.0b2+

输入两次 V 选项时，输出更多构建信息，例如：

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

Added in version 3.6: -VV 选项。

1.1.3. 其他选项

-b

在将 bytes 或 bytearray 转换为 str 时未指定编码格式或在将 bytes 或 bytearray 与 str 或者在将 bytes 与 int 进行比较时将发出警告。 当选项被给出两次 (-bb) 时则会报错。

在 3.5 版本发生变更: 也会影响 bytes 与 int 的比较。

自 3.15 版本弃用: Deprecate -b and -bb command line options and schedule them to become no-op in Python 3.17. These were primarily helpers for the Python 2 -> 3 transition. Starting with Python 3.17, no BytesWarning will be raised for these cases; use a type checker instead.

-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 (隔离) 选项。

-i

在执行之后进入交互模式。

使用 -i 选项将在下列任一情况下进入交互模式：

• 当将脚本作为第一个参数传入

• 当使用了 -c 选项

• 当使用了 -m 选项

交互模式即使在 sys.stdin 并非一个终端时也会启动。 PYTHONSTARTUP 文件不会被读取。

本选项用于，脚本触发异常时，检查全局变量或堆栈回溯。 详见 PYTHONINSPECT。

-I

以隔离模式运行 Python。 这还将应用 -E, -P 和 -s 选项。

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

Added in version 3.4.

-O

移除 assert 语句以及任何以 __debug__ 的值作为条件的代码。 通过在 .pyc 扩展名之前添加 .opt-1 来扩充已编译文件 (bytecode) 的文件名 (参见 PEP 488)。 另请参阅 PYTHONOPTIMIZE。

在 3.5 版本发生变更: 依据 PEP 488 修改 .pyc 文件名。

-OO

在启用 -O 的同时丢弃文档字符串。 通过在 .pyc 扩展名之前添加 .opt-2 来扩展已编译文件 (bytecode) 的文件名 (参见 PEP 488)。

在 3.5 版本发生变更: 依据 PEP 488 修改 .pyc 文件名。

-P

不要将具有潜在不安全性的路径前置到 sys.path:

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

• python script.py 命令行: 不要前置脚本所在目录。 如果是一个符号链接，则会解析符号链接。

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

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

Added in version 3.11.

-q

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

Added in version 3.2.

-R

开启哈希随机化。此选项仅在环境变量 PYTHONHASHSEED 的值设为非 random 时才会生效，因为哈希随机化在默认情况下已处于启用状态。

在之前版本的 Python 中，此选项会启用哈希随机化，以将字符串和字节串对象的 __hash__() 值用不可预测的随机值“加盐”。 虽然它们在单个 Python 进程内将保持恒定，但是在重复唤起的 Python 进程间它们将是不可预测的。

哈希随机化旨在针对由精心选择的输入引起的拒绝服务攻击提供防护，这种输入利用了构造字典在最坏情况下的性能即 O(n²) 复制度。 参见 https://ocert.org/advisories/ocert-2011-003.html 了解详情。

PYTHONHASHSEED 允许你为哈希种子密码设置一个固定值。

Added in version 3.2.3.

在 3.7 版本发生变更: 此选项不会再被忽略。

-s

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

另请参阅 PYTHONNOUSERSITE。

参见

PEP 370 -- 分用户的 site-packages 目录

-S

禁用 site 的导入及其所附带的基于站点对 sys.path 的操作。 如果 site 会在稍后被显式地导入也会禁用这些操作 (如果你希望触发它们则应调用 site.main())。

-u

强制 stdout 和 stderr 流不使用缓冲。 此选项对 stdin 流无影响。

另请参阅 PYTHONUNBUFFERED。

在 3.7 版本发生变更: stdout 和 stderr 流在文本层现在不使用缓冲。

-v

每次在初始化模块时会打印一条信息，显示被加载的地方（文件名或内置模块名）。当给出两个v（ -vv ）时，搜索模块时会为每个文件打印一条信息。退出时模块清理的信息也会给出来。

在 3.10 版本发生变更: 由 site 模块可以得到将要处理的站点路径和 .pth 文件。

参阅 PYTHONVERBOSE 。

-W arg

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

最简单的设置是将某个特定操作无条件地应用于进程所发出的所有警告 (即使是在默认情况下会忽略的那些警告):

-Wdefault  # 每个调用位置警告一次
-Werror    # 转换为异常
-Walways   # 每次都警告
-Wall      # 与 -Walways 相同
-Wmodule   # 每个调用模块警告一次
-Wonce     # 每个 Python 进程警告一次
-Wignore   # 从不警告

action 名可以根据需要进行缩写，解释器将会解析为合适的名称。例如，-Wi 与 -Wignore 相同。

完整的参数如下：

action:message:category:module:lineno

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

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

The message field must match the start of the warning message; this match is case-insensitive. If it starts and ends with a forward slash (/), it specifies a regular expression, otherwise it specifies a literal string.

category 字段与警告类别相匹配（DeprecationWarning 等）。必须是个类名；检测消息的实际警告类别是否为指定类别的子类。

The module field matches the (fully qualified) module name; this match is case-sensitive. If it starts and ends with a forward slash (/), it specifies a regular expression that the start of the fully qualified module name must match, otherwise it specifies a literal string that the fully qualified module name must be equal to.

lineno 字段匹配行号，其中 0 匹配所有行号，相当于省略了行号。

可以给出多个 -W 选项；当某条警告信息匹配上多个选项时，将执行最后一个匹配项的操作。非法 -W 选项将被忽略（不过，在触发第一条警告时，会打印出一条无效选项的警告信息）。

警告信息还可以用 PYTHONWARNINGS 环境变量来控制，也可以在 Python 程序中用 warnings 模块进行控制。例如， warnings.filterwarnings() 函数可对警告信息使用正则表达式。

请参阅 警告过滤器 和 警告过滤器的介绍 了解更多细节。

在 3.15 版本发生变更: Added regular expression support for message and module.

-x

跳过源中第一行，以允许使用非 Unix 形式的 #!cmd。 这适用于 DOS 专属的破解操作。

-X

保留用于各种具体实现专属的选项。 CPython 目前定义了下列可用的值：

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

  Added in version 3.3.

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

  Added in version 3.4.

• -X tracemalloc 使用 tracemalloc 模块启动对 Python 内存分配的跟踪。 在默认情况下，只有最近的帧会保存在跟踪的回溯信息中。 使用 -X tracemalloc=NFRAME 来启动限定回溯 NFRAME 帧的跟踪。 请参阅 tracemalloc.start() 和 PYTHONTRACEMALLOC 了解详情。

  Added in version 3.4.

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

  Added in version 3.11.

• -X importtime 显示每次导入耗费的时间。 它会显示模块名称、累计时间（包括嵌套的导入）和自身时间（排除嵌套的导入）。 请注意它的输出在多线程应用程序中可能会出错。 典型用法是 python -X importtime -c 'import asyncio'。

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

  另请参阅 PYTHONPROFILEIMPORTTIME。

  Added in version 3.7.

  在 3.14 版本发生变更: 增加了 -X importtime=2 用于额外追踪已加载模块的导入，并保留 1 和 2 以外的值供未来使用。

• -X dev: 启用 Python 开发模式，引入在默认情况下启用会导致过大开销的运行时检查。 另请参阅 PYTHONDEVMODE。

  Added in version 3.7.

• -X utf8 启用 Python UTF-8 模式。 -X utf8=0 将显式地禁用 Python UTF-8 模式 (即使在该模式应该会自动激活时也是如此)。 另请参阅 PYTHONUTF8。

  Added in version 3.7.

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

  Added in version 3.8.

• 当采用某地区默认编码打开文件时，-X warn_default_encoding 将引发一条 EncodingWarning。参见 PYTHONWARNDEFAULTENCODING。

  Added in version 3.10.

• -X no_debug_ranges 会禁用在代码对象中包括将额外位置信息（结束行、开始列偏移量和结束列偏移量）映射到每条指令的映射表。 这在需要较小的代码对象和 pyc 文件时很有用处并可在解释器显示回溯时屏蔽额外的视觉位置提示。 另请参阅 PYTHONNODEBUGRANGES。

  Added in version 3.11.

• -X frozen_modules 确定已冻结模块是否要被导入机制所忽略。值为 on 表示它们将被导入而 off 表示它们将被忽略。 如果是安装版 Python（正常情况）则默认为 on。 如果是在开发中（基于源代码树运行）则默认为 off。 请注意 importlib_bootstrap 和 importlib_bootstrap_external 冻结模块总是会被使用，即使该旗标被设为 off。 另请参阅 PYTHON_FROZEN_MODULES。

  Added in version 3.11.

• -X perf 会启用对 Linux perf 性能分析器的支持。 当提供了此选项时，perf 性能分析器将能够报告 Python 调用。 此选项仅在某些平台上可用而在当前系统不支持的情况下将不做任何事。 默认值为 "off"。 另请参阅 PYTHONPERFSUPPORT 和 Python support for the perf map compatible profilers。

  Added in version 3.12.

• -X perf_jit 将启用对 Linux perf 性能分析器的支持并附带 DWARF 支持。 当提供了此选项时，perf 性能分析器将能够使用 DWARF 信息来报告 Python 调用。 此选项仅在某些平台上可用而在当前系统不支持的情况下将不做任何事。 默认值为 "off"。 另请参阅 PYTHON_PERF_JIT_SUPPORT 和 Python support for the perf map compatible profilers。

  Added in version 3.13.

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

  此选项仅在某些平台上可用，如果当前系统不支持此选项，则不会执行任何操作。 参见 PYTHON_DISABLE_REMOTE_DEBUG 和 PEP 768。

  Added in version 3.14.

• -X cpu_count=n 将覆盖 os.cpu_count(), os.process_cpu_count() 和 multiprocessing.cpu_count()。 n 必须大于等于 1。 此选项对于需要限制某个容器系统的 CPU 资源的用户来说会很有用处。 另请参阅 PYTHON_CPU_COUNT。 如果 n 为 default，则不会覆盖任何值。

  Added in version 3.13.

• -X presite=module or -X presite=module:func specifies an entry point that should be executed before the site module is executed and before the __main__ module exists. Therefore, the imported module isn't __main__. This can be used to execute code early during Python initialization. Python needs to be built in debug mode for this option to exist. See also PYTHON_PRESITE.

  在 3.15.0a8 (unreleased) 版本发生变更: Accept also module:func entry point format.

  Added in version 3.13.

• -X gil=0,1 强制分别禁用或启用 GIL。 设为 0 仅在配置了 --disable-gil 的构建版上可用。 另请参阅 PYTHON_GIL 和 自由线程的 CPython。

  Added in version 3.13.

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

  Added in version 3.14.

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

  Added in version 3.14.

• -X pathconfig_warnings=0,1 if true (1) then sys.path 模块搜索路径的初始化 is allowed to log warnings into stderr. If false (0) suppress these warnings. Set to true by default. See also PYTHON_PATHCONFIG_WARNINGS.

  Added in version 3.15.

• -X tlbc=0,1 在配置了 --disable-gil 的构建中启用 (1, 默认值) 或禁用 (0) 线程本地字节码。 当禁用时，这也会禁用专门化解释器。 参见 PYTHON_TLBC。

  Added in version 3.14.

• -X lazy_imports=all,none,normal controls lazy import behavior. all makes all imports lazy by default, none disables lazy imports entirely (even explicit lazy statements become eager), and normal (the default) respects the lazy keyword in source code. See also PYTHON_LAZY_IMPORTS.

  Added in version 3.15.

它还允许传入任意值并通过 sys._xoptions 字典来提取这些值。

Added in version 3.2.

在 3.9 版本发生变更: 移除了 -X showalloccount 选项。

在 3.10 版本发生变更: 移除了 -X oldparser 选项。

Removed in version 3.14: -J 不再被保留给 Jython 使用，现在它已没有特殊含义。

1.1.4. 控制颜色

Python 解释器默认被配置为在特定场景例如当显示回溯信息时使用颜色高亮输出。 此行为可通过设置不同的环境变量来控制。

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

如果设置了 FORCE_COLOR 环境变量，则无论 TERM 的值为何都将启用彩色。 这适用于不属于终端但仍然会显示 ANSI 转义序列的 CI 系统。

如果设置了 NO_COLOR 环境变量，则 Python 将在输出中禁用所有彩色。 此变量的优先级高于 FORCE_COLOR。

所有这些环境变量也被其他工具用来控制颜色输出。 要仅在 Python 解释器中控制颜色输出，可以使用 PYTHON_COLORS 环境变量。 此变量的优先级高于 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

增加模块文件默认搜索路径。 所用格式与终端的 PATH 相同：一个或多个由 os.pathsep 分隔的目录路径名称（例如 Unix 上用冒号而在 Windows 上用分号）。 默认忽略不存在的目录。

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

默认搜索路径依赖于安装路径，但通常都是以 prefix/lib/pythonversion 开始 (参见上文中的 PYTHONHOME)。 它 总是 会被添加到 PYTHONPATH。

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

PYTHONSAFEPATH

如果这被设为一个非空字符串，请不要将具有潜在不安全性的路径前置到 sys.path: 参见 -P 选项了解详情。

Added in version 3.11.

PYTHONPLATLIBDIR

如果它被设为非空字符串，则会覆盖 sys.platlibdir 值。

Added in version 3.9.

PYTHONSTARTUP

这如果是一个可读文件的名称，该文件中的 Python 命令会在交互模式的首个提示符显示之前被执行。 该文件会在与交互式命令执行所在的同一命名空间中被执行，因此其中所定义或导入的对象可以在交互式会话中无限制地使用。 你还可以在这个文件中修改提示符 sys.ps1 和 sys.ps2 以及钩子 sys.__interactivehook__。

在启动时调用文件名作为参数会引发 审计事件 cpython.run_startup 。

PYTHONOPTIMIZE

这如果被设为一个非空字符串，它就相当于指定 -O 选项。 如果设为一个整数，则它就相当于多次指定 -O。

PYTHONBREAKPOINT

此变量如果被设定，它会使用加点号的路径标记一个可调用对象。 包含该可调用对象的模块将被导入，随后该可调用对象将由 sys.breakpointhook() 的默认实现来运行，后者自身将由内置的 breakpoint() 来调用。 如果未设定，或设定为空字符串，则它相当于值 "pdb.set_trace"。 将此变量设为字符串 "0" 会导致 sys.breakpointhook() 的默认实现不做任何事而直接返回。

Added in version 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 选项。

Added in version 3.8.

PYTHONHASHSEED

如果此变量未设置或设为 random，将使用一个随机值作为 str 和 bytes 对象哈希运算的种子。

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

它的目的是允许可复现的哈希运算，例如用于解释器本身的自我检测，或允许一组 python 进程共享哈希值。

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

Added in version 3.2.3.

PYTHONINTMAXSTRDIGITS

如果将此变量设为一个整数，它会被用来配置解释器的全局 整数字符串转换长度限制。

Added in version 3.11.

PYTHONIOENCODING

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

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

在 3.4 版本发生变更: “encodingname” 部分现在是可选的。

在 3.6 版本发生变更: 在 Windows 上，对于交互式控制台缓冲区会忽略此变量所指定的编码，除非还指定了 PYTHONLEGACYWINDOWSSTDIO。 通过标准流重定向的文件和管道则不受其影响。

PYTHONNOUSERSITE

This is equivalent to the -s option. If this is set, Python won't add the user site-packages directory to sys.path.

参见

PEP 370 -- 分用户的 site-packages 目录

PYTHONUSERBASE

定义 用户基准目录，它将被用来计算 user site-packages 目录 以及 python -m pip install --user 的 安装路径。

To disable the user site-packages, see PYTHONNOUSERSITE or the -s option.

参见

PEP 370 -- 分用户的 site-packages 目录

PYTHONEXECUTABLE

如果设置了此环境变量，则 sys.argv[0] 将被设为此变量的值而不是通过 C 运行时所获得的值。 这仅在 macOS 上起作用。

PYTHONWARNINGS

此变量等价于 -W 选项。 如果被设为一个以逗号分隔的字符串，它就相当于多次指定 -W，列表中后出现的过滤器优先级会高于列表中先出现的。

最简单的设置是将某个特定操作无条件地应用于进程所发出的所有警告 (即使是在默认情况下会忽略的那些警告):

PYTHONWARNINGS=default  # 每个调用位置警告一次
PYTHONWARNINGS=error    # 转换为异常
PYTHONWARNINGS=always   # 每次都警告
PYTHONWARNINGS=all      # 与 PYTHONWARNINGS=always 相同
PYTHONWARNINGS=module   # 每个调用模块警告一次
PYTHONWARNINGS=once     # 每个 Python 进程警告一次
PYTHONWARNINGS=ignore   # 从不警告

请参阅 警告过滤器 和 警告过滤器的介绍 了解更多细节。

在 3.15 版本发生变更: Added regular expression support for message and module.

PYTHONFAULTHANDLER

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

Added in version 3.3.

PYTHONTRACEMALLOC

如果此环境变量被设为一个非空字符串，则会使用 tracemalloc 模块启动对 Python 内存分配的跟踪。 该变量的值是保存在跟踪的回溯信息中的最大帧数。 例如， PYTHONTRACEMALLOC=1 只保存最近的帧。 请参阅 tracemalloc.start() 函数了解更多信息。 这等价于设置 -X tracemalloc 选项。

Added in version 3.4.

PYTHONPROFILEIMPORTTIME

如果此环境变量被设为 1，Python 将会显示每次导入耗费了多长时间。如果设置为 2，Python 将包含已加载的已导入模块的输出。 这等价于设置 -X importtime 选项。

Added in version 3.7.

在 3.14 版本发生变更: 增加了 PYTHONPROFILEIMPORTTIME=2 用于额外追踪已加载模块的导入。

PYTHONASYNCIODEBUG

如果此变量被设为一个非空字符串，则会启用 asyncio 模块的 调试模式。

Added in version 3.4.

PYTHONMALLOC

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

设置 Python 所使用的内存分配器族群：

• default: 使用 默认内存分配器。

• malloc: 对所有域 (PYMEM_DOMAIN_RAW, PYMEM_DOMAIN_MEM, PYMEM_DOMAIN_OBJ) 使用 C 库的 malloc() 函数。

• pymalloc: 对 PYMEM_DOMAIN_MEM 和 PYMEM_DOMAIN_OBJ 域使用 pymalloc 分配器 而对 PYMEM_DOMAIN_RAW 域使用 malloc() 函数。

• mimalloc: 对 PYMEM_DOMAIN_MEM 和 PYMEM_DOMAIN_OBJ 域使用 mimalloc 分配器 而对 PYMEM_DOMAIN_RAW 域使用 malloc() 函数。

安装 调试钩子 ：

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

• malloc_debug: 与 malloc 相同但还会安装调试钩子。

• pymalloc_debug: 与 pymalloc 相同但还会安装调试钩子。

• mimalloc_debug: 与 mimalloc 相同但还会安装调试钩子。

备注

在 自由线程 构建版中，不支持 malloc, malloc_debug, pymalloc 和 pymalloc_debug 等值。 只有 default, debug, mimalloc 和 mimalloc_debug 可被接受。

Added in version 3.6.

在 3.7 版本发生变更: 增加了 "default" 分配器。

PYTHONMALLOCSTATS

如果设为一个非空字符串，Python 将在每次创建新的对象区域以及在关闭时打印 pymalloc 内存分配器 或 mimalloc 内存分配器 (两者中被使用的那个) 的统计信息。

如果 PYTHONMALLOC 环境变量被用来强制开启 C 库的 malloc() 分配器，或者如果 Python 的配置不支持 pymalloc 和 mimalloc 则此变量将被忽略。

在 3.6 版本发生变更: 此变量现在也可以被用于在发布模式下编译的 Python。 如果它被设置为一个空字符串则将没有任何效果。

PYTHON_PYMALLOC_HUGEPAGES

If set to a non-zero integer, enable huge page support for pymalloc arenas. Set to 0 or unset to disable. Python must be compiled with --with-pymalloc-hugepages for this variable to have any effect.

When enabled, arena allocation uses MAP_HUGETLB (Linux) or MEM_LARGE_PAGES (Windows) with automatic fallback to regular pages if huge pages are not available.

警告

On Linux, if the huge-page pool is exhausted, page faults — including copy-on-write faults triggered by os.fork() — deliver SIGBUS and kill the process. Only enable this in environments where the huge-page pool is properly sized and fork-safety is not a concern.

On Windows you need a special privilege. See the Windows documentation for large pages for details. Python will fail on startup if the required privilege SeLockMemoryPrivilege is not held by the user.

Added in version 3.15.

PYTHONLEGACYWINDOWSFSENCODING

如果设为非空字符串，默认的 filesystem encoding and error handler 模式将恢复到 3.6 版本之前的值 “mbcs”和“replace”。 否则，将采用新的默认值“utf-8”和“surrogatepass”。

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

适用范围: Windows.

Added in version 3.6: 更多详情请参阅 PEP 529。

PYTHONLEGACYWINDOWSSTDIO

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

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

适用范围: Windows.

Added in version 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 来覆盖。

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

还要注意，即使在区域强制转换被禁用，或者在其无法找到合适的目标区域时，默认 PYTHONUTF8 仍将在传统的基于 ASCII 的区域中被激活。 必须同时禁用这两项特性以强制解释器使用 ASCII 而不是 UTF-8 作为系统接口。

适用范围: Unix.

Added in version 3.7: 请参阅 PEP 538 了解详情。

PYTHONDEVMODE

如果此环境变量被设为一个非空字符串，则会启用 Python 开发模式，引入在默认情况下启用扩展会导致开销过大的额外运行时检查。 这等价于设置 -X dev 选项。

Added in version 3.7.

PYTHONUTF8

如果设为 1 ，将会启用 Python UTF-8 模式。

若设为 0 ，则会禁用 Python UTF-8 模式 。

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

Added in version 3.7.

PYTHONWARNDEFAULTENCODING

如果该环境变量设为一个非空字符串，则在采用某地区默认编码时，将会引发一条 EncodingWarning 。

请参阅 选择性的 EncodingWarning 来了解详情。

Added in version 3.10.

PYTHONNODEBUGRANGES

如果设置了此变量，它会禁用在代码对象中包括将额外位置信息（结束行、开始列偏移量和结束列偏移量）映射到每条指令的映射表。 这在需要较小的代码对象和 pyc 文件时很有用处并可在解释器显示回溯时屏蔽额外的视觉位置提示。

Added in version 3.11.

PYTHONPERFSUPPORT

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

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

另请参阅 -X perf 命令行选项和 Python support for the perf map compatible profilers。

Added in version 3.12.

PYTHON_PERF_JIT_SUPPORT

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

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

另请参阅 -X perf_jit 命令行选项和 Python support for the perf map compatible profilers。

Added in version 3.13.

PYTHON_DISABLE_REMOTE_DEBUG

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

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

Added in version 3.14.

PYTHON_CPU_COUNT

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

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

Added in version 3.13.

PYTHON_FROZEN_MODULES

如果此变量被设为 on 或 off，它将确定已冻结模块是否要被导入机制所忽略。 值为 on 表示它们将被导入而 off 表示它们将被忽略。 对于非调试构建版（正常情况）默认为 on 而对调试构建版则为 off。 请注意 importlib_bootstrap 和 importlib_bootstrap_external 冻结模块总是会被使用，即使该旗标被设为 off。

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

Added in version 3.13.

PYTHON_COLORS

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

Added in version 3.13.

PYTHON_BASIC_REPL

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

Added in version 3.13.

PYTHON_BASIC_COMPLETER

If this variable is set to any value, PyREPL will use rlcompleter to implement tab completion, instead of the default one which uses colors.

Added in version 3.15.

PYTHON_HISTORY

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

Added in version 3.13.

PYTHON_GIL

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

另请参阅 -X gil 命令行选项，该选项的优先级高于此变量，并请参阅 自由线程的 CPython。

Added in version 3.13.

PYTHON_THREAD_INHERIT_CONTEXT

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

Added in version 3.14.

PYTHON_CONTEXT_AWARE_WARNINGS

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

Added in version 3.14.

PYTHON_PATHCONFIG_WARNINGS

If true (1) then sys.path 模块搜索路径的初始化 is allowed to log warnings into stderr. If false (0) suppress these warnings. Set to true by default. See also -X pathconfig_warnings.

Added in version 3.15.

PYTHON_JIT

在支持实验性即时编译（just-in-time compilation，简称 JIT）功能的构建版本中，这个变量可以在解释器启动时强制将 JIT 禁用 (0) 或者启用 (1)。

Added in version 3.13.

PYTHON_TLBC

如果设置为 1 则启用线程本地字节码。 如果设置为 0 则线程本地字节码和专门化解释器都被禁用。 仅适用于配置了 --disable-gil 的构建。

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

Added in version 3.14.

PYTHON_LAZY_IMPORTS

Controls lazy import behavior. Accepts three values: all makes all imports lazy by default, none disables lazy imports entirely (even explicit lazy statements become eager), and normal (the default) respects the lazy keyword in source code.

See also the -X lazy_imports command-line option.

Added in version 3.15.

1.2.1. 调试模式变量

PYTHONDUMPREFS

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

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

PYTHONDUMPREFSFILE

如果设置，Python 将在关闭解释器后将仍然存活的对象和引用计数转储至此环境变量给出的路径所对应的文件中。

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

Added in version 3.11.

PYTHON_PRESITE

如果此变量被设为一个模块，则该模块将在解释器生命周期的较早阶段被导入，即在 site 模块被执行之前，并在 __main__ 模块被创建之前。 因此，这个被导入的模块不会被作为 __main__。

这适用于要早在 Python 初始化期间就执行的代码。

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

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

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

在 3.15.0a8 (unreleased) 版本发生变更: Accept also module:func entry point format.

Added in version 3.13.