1. 命令行和环境¶

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。

-m <模块名称>¶

在 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 文件的压缩文件。

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

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

如果脚本名称指向目录或压缩文件，则脚本名称将添加到 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 配置）。

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¶

移除断言语句和任何以 __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 版本中，此选项启用哈希随机化，以便 __hash__() 的 str 和 bytes 对象的值使用不可预测的随机值“加盐”。虽然它们在单个 Python 进程中保持不变，但它们在 Python 的重复调用之间是不可预测的。

哈希随机化旨在提供针对拒绝服务攻击的保护，该攻击是由精心选择的输入引起的，这些输入利用了 dict 构造的最坏情况性能，即 *O*(*n*²) 复杂度。有关详细信息，请参见 http://ocert.org/advisories/ocert-2011-003.html。

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

在版本 3.2.3 中添加。

在版本 3.7 中更改：此选项不再被忽略。

-s¶

不要将 user site-packages directory 添加到 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 特定的 hack。

-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”冻结模块。

  在版本 3.11 中添加。

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

  在 3.12 版本中添加。

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

在版本 3.2 中添加。

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

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

1.1.4. 您不应该使用的选项¶

-J¶

保留供 Jython 使用。

1.2.1. 调试模式变量¶

PYTHONDUMPREFS¶

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

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

PYTHONDUMPREFSFILE=FILENAME¶

如果设置，Python 将转储在关闭解释器后仍然存在的对象和引用计数到名为 FILENAME 的文件中。

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

在版本 3.11 中添加。