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 的开头（允许导入该目录中的模块作为顶层模块）。

引发一个带参数 command 的 审计事件 cpython.run_command。

-m <module-name>

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

由于参数是 *module* 名称，因此您不得给出文件扩展名 (.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

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

另请参阅

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 的开头。此外，如果你的平台可用，则会自动启用制表符补全和历史记录编辑（请参阅 Readline 配置）。

另请参阅

调用解释器

在 3.4 版本中更改: 自动启用制表符补全和历史记录编辑。

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（隔离）选项。

-i

当脚本作为第一个参数传递或使用 -c 选项时，即使 sys.stdin 似乎不是终端，也会在执行脚本或命令后进入交互模式。不读取 PYTHONSTARTUP 文件。

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

-I

在隔离模式下运行 Python。这也意味着 -E、-P 和 -s 选项。

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

在 3.4 版本中添加。

-O

删除 assert 语句以及任何基于 __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 环境变量设置为 0 时，此选项才生效，因为默认情况下已启用哈希随机化。

在以前的 Python 版本中，此选项会启用哈希随机化，从而使 str 和 bytes 对象的 __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.main()）。

-u

强制 stdout 和 stderr 流无缓冲。 此选项对 stdin 流无效。

另请参阅 PYTHONUNBUFFERED。

在 3.7 版本中更改: stdout 和 stderr 流的文本层现在是无缓冲的。

-v

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

在 3.10 版本中更改: 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 用于显示每个导入花费的时间。 它显示模块名称、累积时间（包括嵌套导入）和自身时间（不包括嵌套导入）。 请注意，其输出在多线程应用程序中可能会中断。 典型用法是 python3 -X importtime -c 'import asyncio'。另请参阅 PYTHONPROFILEIMPORTTIME。

    在 3.7 版本中加入。

  • -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。请注意，即使此标志设置为 off，也始终使用 importlib_bootstrap 和 importlib_bootstrap_external 冻结的模块。另请参阅 PYTHON_FROZEN_MODULES。

    在 3.11 版本中添加。

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

    在 3.12 版本中加入。

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

    在 3.13 版本中加入。

  • -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 和 自由线程 CPython。

    在 3.13 版本中加入。

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

3.2 版本新增。

在 3.9 版本中更改: 删除了 -X showalloccount 选项。

在 3.10 版本中更改: 删除了 -X oldparser 选项。

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.1.5. 你不应该使用的选项

-J

保留供 Jython 使用。

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 选项。

也可以使用 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，则会使用随机值来为 str 和 bytes 对象的哈希值生成种子。

如果 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

定义 user base directory，该目录用于计算 user site-packages directory 的路径以及 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

如果将此环境变量设置为非空字符串，Python 将显示每个导入所花费的时间。这等效于设置 -X importtime 选项。

在 3.7 版本中加入。

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 像往常一样覆盖此流处理行为。

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

另请注意，即使禁用区域设置强制转换，或在查找合适的目标区域设置失败时，PYTHONUTF8 仍将在传统的基于 ASCII 的区域设置中默认激活。必须禁用这两个功能，才能强制解释器对系统接口使用 ASCII 而不是 UTF-8。

可用性：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_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

如果此变量设置为 1，解释器将不会尝试加载需要 curses 和 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 命令行选项，该选项优先于此变量，以及 无线程 CPython。

在 3.13 版本中加入。

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 版本中加入。