subprocess — 子进程管理

源代码: Lib/subprocess.py

---

subprocess 模块允许您生成新进程，连接到它们的输入/输出/错误管道，并获取它们的返回代码。此模块旨在替换一些旧模块和函数

os.system
os.spawn*

有关如何使用 subprocess 模块替换这些模块和函数的信息可在以下章节中找到。

参见

PEP 324 – 提议 subprocess 模块的 PEP

可用性: 非 Android、非 iOS、非 WASI。

该模块在移动平台或WebAssembly 平台上不受支持。

使用 subprocess 模块

调用子进程的推荐方法是使用 run() 函数处理所有它能处理的用例。对于更高级的用例，可以直接使用底层的 Popen 接口。

subprocess.run(args, *, stdin=None, input=None, stdout=None, stderr=None, capture_output=False, shell=False, cwd=None, timeout=None, check=False, encoding=None, errors=None, text=None, env=None, universal_newlines=None, **other_popen_kwargs)

运行 args 描述的命令。等待命令完成，然后返回一个 CompletedProcess 实例。

上面显示的参数仅是最常见的参数，将在下面的 常用参数 中描述（因此在缩写签名中使用了仅限关键字的表示法）。完整的函数签名与 Popen 构造函数的签名大致相同——此函数的大多数参数都传递给该接口。（timeout、input、check 和 capture_output 除外。）

如果 capture_output 为 true，则 stdout 和 stderr 将被捕获。使用时，内部 Popen 对象会自动创建，其 stdout 和 stderr 都设置为 PIPE。不能同时提供 stdout 和 stderr 参数以及 capture_output。如果您希望捕获并将两个流合并为一个，请将 stdout 设置为 PIPE，将 stderr 设置为 STDOUT，而不是使用 capture_output。

可以指定以秒为单位的 timeout，它在内部传递给 Popen.communicate()。如果超时，子进程将被杀死并等待。在子进程终止后，TimeoutExpired 异常将被重新引发。在许多平台 API 上，初始进程创建本身无法中断，因此您无法保证在进程创建所需时间之前看到超时异常。

input 参数传递给 Popen.communicate()，从而传递给子进程的标准输入。如果使用，它必须是字节序列，如果指定了 encoding 或 errors 或 text 为 true，则必须是字符串。使用时，内部 Popen 对象会自动创建，其 stdin 设置为 PIPE，并且不能同时使用 stdin 参数。

如果 check 为 true，并且进程以非零退出代码退出，则将引发 CalledProcessError 异常。该异常的属性包含参数、退出代码以及 stdout 和 stderr（如果它们被捕获）。

如果指定了 encoding 或 errors，或者 text 为 true，则 stdin、stdout 和 stderr 的文件对象将以文本模式打开，使用指定的 encoding 和 errors 或 io.TextIOWrapper 默认值。universal_newlines 参数等同于 text，是为了向后兼容而提供的。默认情况下，文件对象以二进制模式打开。

如果 env 不为 None，它必须是一个定义新进程环境变量的映射；这些变量用于代替继承当前进程环境的默认行为。它直接传递给 Popen。此映射可以是任意平台上的字符串到字符串，或 POSIX 平台上的字节到字节，类似于 os.environ 或 os.environb。

示例：

>>> subprocess.run(["ls", "-l"])  # doesn't capture output
CompletedProcess(args=['ls', '-l'], returncode=0)

>>> subprocess.run("exit 1", shell=True, check=True)
Traceback (most recent call last):
  ...
subprocess.CalledProcessError: Command 'exit 1' returned non-zero exit status 1

>>> subprocess.run(["ls", "-l", "/dev/null"], capture_output=True)
CompletedProcess(args=['ls', '-l', '/dev/null'], returncode=0,
stdout=b'crw-rw-rw- 1 root root 1, 3 Jan 23 16:23 /dev/null\n', stderr=b'')

在 3.5 版本加入。

3.6 版中变更: 添加了 encoding 和 errors 参数

3.7 版中变更: 添加了 text 参数，作为 universal_newlines 更易理解的别名。添加了 capture_output 参数。

3.12 版中变更: 更改了 Windows shell 搜索顺序，针对 shell=True。当前目录和 %PATH% 被替换为 %COMSPEC% 和 %SystemRoot%\System32\cmd.exe。因此，在当前目录中放置名为 cmd.exe 的恶意程序不再有效。

class subprocess.CompletedProcess

run() 的返回值，表示一个已完成的进程。

args

用于启动进程的参数。这可以是一个列表或一个字符串。

returncode

子进程的退出状态。通常，退出状态为 0 表示它成功运行。

负值 -N 表示子进程被信号 N 终止（仅限 POSIX）。

stdout

从子进程捕获的 stdout。一个字节序列，如果调用 run() 时带有编码、错误或 text=True，则为字符串。如果未捕获 stdout，则为 None。

如果您使用 stderr=subprocess.STDOUT 运行进程，stdout 和 stderr 将在此属性中合并，并且 stderr 将为 None。

stderr

从子进程捕获的 stderr。一个字节序列，如果调用 run() 时带有编码、错误或 text=True，则为字符串。如果未捕获 stderr，则为 None。

check_returncode()

如果 returncode 不为零，则引发 CalledProcessError。

在 3.5 版本加入。

subprocess.DEVNULL

一个特殊值，可用作 Popen 的 stdin、stdout 或 stderr 参数，表示将使用特殊文件 os.devnull。

在 3.3 版本加入。

subprocess.PIPE

一个特殊值，可用作 Popen 的 stdin、stdout 或 stderr 参数，表示应打开到标准流的管道。最常与 Popen.communicate() 一起使用。

subprocess.STDOUT

一个特殊值，可用作 Popen 的 stderr 参数，表示标准错误应进入与标准输出相同的句柄。

exception subprocess.SubprocessError

此模块中所有其他异常的基类。

在 3.3 版本加入。

exception subprocess.TimeoutExpired

SubprocessError 的子类，在等待子进程时超时时引发。

cmd

用于生成子进程的命令。

timeout

超时时间（秒）。

output

