Skip to main content

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 或在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 的开始(允许该目录中的模块作为顶级模块导入)。

-m <module-name>

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

由于参数是 module 名称,因此您不能给出文件扩展名(.py)。模块名称应该是有效的绝对Python模块名称,但是实现可能并不总是强制这样做(例如,它可能允许您使用包含连字符的名称)。

还允许包名称(包括命名空间包)。当提供包名称而不是普通模块时,解释器将执行 <pkg>.__main__ 作为主模块。此行为故意类似于作为脚本参数传递到解释器的目录和zip文件的处理。

注解

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

如果给出此选项,sys.argv 的第一个元素将是模块文件的完整路径(在定位模块文件时,第一个元素将被设置为 "-m")。与 -c 选项一样,当前目录将添加到 sys.path 的开始。

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

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

参见

runpy.run_module()

等价功能直接可用于Python代码

PEP 338 - 将模块作为脚本执行

在 3.1 版更改: 提供程序包名称以运行 __main__ 子模块。

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

-

从标准输入(sys.stdin)读取命令。如果标准输入是终端,则暗示 -i

如果给出此选项,sys.argv 的第一个元素将是 "-",并且当前目录将添加到 sys.path 的开始。

<script>

执行 script 中包含的Python代码,它必须是指向Python文件,包含 __main__.py 文件的目录或包含 __main__.py 文件的zipfile的文件系统路径(绝对或相对)。

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

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

如果脚本名称引用目录或zip文件,则将脚本名称添加到 sys.path 的开头,并将该位置中的 __main__.py 文件作为 __main__ 模块执行。

参见

runpy.run_path()

等价功能直接可用于Python代码

如果没有给出接口选项,则暗示 -isys.argv[0] 是空字符串(""),并且当前目录将被添加到 sys.path 的开始。此外,如果在您的平台上可用(参见 Readline配置),将自动启用制表符完成和历史记录编辑。

参见

调用翻译

在 3.4 版更改: 自动启用制表符完成和历史记录编辑。

1.1.2. 通用选项

-?
-h
--help

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

-V
--version

打印Python版本号并退出。示例输出可以:

Python 3.6.0b2+

当给出两次时,打印关于构建的更多信息,如:

Python 3.6.0b2+ (3.6:84a3c5003510+, Oct 26 2016, 02:33:55)
[GCC 6.2.0 20161005]

3.6 新版功能: -VV 选项。

1.1.3. 其他选项

-b

当将 bytesbytearraystrbytesint 进行比较时发出警告。在给出选项两次(-bb)时发出错误。

在 3.5 版更改: 影响 bytesint 的比较。

-B

如果给出,Python将不会尝试在导入源模块时写入 .pyc 文件。参见 PYTHONDONTWRITEBYTECODE

-d

打开解析器调试输出(仅适用于向导,具体取决于编译选项)。参见 PYTHONDEBUG

-E

忽略所有 PYTHON* 环境变量,例如 PYTHONPATHPYTHONHOME,可能会设置。

-i

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

这可以用于在脚本引发异常时检查全局变量或堆栈跟踪。参见 PYTHONINSPECT

-I

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

3.4 新版功能.

-O

打开基本优化。参见 PYTHONOPTIMIZE

-OO

除了 -O 优化之外,还要丢弃文档字符串。

-q

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

3.2 新版功能.

-R

保持兼容性。在Python 3.3及更高版本中,hash随机化默认情况下是开启的。

在以前的Python版本中,此选项打开哈希随机化,以便str,bytes和datetime的 __hash__() 值被“salted”,具有不可预测的随机值。尽管它们在单个Python进程中保持不变,但是在重复调用Python之前是不可预测的。

哈希随机化旨在提供保护以防止由仔细选择的输入引起的服务拒绝,其利用了字符构造的最坏情况性能O(n ^ 2)复杂度。有关详细信息,请参阅 http://www.ocert.org/advisories/ocert-2011-003.html

PYTHONHASHSEED 允许您为散列种子密码设置固定值。

3.2.3 新版功能.

-s

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

参见

PEP 370 - 每个用户site-packages目录

-S

禁用导入模块 site 和它需要的 sys.path 的站点相关操作。如果稍后显式导入 site,也禁用这些操作(如果您希望触发它们,请调用 site.main())。

-u

强制stdout和stderr流(可用作它们的 buffer 属性)的二进制层是无缓冲的。如果写入控制台,则文本I/O层仍将进行行缓冲,如果重定向到非交互式文件,则文本I/O层仍将进行块缓冲。

参见 PYTHONUNBUFFERED

-v

每次模块初始化时打印消息,显示从中加载模块的位置(文件名或内置模块)。当给出两次(-vv)时,为在搜索模块时检查的每个文件打印一条消息。还提供退出时模块清理的信息。参见 PYTHONVERBOSE

