1. 命令行和环境

cpython解释器扫描命令行和环境中的各种设置。

CPython implementation detail: 其他实现的命令行方案可能不同。见 其他实现 获取更多资源。

1.1. 命令行

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

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

当然，最常见的用例是对脚本的简单调用：

python myscript.py

1.1.1. 接口选项

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

• 当使用连接到tty设备的标准输入调用时，它会提示输入命令并执行这些命令，直到出现EOF（文件结束字符），您可以使用 Ctrl-D 关于UNIX或 Ctrl-Z, Enter 在Windows上）被读取。

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

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

• 当与调用时 -c command ，它执行以下给定的python语句： 命令 . 在这里 命令 可以包含多个用换行符分隔的语句。前面的空白在python语句中非常重要！

• 当与调用时 -m module-name ，给定的模块位于python模块路径上，并作为脚本执行。

在非交互模式下，在执行整个输入之前对其进行分析。

接口选项终止解释器使用的选项列表，所有连续参数将以 sys.argv --注意第一个元素，下标零 (sys.argv[0] ）是反映程序源的字符串。

-c <command>

在中执行python代码 命令 . 命令 可以是用换行符分隔的一个或多个语句，其前导空格与正常模块代码中的空格相同。

如果给定此选项，则 sys.argv 将 "-c" 当前目录将添加到 sys.path （允许将该目录中的模块作为顶级模块导入）。

提出一个 auditing event cpython.run_command 带着论证 command .

-m <module-name>

搜索 sys.path 并将其内容作为 __main__ 模块。

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

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

注解

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

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

-I 选项可用于在独立模式下运行脚本，其中 sys.path 既不包含当前目录，也不包含用户的网站包目录。全部 PYTHON* 环境变量也被忽略。

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

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

提出一个 auditing event cpython.run_module 带着论证 module-name .

参见

runpy.run_module()

可直接用于python代码的等效功能

PEP 338 --以脚本形式执行模块

在 3.1 版更改: 提供要运行的包名称 __main__ 子模块。

在 3.4 版更改: 也支持命名空间包

-

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

如果给定此选项，则 sys.argv 将 "-" 当前目录将添加到 sys.path .

提出一个 auditing event cpython.run_stdin 没有参数。

<script>

执行中包含的python代码 脚本 ，它必须是文件系统路径（绝对或相对），引用python文件，包含 __main__.py 文件，或包含 __main__.py 文件。

如果给定此选项，则 sys.argv 将是命令行上给定的脚本名称。

如果脚本名直接引用Python文件，则包含该文件的目录将添加到 sys.path ，文件作为 __main__ 模块。

如果脚本名引用目录或zip文件，则脚本名将添加到 sys.path 以及 __main__.py 该位置中的文件作为 __main__ 模块。

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

提出一个 auditing event cpython.run_file 带着论证 filename .

参见

runpy.run_path()

可直接用于python代码的等效功能

如果没有提供接口选项， -i 暗示， sys.argv[0] 是空字符串 ("" ）当前目录将添加到 sys.path . 此外，如果在您的平台上可用，则会自动启用选项卡完成和历史记录编辑（请参见 读线配置 ）

参见

调用解释器

在 3.4 版更改: 自动启用选项卡完成和历史编辑。

1.1.2. 通用选项

-?

-h

--help

打印所有命令行选项的简短描述。

-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 具有 int . 当选项被给予两次时发出错误 (-bb ）

在 3.5 版更改: 影响比较 bytes 具有 int .

-B

如果给定，python不会尝试写入 .pyc 导入源模块时的文件。也见 PYTHONDONTWRITEBYTECODE .

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

控制基于hash的验证行为 .pyc 文件夹。见 缓存字节码无效 . 当设置为 default 检查和未检查的基于hash的字节码缓存文件将根据其默认语义进行验证。当设置为 always ，所有基于hash的 .pyc 文件，无论是选中还是未选中，都将根据其对应的源文件进行验证。当设置为 never 基于hash的 .pyc 没有根据相应的源文件验证文件。

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

-d

打开解析器调试输出（仅适用于专家，具体取决于编译选项）。也见 PYTHONDEBUG .

-E

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

-i

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

这对于在脚本引发异常时检查全局变量或堆栈跟踪很有用。也见 PYTHONINSPECT .

-I

以隔离模式运行python。这也意味着孤立模式下的-e和-s。 sys.path 既不包含脚本的目录，也不包含用户的站点包目录。所有 PYTHON* 环境变量也被忽略。可能会施加进一步的限制，以防止用户注入恶意代码。

3.4 新版功能.

-O

移除assert语句和任何以值为条件的代码 __debug__ . 为编译文件增加文件名 (bytecode ）通过添加 .opt-1 之前 .pyc 延伸部分（参见 PEP 488 ）也见 PYTHONOPTIMIZE .

在 3.5 版更改: 修改 .pyc 文件名依据 PEP 488 .

-OO

做 -O 并丢弃docstring。为编译文件增加文件名 (bytecode ）通过添加 .opt-2 之前 .pyc 延伸部分（参见 PEP 488 ）

在 3.5 版更改: 修改 .pyc 文件名依据 PEP 488 .

-q

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

3.2 新版功能.

-R

启用hash随机化。只有当 PYTHONHASHSEED 环境变量设置为 0 ，因为默认情况下已启用hash随机化。

在以前的Python版本中，此选项启用哈希随机化，以便 __hash__() str和bytes对象的值是用一个不可预测的随机值“转换”的。尽管它们在一个单独的Python进程中保持不变，但是在重复调用Python之间它们是不可预测的。

hash随机化是为了防止由于精心选择的输入而导致的拒绝服务，这些输入利用了dict构造的最坏情况性能，即O（n^2）复杂性。有关详细信息，请参阅http://www.ocert.org/advisories/ocert-2011-003.html。

PYTHONHASHSEED 允许您设置hash种子机密的固定值。

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

3.2.3 新版功能.

-s

不要添加 user site-packages directory 到 sys.path .

参见

PEP 370 --每用户站点包目录

-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 . 典型警告消息的格式如下：

file:line: category: message

默认情况下，每个警告对于其发生的每一个源行打印一次。此选项控制打印警告的频率。

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

也可以使用 PYTHONWARNINGS 环境变量和来自使用 warnings 模块。

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

-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

操作名称可以根据需要缩写（例如 -Wi ， -Wd ， -Wa ， -We ）解释器将它们解析为适当的操作名。

见 警告过滤器 和 描述警告筛选器 了解更多详细信息。

-x

跳过源代码的第一行，允许使用 #!cmd . 这仅适用于DOS特定的黑客。

-X

为各种特定于实现的选项保留。cpython当前定义了以下可能的值：

• -X faulthandler 使能 faulthandler ；

• -X showrefcount 当程序完成时或在交互解释器中的每个语句之后输出总引用计数和已用内存块的数目。这只适用于调试版本。

• -X tracemalloc 要开始跟踪python内存分配，请使用 tracemalloc 模块。默认情况下，只有最新的帧存储在跟踪的跟踪中。使用 -X tracemalloc=NFRAME 开始跟踪的回溯限制为 NFRAME 框架。查看 tracemalloc.start() 更多信息。

• -X importtime 显示每次导入需要多长时间。它显示模块名称、累计时间（包括嵌套导入）和自时间（不包括嵌套导入）。请注意，在多线程应用程序中，它的输出可能会中断。典型用法是 python3 -X importtime -c 'import asyncio' .另请参见 PYTHONPROFILEIMPORTTIME .

• -X dev ：启用 Python Development Mode ，引入额外的运行时检查，这些检查成本太高，无法默认启用。

• -X utf8 启用 Python UTF-8 Mode 。 -X utf8=0 显式禁用 Python UTF-8 Mode (即使它本来会自动激活)。

• -X pycache_prefix=PATH 启用写入 .pyc 文件的根目录是给定目录，而不是代码树。也见 PYTHONPYCACHEPREFIX .

它还允许传递任意值并通过 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 close() io.IOBase

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

这个 -X showalloccount 选项已被删除。

Deprecated since version 3.9, removed in version 3.10: 这个 -X oldparser 选择权。

1.1.4. 你不应该使用的选项

-J

保留供使用 Jython.

1.2. 环境变量

这些环境变量会影响python的行为，它们在命令行开关（而不是-e或-i）之前进行处理。通常情况下，命令行开关会在发生冲突时覆盖环境变量。

PYTHONHOME

更改标准python库的位置。默认情况下，在 {prefix}/lib/python{version} 和 {exec_prefix}/lib/python{version} 在哪里 {prefix} 和 {exec_prefix} 是安装相关目录，都默认为 /usr/local .

什么时候？ PYTHONHOME 设置为单个目录，其值将同时替换两个目录 {prefix} 和 {exec_prefix} . 要为这些指定不同的值，请设置 PYTHONHOME 到 {prefix}:{exec_prefix} .

PYTHONPATH

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

除了普通目录，个人 PYTHONPATH 条目可以引用包含纯python模块的zipfiles（以源代码或编译格式）。扩展模块不能从zipfiles导入。

默认搜索路径取决于安装，但通常以 {prefix}/lib/python{version} （见 PYTHONHOME 以上）。它是 总是 追加到 PYTHONPATH .

将在前面的搜索路径中插入一个附加目录 PYTHONPATH 如上所述 接口选项 . 搜索路径可以在python程序中作为变量进行操作。 sys.path .

PYTHONPLATLIBDIR

如果设置为非空字符串，它将重写 sys.platlibdir 价值。

3.9 新版功能.

PYTHONSTARTUP

如果这是可读文件的名称，则在交互模式下显示第一个提示之前，将执行该文件中的python命令。该文件在执行交互命令的同一命名空间中执行，以便在交互会话中无需限定即可使用其中定义或导入的对象。您还可以更改提示 sys.ps1 和 sys.ps2 钩子 sys.__interactivehook__ 在此文件中。

提出一个 auditing event cpython.run_startup 带着论证 filename .

PYTHONOPTIMIZE

如果将其设置为非空字符串，则相当于指定 -O 选择权。如果设置为整数，则相当于指定 -O 多次。

PYTHONBREAKPOINT

如果设置了该选项，则使用点路径表示法命名可调用文件。将导入包含可调用的模块，然后按默认实现运行可调用 sys.breakpointhook() 它本身是由内置的 breakpoint() .如果未设置或设置为空字符串，则等于值“pdb.set_trace”。将其设置为字符串“0”将导致 sys.breakpointhook() 什么都不做，只是马上回来。

3.7 新版功能.

PYTHONDEBUG

如果将其设置为非空字符串，则相当于指定 -d 选择权。如果设置为整数，则相当于指定 -d 多次。

PYTHONINSPECT

如果将其设置为非空字符串，则相当于指定 -i 选择权。

也可以使用python代码修改此变量 os.environ 在程序终止时强制检查模式。

PYTHONUNBUFFERED

如果将其设置为非空字符串，则相当于指定 -u 选择权。

PYTHONVERBOSE

如果将其设置为非空字符串，则相当于指定 -v 选择权。如果设置为整数，则相当于指定 -v 多次。

PYTHONCASEOK

如果设置了该选项，则python将忽略 import 声明。这只适用于Windows和OS X。

PYTHONDONTWRITEBYTECODE

如果将其设置为非空字符串，则python不会尝试写入 .pyc 导入源模块时的文件。这相当于指定 -B 选择权。

PYTHONPYCACHEPREFIX

如果设置了此选项，python将写入 .pyc 位于此路径的镜像目录树中的文件，而不是位于 __pycache__ 源码树中的目录。这相当于指定 -X pycache_prefix=PATH 选择权。

3.8 新版功能.

PYTHONHASHSEED

如果此变量未设置或设置为 random ，随机值用于为str和bytes对象的散列种子。

如果 PYTHONHASHSEED 设置为整数值，它用作生成hash随机化所覆盖类型的hash（）的固定种子。

它的目的是允许可重复的散列，例如对解释器本身进行自测，或者允许一组Python进程共享散列值。

整数必须是范围内的十进制数 [04294967295] . 指定值0将禁用hash随机化。

3.2.3 新版功能.

PYTHONIOENCODING

如果在运行解释器之前设置了这个值，它将在语法中重写stdin/stdout/stderr使用的编码。 encodingname:errorhandler . 两个 encodingname 以及 :errorhandler 零件是可选的，具有与中相同的含义 str.encode() .

对于STDRR， :errorhandler 忽略部分；处理程序将始终 'backslashreplace' .

在 3.4 版更改: 这个 encodingname 零件现在是可选的。

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

PYTHONNOUSERSITE

如果设置了此选项，python将不会添加 user site-packages directory 到 sys.path .

参见

PEP 370 --每用户站点包目录

PYTHONUSERBASE

定义 user base directory ，用于计算 user site-packages directory 和 Distutils installation paths 对于 python setup.py install --user .

参见

PEP 370 --每用户站点包目录

PYTHONEXECUTABLE

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

PYTHONWARNINGS

这相当于 -W 选择权。如果设置为逗号分隔的字符串，则相当于指定 -W 多次，列表后面的过滤器优先于列表前面的过滤器。

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

PYTHONWARNINGS=default  # Warn once per call location
PYTHONWARNINGS=error    # Convert to exceptions
PYTHONWARNINGS=always   # Warn every time
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 模块。变量的值是记录道回溯中存储的最大帧数。例如， PYTHONTRACEMALLOC=1 仅存储最近的帧。见 tracemalloc.start() 更多信息。

3.4 新版功能.

PYTHONPROFILEIMPORTTIME

如果将此环境变量设置为非空字符串，则python将显示每次导入所需的时间。这完全等同于设置 -X importtime 在命令行上。

3.7 新版功能.

PYTHONASYNCIODEBUG

如果此环境变量设置为非空字符串，请启用 debug mode 的 asyncio 模块。

3.4 新版功能.

PYTHONMALLOC

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

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

• default 使用 default memory allocators .

• malloc 使用 malloc() 所有域的C库函数 (PYMEM_DOMAIN_RAW ， PYMEM_DOMAIN_MEM ， PYMEM_DOMAIN_OBJ ）

• pymalloc 使用 pymalloc allocator 对于 PYMEM_DOMAIN_MEM 和 PYMEM_DOMAIN_OBJ 域和使用 malloc() 功能 PYMEM_DOMAIN_RAW 领域。

安装调试挂钩：

• debug ：在 default memory allocators .

• malloc_debug 一样 malloc 但也要安装调试挂钩。

• pymalloc_debug 一样 pymalloc 但也要安装调试挂钩。

见 default memory allocators 以及 PyMem_SetupDebugHooks() 函数（在python内存分配器上安装调试挂钩）。

在 3.7 版更改: 增加了 "default" 分配器。

3.6 新版功能.

PYTHONMALLOCSTATS

如果设置为非空字符串，python将打印 pymalloc memory allocator 每次创建新的PymalLoc对象竞技场时，以及关闭时。

如果 PYTHONMALLOC 环境变量用于强制 malloc() C库的分配器，或者如果在没有 pymalloc 支持。

在 3.6 版更改: 这个变量现在也可以在以发布模式编译的Python上使用。如果设置为空字符串，则现在没有效果。

PYTHONLEGACYWINDOWSFSENCODING

如果设置为非空字符串，则默认为 filesystem encoding and error handler 模式将分别恢复到其3.6版本之前的值‘MBCS’和‘REPLACE’。否则，将使用新的默认值‘utf-8’和‘surogue atepass’。

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

Availability ：Windows。

3.6 新版功能: 见 PEP 529 了解更多详细信息。

PYTHONLEGACYWINDOWSSTDIO

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

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

Availability ：Windows。

3.6 新版功能.

PYTHONCOERCECLOCALE

如果设置为值 0 ，使主python命令行应用程序跳过将基于ASCII的C和POSIX区域设置强制为更强大的基于UTF-8的替代方案。

如果这个变量是 not 设置（或设置为除 0 ） LC_ALL 也未设置locale override环境变量，并且为 LC_CTYPE 类别不是默认的 C 区域设置，否则显式基于ASCII POSIX 然后，python cli将尝试为 LC_CTYPE 按照加载解释器运行时之前列出的顺序分类：

• C.UTF-8

• C.utf8

• UTF-8

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

配置这些区域设置之一（显式或通过上述隐式区域设置强制）将自动启用 surrogateescape error handler 对于 sys.stdin 和 sys.stdout (sys.stderr 继续使用 backslashreplace 就像在其他地方一样）。此流处理行为可以使用重写 PYTHONIOENCODING 像往常一样。

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

还要注意，即使禁用了区域设置强制，或者找不到合适的目标区域设置， PYTHONUTF8 默认情况下，仍将在基于ASCII的旧区域设置中激活。必须禁用这两个功能才能强制解释程序使用 ASCII 而不是 UTF-8 用于系统接口。

Availability ： * 尼克斯。

3.7 新版功能: 见 PEP 538 了解更多详细信息。

PYTHONDEVMODE

如果此环境变量设置为非空字符串，请启用 Python Development Mode ，引入额外的运行时检查，这些检查成本太高，无法默认启用。

3.7 新版功能.

PYTHONUTF8

如果设置为 1 ，启用 Python UTF-8 Mode 。

如果设置为 0 ，禁用 Python UTF-8 Mode 。

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

3.7 新版功能.

1.2.1. 调试模式变量

设置这些变量只在Python的调试版本中起作用。

PYTHONTHREADDEBUG

如果设置，python将打印线程调试信息。

需要用 --with-pydebug 建立选项。

PYTHONDUMPREFS

如果设置了，则在关闭解释器后，python将转储对象并保持引用计数活动。

需要用 --with-trace-refs 建立选项。