如果通过 run() 或 check_output() 捕获，则为子进程的输出。否则为 None。无论 text=True 设置如何，只要捕获到任何输出，这始终是 bytes。如果没有观察到输出，它可能保持 None 而不是 b''。

stdout

output 的别名，与 stderr 对称。

stderr

如果通过 run() 捕获，则为子进程的 stderr 输出。否则为 None。无论 text=True 设置如何，只要捕获到 stderr 输出，这始终是 bytes。如果没有观察到 stderr 输出，它可能保持 None 而不是 b''。

在 3.3 版本加入。

3.5 版中变更: 添加了 stdout 和 stderr 属性

exception subprocess.CalledProcessError

SubprocessError 的子类，当由 check_call()、check_output() 或 run() (带 check=True) 运行的进程返回非零退出状态时引发。

returncode

子进程的退出状态。如果进程因信号退出，这将是负信号数。

cmd

用于生成子进程的命令。

output

如果通过 run() 或 check_output() 捕获，则为子进程的输出。否则为 None。

stdout

output 的别名，与 stderr 对称。

stderr

如果通过 run() 捕获，则为子进程的 stderr 输出。否则为 None。

3.5 版中变更: 添加了 stdout 和 stderr 属性

常用参数

为了支持各种用例，Popen 构造函数（和便利函数）接受大量可选参数。对于大多数典型用例，许多这些参数可以安全地保留其默认值。最常用的参数是

args 是所有调用都必需的，它应该是一个字符串或程序参数序列。通常建议提供一个参数序列，因为它允许模块处理任何所需的转义和参数引用（例如，允许文件名中包含空格）。如果传递单个字符串，则 shell 必须为 True (见下文)，否则该字符串必须只是要执行的程序的名称，而不指定任何参数。

stdin, stdout 和 stderr 分别指定了被执行程序的标准输入、标准输出和标准错误文件句柄。有效值为 None, PIPE, DEVNULL, 一个现有文件描述符（正整数）, 以及一个具有有效文件描述符的现有文件对象。在默认设置为 None 的情况下，不会发生重定向。PIPE 表示应该创建一个到子进程的新管道。DEVNULL 表示将使用特殊文件 os.devnull。此外，stderr 可以是 STDOUT，这表示子进程的 stderr 数据应该捕获到与 stdout 相同的 文件句柄中。

如果指定了 encoding 或 errors，或者 text (也称为 universal_newlines) 为真，则文件对象 stdin, stdout 和 stderr 将以文本模式打开，使用调用中指定的 encoding 和 errors，或者 io.TextIOWrapper 的默认值。

对于 stdin，输入中的换行符 '\n' 将转换为默认的行分隔符 os.linesep。对于 stdout 和 stderr，输出中的所有换行符都将转换为 '\n'。更多信息请参阅 io.TextIOWrapper 类的文档，当其构造函数的 newline 参数为 None 时。

如果未使用文本模式，stdin、stdout 和 stderr 将作为二进制流打开。不执行编码或行尾转换。

3.6 版中变更: 添加了 encoding 和 errors 参数。

3.7 版中变更: 添加了 text 参数作为 universal_newlines 的别名。

备注

文件对象 Popen.stdin、Popen.stdout 和 Popen.stderr 的 newlines 属性不会被 Popen.communicate() 方法更新。

如果 shell 为 True，则指定的命令将通过 shell 执行。这在您主要使用 Python 来增强对大多数系统 shell 的控制流，但仍希望方便地访问其他 shell 功能（如 shell 管道、文件名通配符、环境变量扩展以及将 ~ 扩展到用户主目录）时非常有用。但是，请注意 Python 本身提供了许多类似 shell 的功能实现（特别是 glob、fnmatch、os.walk()、os.path.expandvars()、os.path.expanduser() 和 shutil）。

3.3 版中变更: 当 universal_newlines 为 True 时，该类使用编码 locale.getpreferredencoding(False) 而不是 locale.getpreferredencoding()。有关此更改的更多信息，请参阅 io.TextIOWrapper 类。

备注

在使用 shell=True 之前，请阅读 安全注意事项 部分。

这些选项，连同所有其他选项，将在 Popen 构造函数文档中更详细地描述。

Popen 构造函数

此模块中的底层进程创建和管理由 Popen 类处理。它提供了很大的灵活性，以便开发人员能够处理便利函数未涵盖的罕见情况。

class subprocess.Popen(args, bufsize=-1, executable=None, stdin=None, stdout=None, stderr=None, preexec_fn=None, close_fds=True, shell=False, cwd=None, env=None, universal_newlines=None, startupinfo=None, creationflags=0, restore_signals=True, start_new_session=False, pass_fds=(), *, group=None, extra_groups=None, user=None, umask=-1, encoding=None, errors=None, text=None, pipesize=-1, process_group=None)

在一个新进程中执行一个子程序。在 POSIX 上，该类使用类似于 os.execvpe() 的行为来执行子程序。在 Windows 上，该类使用 Windows CreateProcess() 函数。Popen 的参数如下。

args 应该是一个程序参数序列，或者是一个单独的字符串或 类路径对象。默认情况下，如果 args 是一个序列，要执行的程序是 args 中的第一个项。如果 args 是一个字符串，则解释是平台相关的，如下所述。有关与默认行为的其他差异，请参阅 shell 和 executable 参数。除非另有说明，建议将 args 作为序列传递。

警告

为了获得最大的可靠性，请为可执行文件使用完全限定路径。要在 PATH 上搜索不合格的名称，请使用 shutil.which()。在所有平台上，传递 sys.executable 是再次启动当前 Python 解释器并使用 -m 命令行格式启动已安装模块的推荐方式。

解析 executable（或 args 的第一个项目）的路径是平台相关的。对于 POSIX，请参阅 os.execvpe()，并注意在解析或搜索可执行文件路径时，cwd 会覆盖当前工作目录，env 可以覆盖 PATH 环境变量。对于 Windows，请参阅 WinAPI CreateProcess 的 lpApplicationName 和 lpCommandLine 参数的文档，并注意在使用 shell=False 解析或搜索可执行文件路径时，cwd 不会覆盖当前工作目录，env 不能覆盖 PATH 环境变量。使用完整路径可以避免所有这些变化。