-W arg

警告控制。 Python的警告机制默认向 sys.stderr 打印警告消息。典型的警告消息具有以下形式:

file:line: category: message

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

可以给出多个 -W 选项;当警告匹配多个选项时,将执行上一个匹配选项的操作。无效的 -W 选项被忽略(但是,当发出第一个警告时,将打印有关无效选项的警告消息)。

警告也可以在Python程序中使用 warnings 模块进行控制。

参数的最简单形式是以下动作字符串之一(或唯一的缩写):

ignore

忽略所有警告。

default

显式请求默认行为(每个源行打印一次警告)。

all

在每次发生时打印警告(如果对同一源行重复触发警告,例如在循环内,可能会生成许多消息)。

module

仅在每个模块第一次出现时打印每个警告。

once

仅在程序第一次出现时打印每个警告。

error

引发异常而不是打印警告消息。

参数的完整形式是:

action:message:category:module:line

这里,action 如上所述,但仅适用于与剩余字段匹配的消息。空字段匹配所有值;可以省略拖尾空字段。 message 字段与打印的警告消息的开始相匹配;此匹配不区分大小写。 category 字段与警告类别匹配。这必须是类名;该匹配测试消息的实际警告类别是否是指定警告类别的子类。必须提供完整的类名。 module 字段与(完全限定)模块名称匹配;此匹配区分大小写。 line 字段与行号匹配,其中零匹配所有行号,因此等效于省略的行号。

参见

warnings - 警告模块

PEP 230 - 警告框架

PYTHONWARNINGS

-x

跳过源的第一行,允许使用非Unix形式的 #!cmd。这只适用于DOS特定的黑客。

注解

错误消息中的行号将关闭一。

-X

保留用于各种实现特定的选项。 CPython目前定义了以下可能的值:

  • -X faulthandler 启用 faulthandler

  • -X showrefcount 以启用总引用计数和内存块的输出(仅适用于调试版本);

  • -X tracemalloc 使用 tracemalloc 模块开始跟踪Python内存分配。默认情况下,只有最近的帧存储在跟踪的追踪中。使用 -X tracemalloc=NFRAMENFRAME 帧的追溯限制开始跟踪。有关详细信息,请参阅 tracemalloc.start()

  • -X showalloccount 启用每个类型的已分配对象的总计数的输出(仅在使用定义的 COUNT_ALLOCS 构建时才有效);

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

在 3.2 版更改: 现在允许使用CPython传递 -X

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

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

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

1.1.4. 不应该使用的选项

-J

保留供 Jython 使用。

1.2. 环境变量

这些环境变量影响Python的行为,它们在除了-E或-I之外的命令行开关之前被处理。通常,命令行开关覆盖存在冲突的环境变量。

PYTHONHOME

更改标准Python库的位置。默认情况下,在 prefix/lib/pythonversionexec_prefix/lib/pythonversion 中搜索库,其中 prefixexec_prefix 是安装相关的目录,都默认为 /usr/local

PYTHONHOME 设置为单个目录时,其值将替换 prefixexec_prefix。要为这些值指定不同的值,请将 PYTHONHOME 设置为 prefix:exec_prefix

PYTHONPATH

扩充模块文件的默认搜索路径。格式与shell的 PATH 相同:由 os.pathsep 分隔的一个或多个目录路径名(例如,Unix上的冒号或Windows上的分号)。默认忽略不存在的目录。

除了正常目录,单个 PYTHONPATH 条目可以引用包含纯Python模块(源代码或编译形式)的zip文件。无法从zip文件导入扩展模块。

默认搜索路径是安装相关的,但通常从 prefix/lib/pythonversion 开始(参见上面的 PYTHONHOME)。它是附加到 PYTHONPATHalways

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

PYTHONSTARTUP

如果这是可读文件的名称,则在交互式模式下显示第一个提示之前,将执行该文件中的Python命令。该文件在执行交互式命令的同一命名空间中执行,使得在其中定义或导入的对象可以在交互式会话中无限制地使用。您还可以更改此文件中的提示 sys.ps1sys.ps2 以及挂钩 sys.__interactivehook__

PYTHONOPTIMIZE

如果这被设置为非空字符串,它等效于指定 -O 选项。如果设置为整数,则相当于指定 -O 多次。

PYTHONDEBUG

如果这被设置为非空字符串,它等效于指定 -d 选项。如果设置为整数,则相当于指定 -d 多次。

PYTHONINSPECT

如果这被设置为非空字符串,它等效于指定 -i 选项。

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

PYTHONUNBUFFERED

如果这被设置为非空字符串,它等效于指定 -u 选项。

PYTHONVERBOSE

