1. 命令行和环境 — Python 文档
1. 命令行和环境
CPython 解释器会扫描命令行和环境以进行各种设置。
1.1. 命令行
调用 Python 时,您可以指定以下任何选项:
python [-bBdEhiIOqsSuvVWx?] [-c command | -m module-name | script | - ] [args]
当然,最常见的用例是对脚本的简单调用:
python myscript.py
1.1.1. 接口选项
解释器接口类似于 UNIX shell 的接口,但提供了一些额外的调用方法:
- 当使用连接到 tty 设备的标准输入调用时,它会提示输入命令并执行它们直到 EOF(文件结束字符,您可以在 UNIX 或 上使用 Ctrl-D 生成该字符) Ctrl-Z,在 Windows 上 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 的开头(允许模块在该目录中作为顶级模块导入)。
- -m <module-name>
在 sys.path 中搜索命名模块并将其内容作为 __main__ 模块执行。
由于参数是 模块 名称,您不能提供文件扩展名 (
.py
)。 模块名称应该是一个有效的绝对 Python 模块名称,但实现可能并不总是强制这样做(例如 它可能允许您使用包含连字符的名称)。包名称(包括命名空间包)也是允许的。 当提供包名而不是普通模块时,解释器将执行
<pkg>.__main__
作为主模块。 这种行为特意类似于处理作为脚本参数传递给解释器的目录和 zip 文件。笔记
此选项不能与用 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
在 3.1 版更改: 提供包名称以运行
__main__
子模块。在 3.4 版更改:也支持 命名空间包
- <script>
执行包含在 script 中的 Python 代码,它必须是一个文件系统路径(绝对或相对),引用 Python 文件、包含
__main__.py
文件的目录或包含 [ X211X] 文件。如果给出此选项,sys.argv 的第一个元素将是命令行中给出的脚本名称。
如果脚本名称直接引用 Python 文件,则将包含该文件的目录添加到 sys.path 的开头,并且该文件作为 __main__ 模块执行。
如果脚本名称引用目录或 zip 文件,则脚本名称将添加到 sys.path 的开头,并且该位置的
__main__.py
文件将作为 __main__[ X183X] 模块。-I 选项可用于在隔离模式下运行脚本,其中 sys.path 既不包含脚本目录也不包含用户的站点包目录。 所有
PYTHON*
环境变量也被忽略。
如果没有给出接口选项,则隐含 -i,sys.argv[0]
为空字符串(""
),当前目录将添加到 的开头sys.path。 此外,如果在您的平台上可用,选项卡完成和历史编辑会自动启用(请参阅 Readline 配置 )。
在 3.4 版更改: 自动启用选项卡完成和历史编辑。
1.1.2. 通用选项
- -?
-h
--help
- 打印所有命令行选项的简短描述。
- -V
--version 打印 Python 版本号并退出。 示例输出可能是:
Python 3.7.0b2+
当给出两次时,打印有关构建的更多信息,例如:
Python 3.7.0b2+ (3.7:0c076caaa8, Sep 22 2018, 12:04:24) [GCC 6.2.0 20161005]
3.6 版新增:
-VV
选项。
1.1.3. 其他选项
- -B
- 如果给定,Python 将不会尝试在源模块的导入上编写
.pyc
文件。 另见 PYTHONDONTWRITEBYTECODE。
- --check-hash-based-pycs default|always|never
控制基于哈希的
.pyc
文件的验证行为。 参见缓存字节码失效。 当设置为default
时,已检查和未检查的基于哈希的字节码缓存文件将根据其默认语义进行验证。 当设置为always
时,所有基于哈希的.pyc
文件,无论是否选中,都将根据其相应的源文件进行验证。 当设置为never
时,基于哈希的.pyc
文件不会根据其相应的源文件进行验证。基于时间戳的
.pyc
文件的语义不受此选项的影响。
- -d
- 打开解析器调试输出(仅限专家,取决于编译选项)。 另见 PYTHONDEBUG。
- -E
- 忽略所有
PYTHON*
环境变量,例如 PYTHONPATH 和 PYTHONHOME,可以设置。
- -i
当脚本作为第一个参数传递或使用 -c 选项时,执行脚本或命令后进入交互模式,即使 sys.stdin 看起来不是一个终端。 未读取 PYTHONSTARTUP 文件。
当脚本引发异常时,这对于检查全局变量或堆栈跟踪非常有用。 另见 PYTHONINSPECT。
- -I
在隔离模式下运行 Python。 这也意味着 -E 和 -s。 在隔离模式下 sys.path 既不包含脚本的目录,也不包含用户的站点包目录。 所有
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
文件名。
- -q
即使在交互模式下也不显示版权和版本消息。
3.2 版中的新功能。
- -R
打开哈希随机化。 此选项仅在 PYTHONHASHSEED 环境变量设置为
0
时有效,因为默认情况下启用哈希随机化。在以前版本的 Python 上,此选项会打开哈希随机化,因此 str、bytes 和 datetime 的
__hash__()
值会被不可预测的随机值“加盐”。 尽管它们在单个 Python 进程中保持不变,但它们在 Python 的重复调用之间是不可预测的。哈希随机化旨在提供保护,防止由精心选择的输入引起的拒绝服务,这些输入利用 dict 构造的最坏情况性能,O(n^2) 复杂度。 有关详细信息,请参阅 http://www.ocert.org/advisories/ocert-2011-003.html。
PYTHONHASHSEED 允许您为哈希种子密钥设置固定值。
3.7 版更改: 该选项不再被忽略。
3.2.3 版中的新功能。
- -S
- 禁用模块 site 的导入和它所需要的 sys.path 的站点相关操作。 如果稍后显式导入 site,也请禁用这些操作(如果您希望触发它们,请调用 site.main())。
- -u
强制 stdout 和 stderr 流无缓冲。 此选项对标准输入流没有影响。
另见 PYTHONUNBUFFERED。
3.7 版更改: stdout 和 stderr 流的文本层现在是无缓冲的。
- -v
- 每次初始化模块时打印一条消息,显示加载它的位置(文件名或内置模块)。 当给定两次 (
-vv
) 时,为搜索模块时检查的每个文件打印一条消息。 还提供有关退出时模块清理的信息。 另见 PYTHONVERBOSE。
- -W arg
警告控制。 默认情况下,Python 的警告机制将警告消息打印到 sys.stderr。 典型的警告消息具有以下形式:
file:line: category: message
默认情况下,每个警告都会为出现它的每个源代码行打印一次。 此选项控制打印警告的频率。
可以给出多个 -W 选项; 当警告匹配多个选项时,将执行最后一个匹配选项的操作。 无效的 -W 选项将被忽略(不过,在发出第一个警告时会打印一条关于无效选项的警告消息)。
警告也可以使用 PYTHONWARNINGS 环境变量和使用 warnings 模块在 Python 程序中控制。
最简单的设置无条件地将特定操作应用于进程发出的所有警告(即使是那些默认情况下被忽略的警告):
-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
- 跳过源代码的第一行,允许使用非 Unix 形式的
#!cmd
。 这仅适用于特定于 DOS 的 hack。
- -X
保留用于各种特定于实现的选项。 CPython 目前定义了以下可能的值:
-X faulthandler
启用 故障处理程序 ;-X showrefcount
在程序完成时或在交互式解释器中的每个语句之后输出总引用计数和使用的内存块数。 这仅适用于调试版本。-X tracemalloc
开始使用 tracemalloc 模块跟踪 Python 内存分配。 默认情况下,只有最近的帧存储在跟踪的回溯中。 使用-X tracemalloc=NFRAME
以 NFRAME 帧的回溯限制开始跟踪。 有关更多信息,请参阅 tracemalloc.start()。-X showalloccount
程序结束时输出每种类型的已分配对象的总数。 这仅在 Python 构建时定义了COUNT_ALLOCS
时才有效。-X importtime
显示每次导入需要多长时间。 它显示模块名称、累计时间(包括嵌套导入)和自时间(不包括嵌套导入)。 请注意,它的输出在多线程应用程序中可能会损坏。 典型用法是python3 -X importtime -c 'import asyncio'
。 另见 PYTHONPROFILEIMPORTTIME。-X dev
:启用 CPython 的“开发模式”,引入额外的运行时检查,默认情况下启用成本太高。 如果代码正确,它不应该比默认值更冗长:只有在检测到问题时才会发出新警告。 开发者模式的效果:添加
default
警告过滤器,如 -Wdefault
。在内存分配器上安装调试钩子:参见 PyMem_SetupDebugHooks() C 函数。
启用 faulthandler 模块以在崩溃时转储 Python 回溯。
启用 异步调试模式 。
将sys.flags的
dev_mode
属性设置为True
。
-X utf8
为操作系统接口启用 UTF-8 模式,覆盖默认的语言环境感知模式。-X utf8=0
明确禁用 UTF-8 模式(即使它会自动激活)。 有关更多详细信息,请参阅 PYTHONUTF8。
它还允许传递任意值并通过 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
选项。
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 模块(源代码或编译形式)的 zipfiles。 不能从 zipfiles 导入扩展模块。
默认搜索路径取决于安装,但通常以
prefix/lib/pythonversion
开头(请参阅上面的 PYTHONHOME)。 它是 总是 附加到 PYTHONPATH。将在 PYTHONPATH 前面的搜索路径中插入一个附加目录,如上文 接口选项 下所述。 搜索路径可以在 Python 程序中作为变量 sys.path 进行操作。
- PYTHONSTARTUP
- 如果这是一个可读文件的名称,则该文件中的 Python 命令在以交互模式显示第一个提示之前执行。 该文件在执行交互式命令的同一命名空间中执行,以便在其中定义或导入的对象可以在交互式会话中不加限定地使用。 您还可以更改此文件中的提示 sys.ps1 和 sys.ps2 以及钩子 sys.__interactivehook__。
- PYTHONBREAKPOINT
如果设置了它,它会使用点分路径表示法命名一个可调用对象。 包含 callable 的模块将被导入,然后 callable 将由 sys.breakpointhook() 的默认实现运行,它本身由内置的 breakpoint() 调用。 如果未设置,或设置为空字符串,则相当于值“pdb.set_trace”。 将此设置为字符串“0”会导致 sys.breakpointhook() 的默认实现除了立即返回之外什么都不做。
3.7 版中的新功能。
- PYTHONINSPECT
如果将其设置为非空字符串,则等效于指定 -i 选项。
这个变量也可以通过 Python 代码修改,使用 os.environ 在程序终止时强制检查模式。
- PYTHONUNBUFFERED
- 如果将其设置为非空字符串,则等效于指定 -u 选项。
- PYTHONCASEOK
- 如果设置,Python 将忽略 import 语句中的大小写。 这仅适用于 Windows 和 OS X。
- PYTHONDONTWRITEBYTECODE
- 如果将其设置为非空字符串,Python 将不会尝试在导入源模块时写入
.pyc
文件。 这等效于指定 -B 选项。
- PYTHONHASHSEED
如果此变量未设置或设置为
random
,则使用随机值作为 str、bytes 和 datetime 对象的散列的种子。如果 PYTHONHASHSEED 被设置为一个整数值,它被用作一个固定种子,用于生成哈希随机化所涵盖的类型的 hash()。
它的目的是允许可重复的散列,例如用于解释器本身的自测,或允许一组 python 进程共享散列值。
整数必须是 [0,4294967295] 范围内的十进制数。 指定值 0 将禁用哈希随机化。
3.2.3 版中的新功能。
- PYTHONIOENCODING
如果这是在运行解释器之前设置的,它将覆盖用于 stdin/stdout/stderr 的编码,语法为
encodingname:errorhandler
。encodingname
和:errorhandler
部分都是可选的,其含义与 str.encode() 中的含义相同。对于标准错误,
:errorhandler
部分被忽略; 处理程序将始终为'backslashreplace'
。3.4 版更改:
encodingname
部分现在是可选的。3.6 版更改: 在 Windows 上,除非还指定了 PYTHONLEGACYWINDWSSTDIO,否则此变量指定的编码对于交互式控制台缓冲区将被忽略。 通过标准流重定向的文件和管道不受影响。
- PYTHONUSERBASE
定义用户基目录,用于计算用户站点包目录和Distutils安装路径的路径
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 回溯。 这相当于 -Xfaulthandler
选项。3.3 版中的新功能。
- PYTHONTRACEMALLOC
如果此环境变量设置为非空字符串,请使用 tracemalloc 模块开始跟踪 Python 内存分配。 该变量的值是存储在跟踪回溯中的最大帧数。 例如,
PYTHONTRACEMALLOC=1
只存储最近的帧。 有关更多信息,请参阅 tracemalloc.start()。3.4 版中的新功能。
- PYTHONPROFILEIMPORTTIME
如果此环境变量设置为非空字符串,Python 将显示每次导入所需的时间。 这完全等同于在命令行上设置
-X importtime
。3.7 版中的新功能。
- 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()
函数领域。
安装调试钩子:
debug
:在 默认内存分配器 之上安装调试钩子。malloc_debug
:与malloc
相同,但也安装调试钩子。pymalloc_debug
:与pymalloc
相同,但也安装调试钩子。
参见 default memory allocators 和 PyMem_SetupDebugHooks() 函数(在 Python 内存分配器上安装调试钩子)。
3.7 版更改: 添加
"default"
分配器。3.6 版中的新功能。
- PYTHONMALLOCSTATS
如果设置为非空字符串,Python 将在每次创建新的 pymalloc 对象 arena 和关闭时打印 pymalloc 内存分配器 的统计信息。
如果 PYTHONMALLOC 环境变量用于强制 C 库的
malloc()
分配器,或者如果 Python 配置没有pymalloc
,则忽略此变量支持。3.6 版更改: 该变量现在也可以在发布模式下编译的 Python 上使用。 如果设置为空字符串,它现在不起作用。
- PYTHONLEGACYWINDOWSFSENCODING
如果设置为非空字符串,则默认文件系统编码和错误模式将分别恢复为 3.6 之前的 'mbcs' 和 'replace' 值。 否则,将使用新的默认值 'utf-8' 和 'surrogatepass'。
这也可以在运行时使用 sys._enablelegacywindowsfsencoding() 启用。
3.6 版新功能: 有关更多详细信息,请参阅 PEP 529。
- PYTHONLEGACYWINDOWSSTDIO
如果设置为非空字符串,则不使用新的控制台读写器。 这意味着 Unicode 字符将根据活动控制台代码页进行编码,而不是使用 utf-8。
如果标准流被重定向(到文件或管道)而不是引用控制台缓冲区,则忽略此变量。
3.6 版中的新功能。
- PYTHONCOERCECLOCALE
如果设置为值
0
,会导致主 Python 命令行应用程序跳过将旧的基于 ASCII 的 C 和 POSIX 语言环境强制转换为更强大的基于 UTF-8 的替代方法。如果此变量未设置 未设置 (或设置为
0
以外的值),则也未设置LC_ALL
语言环境覆盖环境变量,并报告当前语言环境对于LC_CTYPE
类别是默认的C
语言环境,或者明确的基于 ASCII 的POSIX
语言环境,那么 Python CLI 将尝试为 [ X378X] 类别在加载解释器运行时之前列出的顺序:C.UTF-8
C.utf8
UTF-8
如果设置这些语言环境类别之一成功,则在 Python 运行时初始化之前,
LC_CTYPE
环境变量也将在当前进程环境中进行相应设置。 这确保除了被解释器本身和在同一进程中运行的其他区域设置感知组件(例如 GNUreadline
库)看到之外,更新的设置也可以在子进程中看到(无论是否或者这些进程是否正在运行 Python 解释器),以及查询环境而不是当前 C 语言环境的操作(例如 Python 自己的 locale.getdefaultlocale())。配置这些语言环境之一(显式或通过上述隐式语言环境强制)自动为 sys.stdin 和 sys.stdout 启用
surrogateescape
错误处理程序 (sys.stderr 继续使用backslashreplace
,就像在任何其他语言环境中一样)。 可以像往常一样使用 PYTHONIOENCODING 覆盖此流处理行为。出于调试目的,设置
PYTHONCOERCECLOCALE=warn
将导致 Python 在stderr
上发出警告消息,如果语言环境强制激活,或者如果 将 触发强制的语言环境仍然存在在 Python 运行时初始化时处于活动状态。另请注意,即使区域设置强制被禁用,或者无法找到合适的目标区域设置,PYTHONUTF8 在基于 ASCII 的旧区域设置中仍将默认激活。 必须禁用这两个功能才能强制解释器对系统接口使用
ASCII
而不是UTF-8
。3.7 版新功能:请参阅 PEP 538 了解更多详情。
- PYTHONDEVMODE
如果此环境变量设置为非空字符串,则启用 CPython“开发模式”。 请参阅 -X
dev
选项。3.7 版中的新功能。
- PYTHONUTF8
如果设置为
1
,则启用解释器的 UTF-8 模式,其中UTF-8
用作系统界面的文本编码,无论当前的区域设置如何。这意味着:
sys.getfilesystemencoding() 返回
'UTF-8'
(忽略区域设置编码)。locale.getpreferredencoding() 返回
'UTF-8'
(忽略语言环境编码,函数的do_setlocale
参数无效)。sys.stdin、sys.stdout 和 sys.stderr 都使用 UTF-8 作为它们的文本编码,
surrogateescape
]error handler 为 sys.stdin 和 sys.stdout 启用(sys.stderr 继续使用backslashreplace
在默认的语言环境感知模式下)
由于这些较低级别的 API 发生变化,其他较高级别的 API 也表现出不同的默认行为:
命令行参数、环境变量和文件名使用 UTF-8 编码解码为文本。
os.fsdecode() 和 os.fsencode() 使用 UTF-8 编码。
open()、io.open() 和 codecs.open() 默认使用 UTF-8 编码。 但是,默认情况下,它们仍然使用严格的错误处理程序,因此尝试以文本模式打开二进制文件可能会引发异常而不是产生无意义的数据。
请注意,UTF-8 模式下的标准流设置可以被 PYTHONIOENCODING 覆盖(就像它们可以在默认的语言环境感知模式下一样)。
如果设置为
0
,解释器将以其默认的语言环境感知模式运行。在解释器初始化期间设置任何其他非空字符串会导致错误。
如果根本没有设置这个环境变量,那么解释器默认使用当前的语言环境设置, 除非 当前语言环境被标识为传统的基于 ASCII 的语言环境(如 中所述) PYTHONCOERCECLOCALE),并且区域设置强制被禁用或失败。 在这样的传统语言环境中,解释器将默认启用 UTF-8 模式,除非明确指示不要这样做。
也可用作 -X
utf8
选项。3.7 版新功能: 有关更多详细信息,请参阅 PEP 540。
1.2.1. 调试模式变量
设置这些变量仅在 Python 的调试构建中有效,也就是说,如果 Python 配置了 --with-pydebug
构建选项。
- PYTHONTHREADDEBUG
- 如果设置,Python 将打印线程调试信息。
- PYTHONDUMPREFS
- 如果设置,Python 将在关闭解释器后转储仍然存在的对象和引用计数。