将一些参数作为序列传递给外部程序的示例是

Popen(["/usr/bin/git", "commit", "-m", "Fixes a bug."])

在 POSIX 上，如果 args 是一个字符串，则该字符串将被解释为要执行的程序的名称或路径。但是，这只能在不向程序传递参数的情况下完成。

备注

如何将 shell 命令分解为参数序列可能并不明显，尤其是在复杂情况下。shlex.split() 可以说明如何确定 args 的正确分词

>>> import shlex, subprocess
>>> command_line = input()
/bin/vikings -input eggs.txt -output "spam spam.txt" -cmd "echo '$MONEY'"
>>> args = shlex.split(command_line)
>>> print(args)
['/bin/vikings', '-input', 'eggs.txt', '-output', 'spam spam.txt', '-cmd', "echo '$MONEY'"]
>>> p = subprocess.Popen(args) # Success!

特别注意，在 shell 中通过空格分隔的选项（例如 -input）和参数（例如 eggs.txt）会放在不同的列表元素中，而在 shell 中需要引号或反斜杠转义的参数（例如包含空格的文件名或上面所示的 echo 命令）是单个列表元素。

在 Windows 上，如果 args 是一个序列，它将按照 将参数序列转换为 Windows 上的字符串 中描述的方式转换为字符串。这是因为底层的 CreateProcess() 对字符串进行操作。

3.6 版中变更: 如果 shell 为 False 且 POSIX 上包含类路径对象的序列，则 args 参数接受 类路径对象。

3.8 版中变更: 如果 shell 为 False 且 Windows 上包含字节和类路径对象的序列，则 args 参数接受 类路径对象。

shell 参数（默认为 False）指定是否将 shell 用作要执行的程序。如果 shell 为 True，建议将 args 作为字符串而不是序列传递。

在 POSIX 上，如果 shell=True，shell 默认为 /bin/sh。如果 args 是一个字符串，该字符串指定通过 shell 执行的命令。这意味着该字符串必须与在 shell 提示符下键入时完全相同的格式。例如，这包括对包含空格的文件名进行引号或反斜杠转义。如果 args 是一个序列，第一个项目指定命令字符串，任何额外的项目将被视为 shell 本身的额外参数。也就是说，Popen 执行等同于

Popen(['/bin/sh', '-c', args[0], args[1], ...])

在 Windows 上，如果 shell=True，COMSPEC 环境变量指定默认 shell。您只需要在要执行的命令是 shell 的内置命令（例如 dir 或 copy）时才需要在 Windows 上指定 shell=True。您不需要 shell=True 来运行批处理文件或基于控制台的可执行文件。

备注

在使用 shell=True 之前，请阅读 安全注意事项 部分。

在创建 stdin/stdout/stderr 管道文件对象时，bufsize 将作为相应的参数提供给 open() 函数

• 0 表示无缓冲（读写是一个系统调用，可能返回短数据）

• 1 表示行缓冲（仅在 text=True 或 universal_newlines=True 时可用）

• 任何其他正值表示使用大约该大小的缓冲区

• 负值 bufsize（默认值）表示将使用系统默认值 io.DEFAULT_BUFFER_SIZE。

3.3.1 版中变更: bufsize 现在默认为 -1，以便默认启用缓冲，以匹配大多数代码期望的行为。在 Python 3.2.4 和 3.3.1 之前的版本中，它错误地默认为 0，即无缓冲并允许短读。这是无意的，并且与大多数代码期望的 Python 2 行为不符。

executable 参数指定要执行的替代程序。它很少需要。当 shell=False 时，executable 替换 args 指定的要执行的程序。然而，原始的 args 仍然传递给程序。大多数程序将 args 指定的程序视为命令名称，这可能与实际执行的程序不同。在 POSIX 上，args 名称成为实用程序（如 ps）中可执行文件的显示名称。如果 shell=True，在 POSIX 上，executable 参数指定默认 /bin/sh 的替代 shell。

3.6 版中变更: executable 参数在 POSIX 上接受 类路径对象。

3.8 版中变更: executable 参数在 Windows 上接受字节和 类路径对象。

3.12 版中变更: 更改了 Windows shell 搜索顺序，针对 shell=True。当前目录和 %PATH% 被替换为 %COMSPEC% 和 %SystemRoot%\System32\cmd.exe。因此，在当前目录中放置名为 cmd.exe 的恶意程序不再有效。

stdin、stdout 和 stderr 分别指定了被执行程序的标准输入、标准输出和标准错误文件句柄。有效值为 None、PIPE、DEVNULL、一个现有文件描述符（正整数）以及一个具有有效文件描述符的现有文件对象。在默认设置为 None 的情况下，不会发生重定向。PIPE 表示应该创建一个到子进程的新管道。DEVNULL 表示将使用特殊文件 os.devnull。此外，stderr 可以是 STDOUT，这表示应用程序的 stderr 数据应该捕获到与 stdout 相同的 文件句柄中。

如果 preexec_fn 设置为一个可调用对象，则该对象将在子进程执行之前在子进程中调用。（仅限 POSIX）

警告

在应用程序中存在线程的情况下，preexec_fn 参数使用不安全。在调用 exec 之前，子进程可能会死锁。

备注

如果您需要修改子进程的环境，请使用 env 参数，而不是在 preexec_fn 中进行。start_new_session 和 process_group 参数应该取代使用 preexec_fn 在子进程中调用 os.setsid() 或 os.setpgid() 的代码。

3.8 版中变更: 子解释器不再支持 preexec_fn 参数。在子解释器中使用该参数会引发 RuntimeError。新的限制可能会影响部署在 mod_wsgi、uWSGI 和其他嵌入式环境中的应用程序。

如果 close_fds 为 true，则除 0、1 和 2 之外的所有文件描述符都将在子进程执行之前关闭。否则，当 close_fds 为 false 时，文件描述符将遵循 文件描述符的继承 中所述的其可继承标志。

