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

使用 command 参数会引发 审计事件 cpython.run_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

使用 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 代码，该参数应为（绝对或相对）文件系统路径，指向 Python 文件、包含 __main__.py 文件的目录，或包含 __main__.py 文件的 zip 文件。

给出此选项时，sys.argv 的第一个元素就是在命令行中指定的脚本名称。

如果脚本名称直接指向 Python 文件，则把该文件所在目录加入 sys.path 的开头，并且把该文件当作 __main__ 模块来执行。

如果脚本名称指向目录或 zip 文件，则把脚本名加入 sys.path 的开头，并把该位置中的 __main__.py 文件当作 __main__ 模块来执行。

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

使用 filename 参数会引发 审计事件 cpython.run_file 。

参见

runpy.run_path()

Python 代码可以直接使用的等效功能

未给出接口选项时，使用 -i，sys.argv[0] 为空字符串 ("")，并把当前目录加至 sys.path 的开头。 此外，如果系统支持，还能自动启用 tab 补全和历史编辑（参见 Readline 配置）。

1.1.2. 通用选项¶

-?¶

-h¶

--help¶

输出所有命令行选项的简介。

-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]

3.6 新版功能: -VV 选项。

1.1.3. 其他选项¶

-b¶

用 str 与 bytes 或 bytearray 对比， 或对比 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¶

Turn on parser debugging output (for expert only). See also the PYTHONDEBUG environment variable.

This option requires a debug build of Python, otherwise it's ignored.

-E¶

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

See also the -P and -I (isolated) options.

-i¶

脚本是第一个参数，或使用 -c 时，即便 sys.stdin 不是终端，执行脚本或命令后，也会进入交互模式。不读取 PYTHONSTARTUP 文件。

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

-I¶

Run Python in isolated mode. This also implies -E, -P and -s options.

In isolated mode sys.path contains neither the script's directory nor the user's site-packages directory. All PYTHON* environment variables are ignored, too. Further restrictions may be imposed to prevent the user from injecting malicious code.

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¶

Don't prepend a potentially unsafe path to sys.path:

• python -m module command line: Don't prepend the current working directory.

• python script.py command line: Don't prepend the script's directory. If it's a symbolic link, resolve symbolic links.

• python -c code and python (REPL) command lines: Don't prepend an empty string, which means the current working directory.

See also the PYTHONSAFEPATH environment variable, and -E and -I (isolated) options.

3.11 新版功能.

-q¶

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

3.2 新版功能.

-R¶

开启哈希随机化。 此选项权 PYTHONHASHSEED 环境变量设置为 0 时起作用，因为哈希随机化是默认启用的。

在Python的早期版本中，此选项启用哈希随机化，将 str 和 bytes 的对象 __hash__() 的值 "加盐" 为不可预测的随机值。虽然它们在单个Python进程中保持不变，但是在重复调用的Python进程之间它们是不可预测的。

Hash randomization is intended to provide protection against a denial-of-service caused by carefully-chosen inputs that exploit the worst case performance of a dict construction, O(n²) complexity. See http://www.ocert.org/advisories/ocert-2011-003.html for details.

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

在 3.7 版更改: 此选项不会再被忽略。

3.2.3 新版功能.

-s¶

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

参见

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  # Warn once per call location
-Werror    # Convert to exceptions
-Walways   # Warn every time
-Wmodule   # Warn once per calling module
-Wonce     # Warn once per Python process
-Wignore   # Never warn

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

完整的参数如下：

action:message:category:module:lineno

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

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

message 字段必须与整个警告信息相匹配；不区分大小写。

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

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

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

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

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

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

-x¶

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

-X¶

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

• -X faulthandler 启用 faulthandler；

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

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

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

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

• -X utf8 启用 Python UTF-8 模式。 -X utf8=0 显式禁用 Python UTF-8 模式 (即便已自动启用)。

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

• -X warn_default_encoding issues a EncodingWarning when the locale-specific default encoding is used for opening files. See also PYTHONWARNDEFAULTENCODING.

• -X no_debug_ranges disables the inclusion of the tables mapping extra location information (end line, start column offset and end column offset) to every instruction in code objects. This is useful when smaller code objects and pyc files are desired as well as suppressing the extra visual location indicators when the interpreter displays tracebacks. See also PYTHONNODEBUGRANGES.

• -X frozen_modules determines whether or not frozen modules are ignored by the import machinery. A value of "on" means they get imported and "off" means they are ignored. The default is "on" if this is an installed Python (the normal case). If it's under development (running from the source tree) then the default is "off". Note that the "importlib_bootstrap" and "importlib_bootstrap_external" frozen modules are always used, even if this flag is set to "off".

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

在 3.2 版更改: 增加了 -X 选项。

3.3 新版功能: -X faulthandler 选项。

3.4 新版功能: -X showrefcount 与 -X tracemalloc 选项。

3.6 新版功能: -X showalloccount 选项。

3.7 新版功能: -X importtime, -X dev 与 -X utf8 选项。

3.8 新版功能: -X pycache_prefix 选项。 -X dev 选项现在在 io.IOBase 析构函数中记录 close() 异常。

在 3.9 版更改: 使用 -X dev 选项，在字符串编码和解码操作时检查 encoding 和 errors 参数。

The -X showalloccount 选项已被移除。

3.10 新版功能: -X warn_default_encoding 选项。

Deprecated since version 3.9, removed in version 3.10: The -X oldparser option.

3.11 新版功能: The -X no_debug_ranges option.

3.11 新版功能: The -X frozen_modules option.

1.1.4. 不应当使用的选项¶

-J¶

保留给 Jython 使用。

1.2.1. 调试模式变量¶

PYTHONDUMPREFS¶

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

需用 --with-trace-refs 编译选项来配置 Python。

PYTHONDUMPREFSFILE=FILENAME¶

If set, Python will dump objects and reference counts still alive after shutting down the interpreter into a file called FILENAME.

需用 --with-trace-refs 编译选项来配置 Python。

3.11 新版功能.