如果这被设置为非空字符串,它等效于指定 -v 选项。如果设置为整数,则相当于指定 -v 多次。

PYTHONCASEOK

如果设置了此项,Python会忽略 import 语句中的大小写。这只适用于Windows和OS X.

PYTHONDONTWRITEBYTECODE

如果设置为非空字符串,Python将不会尝试在导入源模块时写入 .pyc.pyo 文件。这相当于指定 -B 选项。

PYTHONHASHSEED

如果未设置此变量或将其设置为 random,则使用随机值为str,bytes和datetime对象的散列进行种子。

如果 PYTHONHASHSEED 被设置为整数值,则它被用作用于生成由哈希随机化覆盖的类型的hash()的固定种子。

它的目的是允许可重复的哈希,例如为解释器本身的selftest,或允许一组python进程共享哈希值。

整数必须是范围[0,4294967295]中的十进制数。指定值0将禁用哈希随机化。

3.2.3 新版功能.

PYTHONIOENCODING

如果在运行解释器之前设置它,它将在语法 encodingname:errorhandler 中覆盖用于stdin/stdout/stderr的编码。 encodingname:errorhandler 部分都是任选的并且具有与 str.encode() 中相同的含义。

对于stderr,:errorhandler 部分被忽略;处理程序将始终是 'backslashreplace'

在 3.4 版更改: encodingname 部分现在是可选的。

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

PYTHONNOUSERSITE

如果设置了,Python将不会将 user site-packages directory 添加到 sys.path

参见

PEP 370 - 每个用户site-packages目录

PYTHONUSERBASE

定义 user base directory,用于计算 user site-packages directory 的路径,Distutils安装路径 用于 python setup.py install --user

参见

PEP 370 - 每个用户site-packages目录

PYTHONEXECUTABLE

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

PYTHONWARNINGS

这相当于 -W 选项。如果设置为逗号分隔的字符串,则相当于多次指定 -W

PYTHONFAULTHANDLER

如果此环境变量设置为非空字符串,则在启动时调用 faulthandler.enable():为 SIGSEGVSIGFPESIGABRTSIGBUSSIGILL 信号安装处理程序以转储Python回溯。这相当于 -X faulthandler 选项。

3.3 新版功能.

PYTHONTRACEMALLOC

如果此环境变量设置为非空字符串,请使用 tracemalloc 模块开始跟踪Python内存分配。变量的值是存储在跟踪的追溯中的最大帧数。例如,PYTHONTRACEMALLOC=1 仅存储最近的帧。有关详细信息,请参阅 tracemalloc.start()

3.4 新版功能.

PYTHONASYNCIODEBUG

如果此环境变量设置为非空字符串,请启用 asyncio 模块的 调试模式

3.4 新版功能.

PYTHONMALLOC

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

设置Python使用的内存分配器系列:

安装调试钩子:

  • debug:在默认内存分配器的顶部安装调试挂钩

  • malloc_debug:与 malloc 相同,但也安装调试挂钩

  • pymalloc_debug:与 pymalloc 相同,但也安装调试挂钩

当Python在发布模式下编译时,默认为 pymalloc。当在调试模式下编译时,缺省值为 pymalloc_debug,并且自动使用调试挂接。

如果Python配置没有 pymalloc 支持,pymallocpymalloc_debug 不可用,缺省是 malloc 在释放模式和 malloc_debug 在调试模式。

请参阅Python内存分配器上的调试挂钩的 PyMem_SetupDebugHooks() 函数。

3.6 新版功能.

PYTHONMALLOCSTATS

如果设置为非空字符串,Python将在每次创建新的pymalloc对象竞技场时以及在关闭时打印 pymalloc内存分配器 的统计信息。

如果 PYTHONMALLOC 环境变量用于强制C库的 malloc() 分配器,或者如果Python配置为没有 pymalloc 支持,则忽略此变量。

在 3.6 版更改: 此变量现在也可以用于在发布模式下编译的Python。如果设置为空字符串,它现在没有效果。

PYTHONLEGACYWINDOWSFSENCODING

如果设置为非空字符串,则默认的文件系统编码和错误模式将分别还原为“mbcs”和“replace”的3.6之前的值。否则,使用新的默认值’utf-8’和’surrogatepass’。

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

可用性:Windows

3.6 新版功能: 有关详细信息,请参阅 PEP 529

PYTHONLEGACYWINDOWSIOENCODING

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

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

可用性:Windows

3.6 新版功能.

1.2.1. 调试模式变量

设置这些变量只对Python的调试版本有影响,也就是说,如果Python配置了 --with-pydebug 编译选项。

PYTHONTHREADDEBUG

如果设置,Python将打印线程调试信息。

PYTHONDUMPREFS

如果设置,Python将在关闭解释器后转储对象和引用计数。