在 Windows 上，如果 close_fds 为 true，则子进程不会继承任何句柄，除非在 STARTUPINFO.lpAttributeList 的 handle_list 元素中明确传递，或通过标准句柄重定向。

3.2 版中变更: close_fds 的默认值已从 False 更改为上面描述的值。

3.7 版中变更: 在 Windows 上，当重定向标准句柄时，close_fds 的默认值从 False 更改为 True。现在，当重定向标准句柄时，可以将 close_fds 设置为 True。

pass_fds 是一个可选的文件描述符序列，用于在父进程和子进程之间保持打开。提供任何 pass_fds 会强制 close_fds 为 True。（仅限 POSIX）

3.2 版中变更: 添加了 pass_fds 参数。

如果 cwd 不为 None，则函数在执行子进程之前将工作目录更改为 cwd。cwd 可以是字符串、字节或 类路径 对象。在 POSIX 上，如果可执行文件路径是相对路径，则函数会相对于 cwd 查找 executable（或 args 中的第一个项目）。

3.6 版中变更: cwd 参数在 POSIX 上接受 类路径对象。

3.7 版中变更: cwd 参数在 Windows 上接受 类路径对象。

3.8 版中变更: cwd 参数在 Windows 上接受字节对象。

如果 restore_signals 为 true（默认值），则在子进程执行之前，Python 设置为 SIG_IGN 的所有信号都将在子进程中恢复为 SIG_DFL。目前这包括 SIGPIPE、SIGXFZ 和 SIGXFSZ 信号。（仅限 POSIX）

3.2 版中变更: 添加了 restore_signals。

如果 start_new_session 为 true，则在子进程执行之前，将在子进程中进行 setsid() 系统调用。

可用性：POSIX

3.2 版中变更: 添加了 start_new_session。

如果 process_group 是一个非负整数，则在子进程执行之前，将在子进程中进行 setpgid(0, value) 系统调用。

可用性：POSIX

3.11 版中变更: 添加了 process_group。

如果 group 不为 None，则在子进程执行之前，将在子进程中进行 setregid() 系统调用。如果提供的值是字符串，它将通过 grp.getgrnam() 查找，并使用 gr_gid 中的值。如果该值为整数，它将按原样传递。（仅限 POSIX）

可用性：POSIX

在 3.9 版本中新增。

如果 extra_groups 不为 None，则在子进程执行之前，将在子进程中进行 setgroups() 系统调用。extra_groups 中提供的字符串将通过 grp.getgrnam() 查找，并使用 gr_gid 中的值。整数值将按原样传递。（仅限 POSIX）

可用性：POSIX

在 3.9 版本中新增。

如果 user 不为 None，则在子进程执行之前，将在子进程中进行 setreuid() 系统调用。如果提供的值是字符串，它将通过 pwd.getpwnam() 查找，并使用 pw_uid 中的值。如果该值为整数，它将按原样传递。（仅限 POSIX）

可用性：POSIX

在 3.9 版本中新增。

如果 umask 不为负数，则在子进程执行之前，将在子进程中进行 umask() 系统调用。

可用性：POSIX

在 3.9 版本中新增。

如果 env 不为 None，它必须是一个定义新进程环境变量的映射；这些变量用于代替继承当前进程环境的默认行为。此映射可以是任意平台上的字符串到字符串，或 POSIX 平台上的字节到字节，类似于 os.environ 或 os.environb。

备注

如果指定了 env，则 env 必须提供程序执行所需的所有变量。在 Windows 上，为了运行 并行程序集，指定的 env 必须 包含一个有效的 %SystemRoot%。

如果指定了 encoding 或 errors，或者 text 为 true，则文件对象 stdin、stdout 和 stderr 将以文本模式打开，并使用指定的 encoding 和 errors，如上文 常用参数 中所述。universal_newlines 参数等同于 text，是为了向后兼容而提供的。默认情况下，文件对象以二进制模式打开。

3.6 版新增: 添加了 encoding 和 errors。

3.7 版新增: 添加了 text 作为 universal_newlines 的更具可读性的别名。

如果提供了 startupinfo，它将是一个 STARTUPINFO 对象，该对象将传递给底层的 CreateProcess 函数。

如果给定 creationflags，它可以是以下一个或多个标志

• CREATE_NEW_CONSOLE

• CREATE_NEW_PROCESS_GROUP

• ABOVE_NORMAL_PRIORITY_CLASS

• BELOW_NORMAL_PRIORITY_CLASS

• HIGH_PRIORITY_CLASS

• IDLE_PRIORITY_CLASS

• NORMAL_PRIORITY_CLASS

• REALTIME_PRIORITY_CLASS

• CREATE_NO_WINDOW

• DETACHED_PROCESS

• CREATE_DEFAULT_ERROR_MODE

• CREATE_BREAKAWAY_FROM_JOB

当 stdin、stdout 或 stderr 使用 PIPE 时，可以使用 pipesize 来更改管道的大小。管道的大小只会在支持此功能的平台（目前仅限 Linux）上更改。其他平台将忽略此参数。

3.10 版中变更: 添加了 pipesize 参数。

Popen 对象通过 with 语句支持上下文管理器：退出时，标准文件描述符关闭，并等待进程。

with Popen(["ifconfig"], stdout=PIPE) as proc:
    log.write(proc.stdout.read())

Popen 以及此模块中其他使用它的函数会引发一个 审计事件 subprocess.Popen，其参数为 executable、args、cwd 和 env。args 的值可能是一个字符串或一个字符串列表，具体取决于平台。

3.2 版中变更: 增加了上下文管理器支持。

3.6 版中变更: 如果子进程仍在运行，Popen 析构函数现在会发出 ResourceWarning 警告。

3.8 版中变更: Popen 在某些情况下可以使用 os.posix_spawn() 以提高性能。在适用于 Linux 的 Windows 子系统和 QEMU 用户仿真中，使用 os.posix_spawn() 的 Popen 构造函数不再在程序丢失等错误时引发异常，但子进程会以非零 returncode 失败。

异常

在子进程中，在新程序开始执行之前引发的异常，将在父进程中重新引发。

最常见的异常是 OSError。例如，在尝试执行不存在的文件时会发生这种情况。应用程序应该为 OSError 异常做好准备。请注意，当 shell=True 时，OSError 将仅在找不到选定的 shell 本身时由子进程引发。要确定 shell 是否未能找到请求的应用程序，需要检查子进程的返回代码或输出。

如果使用无效参数调用 Popen，将引发 ValueError。

check_call() 和 check_output() 将在被调用的进程返回非零返回代码时引发 CalledProcessError。

所有接受 timeout 参数的函数和方法，例如 run() 和 Popen.communicate()，如果超时时间在进程退出之前到期，将引发 TimeoutExpired。

此模块中定义的所有异常都继承自 SubprocessError。

3.3 版新增: 添加了 SubprocessError 基类。

安全考虑

与某些其他 popen 函数不同，此库不会隐式选择调用系统 shell。这意味着所有字符，包括 shell 元字符，都可以安全地传递给子进程。如果通过 shell=True 显式调用 shell，则应用程序有责任确保所有空格和元字符都被正确引用，以避免 shell 注入 漏洞。在 某些平台 上，可以使用 shlex.quote() 进行此转义。

在 Windows 上，批处理文件 (*.bat 或 *.cmd) 可能会被操作系统在系统 shell 中启动，而不管传递给此库的参数。这可能导致参数根据 shell 规则进行解析，但没有 Python 添加任何转义。如果您有意从不受信任的源启动带参数的批处理文件，请考虑传递 shell=True 以允许 Python 转义特殊字符。有关更多讨论，请参阅 gh-114539。

Popen 对象

Popen 类的实例具有以下方法

Popen.poll()

检查子进程是否已终止。设置并返回 returncode 属性。否则，返回 None。

Popen.wait(timeout=None)

等待子进程终止。设置并返回 returncode 属性。

如果进程在 timeout 秒后仍未终止，则引发 TimeoutExpired 异常。捕获此异常并重试等待是安全的。

备注

当使用 stdout=PIPE 或 stderr=PIPE 且子进程向管道生成足够的输出导致其阻塞等待操作系统管道缓冲区接受更多数据时，这将导致死锁。在使用管道时使用 Popen.communicate() 可避免这种情况。

备注

当 timeout 参数不为 None 时，（在 POSIX 上）该函数通过忙循环（非阻塞调用和短睡眠）实现。使用 asyncio 模块进行异步等待：请参阅 asyncio.create_subprocess_exec。

3.3 版中变更: 添加了 timeout。

Popen.communicate(input=None, timeout=None)

与进程交互：向 stdin 发送数据。从 stdout 和 stderr 读取数据，直到达到文件末尾。等待进程终止并设置 returncode 属性。可选的 input 参数应该是要发送给子进程的数据，如果不需要发送数据给子进程，则为 None。如果流以文本模式打开，则 input 必须是字符串。否则，它必须是字节。

communicate() 返回一个元组 (stdout_data, stderr_data)。如果流以文本模式打开，则数据将是字符串；否则为字节。

请注意，如果要向进程的 stdin 发送数据，则需要使用 stdin=PIPE 创建 Popen 对象。同样，要在结果元组中获得 None 以外的任何内容，您还需要提供 stdout=PIPE 和/或 stderr=PIPE。

如果进程在 timeout 秒后仍未终止，将引发 TimeoutExpired 异常。捕获此异常并重试通信不会丢失任何输出。

如果超时，子进程不会被杀死，因此为了正确清理，行为良好的应用程序应杀死子进程并完成通信

proc = subprocess.Popen(...)
try:
    outs, errs = proc.communicate(timeout=15)
except TimeoutExpired:
    proc.kill()
    outs, errs = proc.communicate()

备注

读取的数据在内存中缓冲，因此如果数据大小较大或无限，请勿使用此方法。

3.3 版中变更: 添加了 timeout。

Popen.send_signal(signal)

向子进程发送信号 signal。

如果进程已完成，则不执行任何操作。

备注

在 Windows 上，SIGTERM 是 terminate() 的别名。CTRL_C_EVENT 和 CTRL_BREAK_EVENT 可以发送给使用包含 CREATE_NEW_PROCESS_GROUP 的 creationflags 参数启动的进程。

Popen.terminate()

终止子进程。在 POSIX 操作系统上，该方法向子进程发送 SIGTERM。在 Windows 上，调用 Win32 API 函数 TerminateProcess() 来终止子进程。

Popen.kill()

杀死子进程。在 POSIX 操作系统上，该函数向子进程发送 SIGKILL。在 Windows 上，kill() 是 terminate() 的别名。

该类还会为您设置以下属性以供访问。不支持将它们重新分配给新值

Popen.args

传递给 Popen 的 args 参数——一个程序参数序列或一个字符串。

在 3.3 版本加入。

Popen.stdin

如果 stdin 参数是 PIPE，则此属性是一个可写入的流对象，由 open() 返回。如果指定了 encoding 或 errors 参数，或者 text 或 universal_newlines 参数为 True，则该流是文本流，否则是字节流。如果 stdin 参数不是 PIPE，则此属性为 None。

Popen.stdout

如果 stdout 参数是 PIPE，则此属性是一个可读的流对象，由 open() 返回。从该流读取将提供子进程的输出。如果指定了 encoding 或 errors 参数，或者 text 或 universal_newlines 参数为 True，则该流是文本流，否则是字节流。如果 stdout 参数不是 PIPE，则此属性为 None。

Popen.stderr

如果 stderr 参数是 PIPE，则此属性是一个可读的流对象，由 open() 返回。从该流读取将提供子进程的错误输出。如果指定了 encoding 或 errors 参数，或者 text 或 universal_newlines 参数为 True，则该流是文本流，否则是字节流。如果 stderr 参数不是 PIPE，则此属性为 None。

警告

请使用 communicate() 而不是 .stdin.write、.stdout.read 或 .stderr.read，以避免由于任何其他操作系统管道缓冲区填满并阻塞子进程而导致的死锁。

Popen.pid

子进程的进程 ID。

请注意，如果将 shell 参数设置为 True，则这是启动的 shell 的进程 ID。

Popen.returncode

子进程的返回代码。最初为 None，如果在调用 poll()、wait() 或 communicate() 方法时检测到进程已终止，则 returncode 会被设置。

值为 None 表示在上次方法调用时进程尚未终止。

负值 -N 表示子进程被信号 N 终止（仅限 POSIX）。

Windows Popen 助手

STARTUPINFO 类和以下常量仅在 Windows 上可用。

class subprocess.STARTUPINFO(*, dwFlags=0, hStdInput=None, hStdOutput=None, hStdError=None, wShowWindow=0, lpAttributeList=None)

Windows STARTUPINFO 结构的部分支持用于 Popen 创建。可以通过将它们作为仅关键字参数传递来设置以下属性。

3.7 版本中已更改: 增加了仅关键字参数支持。

dwFlags

一个位字段，它决定在进程创建窗口时是否使用某些 STARTUPINFO 属性。

si = subprocess.STARTUPINFO()
si.dwFlags = subprocess.STARTF_USESTDHANDLES | subprocess.STARTF_USESHOWWINDOW

hStdInput

如果 dwFlags 指定 STARTF_USESTDHANDLES，则此属性是进程的标准输入句柄。如果未指定 STARTF_USESTDHANDLES，则标准输入的默认值为键盘缓冲区。

hStdOutput

如果 dwFlags 指定 STARTF_USESTDHANDLES，则此属性是进程的标准输出句柄。否则，此属性将被忽略，标准输出的默认值为控制台窗口的缓冲区。

hStdError

如果 dwFlags 指定 STARTF_USESTDHANDLES，则此属性是进程的标准错误句柄。否则，此属性将被忽略，标准错误的默认值为控制台窗口的缓冲区。

wShowWindow

如果 dwFlags 指定 STARTF_USESHOWWINDOW，则此属性可以是 ShowWindow 函数的 nCmdShow 参数中可以指定的任何值，但 SW_SHOWDEFAULT 除外。否则，此属性将被忽略。

SW_HIDE 为此属性提供。当调用 Popen 时 shell=True 时使用它。

lpAttributeList

一个字典，包含 STARTUPINFOEX 中给出的其他进程创建属性，请参阅 UpdateProcThreadAttribute。

支持的属性

handle_list

将继承的句柄序列。如果非空，则 close_fds 必须为 True。

当传递给 Popen 构造函数时，句柄必须通过 os.set_handle_inheritable() 暂时设置为可继承，否则将引发 OSError，错误代码为 Windows 错误 ERROR_INVALID_PARAMETER (87)。

警告

在多线程进程中，将此功能与并发调用其他继承所有句柄的进程创建函数（例如 os.system()）结合使用时，请谨慎操作，以避免标记为可继承的句柄泄漏。这同样适用于标准句柄重定向，它会暂时创建可继承的句柄。

在 3.7 版本加入。

Windows 常量

subprocess 模块公开了以下常量。

subprocess.STD_INPUT_HANDLE

标准输入设备。最初，它是控制台输入缓冲区，CONIN$。

subprocess.STD_OUTPUT_HANDLE

标准输出设备。最初，它是活动控制台屏幕缓冲区，CONOUT$。

subprocess.STD_ERROR_HANDLE

标准错误设备。最初，它是活动控制台屏幕缓冲区，CONOUT$。

subprocess.SW_HIDE

隐藏窗口。另一个窗口将被激活。

subprocess.STARTF_USESTDHANDLES

指定 STARTUPINFO.hStdInput、STARTUPINFO.hStdOutput 和 STARTUPINFO.hStdError 属性包含额外信息。

subprocess.STARTF_USESHOWWINDOW

指定 STARTUPINFO.wShowWindow 属性包含额外信息。

subprocess.STARTF_FORCEONFEEDBACK

一个 STARTUPINFO.dwFlags 参数，用于指定在进程启动时将显示“后台工作”鼠标光标。这是 GUI 进程的默认行为。

在 3.13 版本加入。

subprocess.STARTF_FORCEOFFFEEDBACK

一个 STARTUPINFO.dwFlags 参数，用于指定在启动进程时鼠标光标不会更改。

在 3.13 版本加入。

subprocess.CREATE_NEW_CONSOLE

新进程拥有一个新的控制台，而不是继承其父进程的控制台（默认）。

subprocess.CREATE_NEW_PROCESS_GROUP

一个 Popen creationflags 参数，用于指定将创建一个新的进程组。此标志对于对子进程使用 os.kill() 是必需的。

如果指定了 CREATE_NEW_CONSOLE，则此标志将被忽略。

subprocess.ABOVE_NORMAL_PRIORITY_CLASS

一个 Popen creationflags 参数，用于指定新进程将具有高于平均的优先级。

在 3.7 版本加入。

subprocess.BELOW_NORMAL_PRIORITY_CLASS

一个 Popen creationflags 参数，用于指定新进程将具有低于平均的优先级。

在 3.7 版本加入。

subprocess.HIGH_PRIORITY_CLASS

一个 Popen creationflags 参数，用于指定新进程将具有高优先级。

在 3.7 版本加入。

subprocess.IDLE_PRIORITY_CLASS

一个 Popen creationflags 参数，用于指定新进程将具有空闲（最低）优先级。

在 3.7 版本加入。

subprocess.NORMAL_PRIORITY_CLASS

一个 Popen creationflags 参数，用于指定新进程将具有正常优先级。（默认）

在 3.7 版本加入。

subprocess.REALTIME_PRIORITY_CLASS

一个 Popen creationflags 参数，用于指定新进程将具有实时优先级。几乎不应使用 REALTIME_PRIORITY_CLASS，因为它会中断管理鼠标输入、键盘输入和后台磁盘刷新的系统线程。此类别可能适用于直接与硬件“对话”或执行应受有限中断的短暂任务的应用程序。

在 3.7 版本加入。

subprocess.CREATE_NO_WINDOW

一个 Popen creationflags 参数，用于指定新进程不会创建窗口。

在 3.7 版本加入。

subprocess.DETACHED_PROCESS

一个 Popen creationflags 参数，用于指定新进程不会继承其父进程的控制台。此值不能与 CREATE_NEW_CONSOLE 一起使用。

在 3.7 版本加入。

subprocess.CREATE_DEFAULT_ERROR_MODE

一个 Popen creationflags 参数，用于指定新进程不继承调用进程的错误模式。相反，新进程获取默认错误模式。此功能对于禁用硬错误的多线程 shell 应用程序特别有用。

在 3.7 版本加入。

subprocess.CREATE_BREAKAWAY_FROM_JOB

一个 Popen creationflags 参数，用于指定新进程不与作业关联。

在 3.7 版本加入。

旧版高级 API

在 Python 3.5 之前，这三个函数构成了 subprocess 的高级 API。现在在许多情况下可以使用 run()，但许多现有代码仍然调用这些函数。

subprocess.call(args, *, stdin=None, stdout=None, stderr=None, shell=False, cwd=None, timeout=None, **other_popen_kwargs)

运行 args 描述的命令。等待命令完成，然后返回 returncode 属性。

需要捕获 stdout 或 stderr 的代码应改用 run()

run(...).returncode

要抑制 stdout 或 stderr，请提供 DEVNULL 值。

上面显示的参数只是一些常见的参数。完整的函数签名与 Popen 构造函数的签名相同 - 此函数将所有提供的参数（除了 timeout）直接传递给该接口。

备注

请勿在此函数中使用 stdout=PIPE 或 stderr=PIPE。如果子进程向管道生成足够的输出以填满操作系统管道缓冲区，则子进程将阻塞，因为管道没有被读取。

3.3 版中变更: 添加了 timeout。

3.12 版中变更: 更改了 Windows shell 搜索顺序，针对 shell=True。当前目录和 %PATH% 被替换为 %COMSPEC% 和 %SystemRoot%\System32\cmd.exe。因此，在当前目录中放置名为 cmd.exe 的恶意程序不再有效。

subprocess.check_call(args, *, stdin=None, stdout=None, stderr=None, shell=False, cwd=None, timeout=None, **other_popen_kwargs)

使用参数运行命令。等待命令完成。如果返回代码为零则返回，否则引发 CalledProcessError。CalledProcessError 对象将在 returncode 属性中包含返回代码。如果 check_call() 无法启动进程，它将传播引发的异常。

需要捕获 stdout 或 stderr 的代码应改用 run()

run(..., check=True)

要抑制 stdout 或 stderr，请提供 DEVNULL 值。

上面显示的参数只是一些常见的参数。完整的函数签名与 Popen 构造函数的签名相同 - 此函数将所有提供的参数（除了 timeout）直接传递给该接口。

备注

请勿在此函数中使用 stdout=PIPE 或 stderr=PIPE。如果子进程向管道生成足够的输出以填满操作系统管道缓冲区，则子进程将阻塞，因为管道没有被读取。

3.3 版中变更: 添加了 timeout。

3.12 版中变更: 更改了 Windows shell 搜索顺序，针对 shell=True。当前目录和 %PATH% 被替换为 %COMSPEC% 和 %SystemRoot%\System32\cmd.exe。因此，在当前目录中放置名为 cmd.exe 的恶意程序不再有效。

subprocess.check_output(args, *, stdin=None, stderr=None, shell=False, cwd=None, encoding=None, errors=None, universal_newlines=None, timeout=None, text=None, **other_popen_kwargs)

运行带有参数的命令并返回其输出。

如果返回代码非零，它将引发 CalledProcessError。CalledProcessError 对象将在 returncode 属性中包含返回代码，并在 output 属性中包含任何输出。

这等价于：

run(..., check=True, stdout=PIPE).stdout

上面显示的参数只是一些常见的参数。完整的函数签名与 run() 的大致相同——大多数参数直接传递给该接口。与 run() 行为的一个 API 差异是：传递 input=None 的行为与 input=b''（或 input=''，取决于其他参数）相同，而不是使用父进程的标准输入文件句柄。

默认情况下，此函数将以编码字节的形式返回数据。输出数据的实际编码可能取决于所调用的命令，因此通常需要在应用程序级别处理文本解码。

通过将 text、encoding、errors 或 universal_newlines 设置为 True 可以覆盖此行为，如 常用参数 和 run() 中所述。

要同时捕获标准错误到结果中，请使用 stderr=subprocess.STDOUT

>>> subprocess.check_output(
...     "ls non_existent_file; exit 0",
...     stderr=subprocess.STDOUT,
...     shell=True)
'ls: non_existent_file: No such file or directory\n'

在 3.1 版本加入。

3.3 版中变更: 添加了 timeout。

3.4 版本中已更改: 增加了对 input 关键字参数的支持。

3.6 版本中已更改: 增加了 encoding 和 errors。有关详细信息，请参见 run()。

3.7 版新增: 添加了 text 作为 universal_newlines 的更具可读性的别名。

3.12 版中变更: 更改了 Windows shell 搜索顺序，针对 shell=True。当前目录和 %PATH% 被替换为 %COMSPEC% 和 %SystemRoot%\System32\cmd.exe。因此，在当前目录中放置名为 cmd.exe 的恶意程序不再有效。

使用 subprocess 模块替换旧函数

在本节中，“a 变为 b”表示 b 可以用作 a 的替代品。

备注

本节中所有“a”函数在找不到已执行程序时会（或多或少）静默失败；“b”替代品会改为引发 OSError。

此外，使用 check_output() 的替换将因 CalledProcessError 而失败，如果请求的操作产生非零返回代码。输出仍然作为引发异常的 output 属性可用。

在以下示例中，我们假设相关函数已从 subprocess 模块中导入。

替换 /bin/sh shell 命令替换

output=$(mycmd myarg)

变为

output = check_output(["mycmd", "myarg"])

替换 shell 管道

output=$(dmesg | grep hda)

变为

p1 = Popen(["dmesg"], stdout=PIPE)
p2 = Popen(["grep", "hda"], stdin=p1.stdout, stdout=PIPE)
p1.stdout.close()  # Allow p1 to receive a SIGPIPE if p2 exits.
output = p2.communicate()[0]

在启动 p2 后调用 p1.stdout.close() 很重要，以便在 p2 在 p1 之前退出时 p1 接收到 SIGPIPE。

或者，对于可信输入，shell 自己的管道支持仍然可以直接使用

output=$(dmesg | grep hda)

变为

output = check_output("dmesg | grep hda", shell=True)

替换 os.system()

sts = os.system("mycmd" + " myarg")
# becomes
retcode = call("mycmd" + " myarg", shell=True)

备注

• 通常不需要通过 shell 调用程序。

• call() 的返回值与 os.system() 的返回值编码方式不同。

• os.system() 函数在命令运行时忽略 SIGINT 和 SIGQUIT 信号，但使用 subprocess 模块时，调用者必须单独执行此操作。

一个更实际的例子会是这样

try:
    retcode = call("mycmd" + " myarg", shell=True)
    if retcode < 0:
        print("Child was terminated by signal", -retcode, file=sys.stderr)
    else:
        print("Child returned", retcode, file=sys.stderr)
except OSError as e:
    print("Execution failed:", e, file=sys.stderr)

替换 os.spawn 家族

P_NOWAIT 示例

pid = os.spawnlp(os.P_NOWAIT, "/bin/mycmd", "mycmd", "myarg")
==>
pid = Popen(["/bin/mycmd", "myarg"]).pid

P_WAIT 示例

retcode = os.spawnlp(os.P_WAIT, "/bin/mycmd", "mycmd", "myarg")
==>
retcode = call(["/bin/mycmd", "myarg"])

向量示例

os.spawnvp(os.P_NOWAIT, path, args)
==>
Popen([path] + args[1:])

环境示例

os.spawnlpe(os.P_NOWAIT, "/bin/mycmd", "mycmd", "myarg", env)
==>
Popen(["/bin/mycmd", "myarg"], env={"PATH": "/usr/bin"})

替换 os.popen()

返回代码处理转换如下

pipe = os.popen(cmd, 'w')
...
rc = pipe.close()
if rc is not None and rc >> 8:
    print("There were some errors")
==>
process = Popen(cmd, stdin=PIPE)
...
process.stdin.close()
if process.wait() != 0:
    print("There were some errors")

旧版 Shell 调用函数

此模块还提供了来自 2.x commands 模块的以下旧版函数。这些操作隐式调用系统 shell，并且上述关于安全性和异常处理一致性的任何保证对这些函数均无效。

subprocess.getstatusoutput(cmd, *, encoding=None, errors=None)

在 shell 中执行 cmd 并返回 (exitcode, output)。

使用 check_output() 在 shell 中执行字符串 cmd，并返回一个 2 元组 (exitcode, output)。encoding 和 errors 用于解码输出；有关详细信息，请参阅 常用参数 中的注释。

输出中的尾部换行符将被去除。命令的退出码可以解释为 subprocess 的返回码。示例

>>> subprocess.getstatusoutput('ls /bin/ls')
(0, '/bin/ls')
>>> subprocess.getstatusoutput('cat /bin/junk')
(1, 'cat: /bin/junk: No such file or directory')
>>> subprocess.getstatusoutput('/bin/junk')
(127, 'sh: /bin/junk: not found')
>>> subprocess.getstatusoutput('/bin/kill $$')
(-15, '')

可用性: Unix, Windows。

3.3.4 版本中已更改: 增加了对 Windows 的支持。

该函数现在返回 (exitcode, output)，而不是像 Python 3.3.3 及更早版本那样返回 (status, output)。exitcode 具有与 returncode 相同的值。

3.11 版本中已更改: 增加了 encoding 和 errors 参数。

subprocess.getoutput(cmd, *, encoding=None, errors=None)

在 shell 中执行 cmd 并返回其输出（stdout 和 stderr）。

与 getstatusoutput() 类似，只是忽略退出码，返回值为包含命令输出的字符串。示例

>>> subprocess.getoutput('ls /bin/ls')
'/bin/ls'

可用性: Unix, Windows。

3.3.4 版本中已更改: 增加了对 Windows 的支持

3.11 版本中已更改: 增加了 encoding 和 errors 参数。

注释

超时行为

在使用 run()、Popen.wait() 或 Popen.communicate() 等函数中的 timeout 参数时，用户应注意以下行为：

1. 进程创建延迟：在许多平台 API 上，初始进程创建本身无法中断。这意味着即使指定了超时，也无法保证在进程创建所需时间之后才能看到超时异常。

2. 极小的超时值：设置非常小的超时值（例如几毫秒）可能会导致几乎立即出现 TimeoutExpired 异常，因为进程创建和系统调度本身需要时间。

在 Windows 上将参数序列转换为字符串

在 Windows 上，args 序列被转换为一个字符串，可以使用以下规则进行解析（这些规则对应于 MS C 运行时使用的规则）

1. 参数由空白符（空格或制表符）分隔。

2. 用双引号括起来的字符串被解释为单个参数，无论其中包含多少空白符。带引号的字符串可以嵌入到参数中。

3. 前面带反斜杠的双引号被解释为字面双引号。

4. 反斜杠被解释为字面字符，除非它们紧跟在双引号之前。

5. 如果反斜杠紧跟在双引号之前，每对反斜杠都被解释为字面反斜杠。如果反斜杠的数量是奇数，则最后一个反斜杠会转义下一个双引号，如规则 3 中所述。

参见

shlex

提供用于解析和转义命令行功能的模块。

禁用 posix_spawn() 的使用

在 Linux 上，subprocess 默认情况下在安全的情况下内部使用 vfork() 系统调用而不是 fork()。这大大提高了性能。

subprocess._USE_POSIX_SPAWN = False  # See CPython issue gh-NNNNNN.

在任何 Python 版本上，将此设置为 false 都是安全的。它在不支持的旧版本或新版本上不会产生任何影响。不要假设该属性可读。尽管有此名称，但 true 值并不表示将使用相应的函数，而只是表示可能使用。

当您不得不使用这些私有选项时，请提交问题，并提供重现您所遇到的问题的方法。在您的代码注释中链接到该问题。

3.8 版本新增: _USE_POSIX_SPAWN