使用 subprocess 模块¶

推荐的调用子进程的方式是在任何它支持的用例中使用 run() 函数。对于更进阶的用例，也可以使用底层的 Popen 接口。

run() 函数是在 Python 3.5 被添加的；如果你需要与旧版本保持兼容，查看 较旧的高阶 API 段落。

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)¶

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

以上显示的参数仅仅是最简单的一些，下面 常用参数 描述（因此在缩写签名中使用仅关键字标示）。完整的函数头和 Popen 的构造函数一样，此函数接受的大多数参数都被传递给该接口。（timeout, input, check 和 capture_output 除外）。

如果 capture_output 设为 true，stdout 和 stderr 将会被捕获。在使用时，内置的 Popen 对象将自动用 stdout=PIPE 和 stderr=PIPE 创建。stdout 和 stderr 参数不应当与 capture_output 同时提供。如果你希望捕获并将两个流合并在一起，使用 stdout=PIPE 和 stderr=STDOUT 来代替 capture_output。

timeout 参数将被传递给 Popen.communicate()。如果发生超时，子进程将被杀死并等待。 TimeoutExpired 异常将在子进程中断后被抛出。

input 参数将被传递给 Popen.communicate() 以及子进程的标准输入。 如果使用此参数，它必须是一个字节序列。 如果指定了 encoding 或 errors 或者将 text 设置为 True，那么也可以是一个字符串。 当使用此参数时，在创建内部 Popen 对象时将自动带上 stdin=PIPE，并且不能再手动指定 stdin 参数。

如果 check 设为 True, 并且进程以非零状态码退出, 一个 CalledProcessError 异常将被抛出. 这个异常的属性将设置为参数, 退出码, 以及标准输出和标准错误, 如果被捕获到.

如果 encoding 或者 error 被指定, 或者 text 被设为 True, 标准输入, 标准输出和标准错误的文件对象将通过指定的 encoding 和 errors 以文本模式打开, 否则以默认的 io.TextIOWrapper 打开. universal_newline 参数等同于 text 并且提供了向后兼容性. 默认情况下, 文件对象是以二进制模式打开的.

如果 env 不是 None, 它必须是一个字典, 为新的进程设置环境变量; 它用于替换继承的当前进程的环境的默认行为. 它将直接被传递给 Popen.

例如:

>>> 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 形参.

class subprocess.CompletedProcess¶

run() 的返回值, 代表一个进程已经结束.

args¶

被用作启动进程的参数. 可能是一个列表或字符串.

returncode¶

子进程的退出状态码. 通常来说, 一个为 0 的退出码表示进程运行正常.

一个负值 -N 表示子进程被信号 N 中断 (仅 POSIX).

stdout¶

从子进程捕获到的标准输出. 一个字节序列, 或一个字符串, 如果 run() 是设置了 encoding, errors 或者 text=True 来运行的. 如果未有捕获, 则为 None.

如果你通过 stderr=subprocess.STDOUT 运行, 标准输入和标准错误将被组合在一起, 并且 stderr` 将为 None.

stderr¶

捕获到的子进程的标准错误. 一个字节序列, 或者一个字符串, 如果 run() 是设置了参数 encoding, errors 或者 text=True 运行的. 如果未有捕获, 则为 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 的 stdin ， stdout 或者 stderr 参数使用的特殊值， 表示标准错误与标准输出使用同一句柄。

exception subprocess.SubprocessError¶

此模块的其他异常的基类。

3.3 新版功能.

exception subprocess.TimeoutExpired¶

SubprocessError 的子类，等待子进程的过程中发生超时时被抛出。

cmd¶

用于创建子进程的指令。

timeout¶

超时秒数。

output¶

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

stdout¶

对 output 的别名，对应的有 stderr。

stderr¶

子进程的标准错误输出，如果被 run() 捕获。 否则为 None。

3.3 新版功能.

在 3.5 版更改: 添加了 stdout 和 stderr 属性。

exception subprocess.CalledProcessError¶

SubprocessError 的子类，当一个被 check_call() 或 check_output() 函数运行的子进程返回了非零退出码时被抛出。

returncode¶

子进程的退出状态。如果程序由一个信号终止，这将会被设为一个负的信号码。

cmd¶

用于创建子进程的指令。

output¶

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

stdout¶

对 output 的别名，对应的有 stderr。

stderr¶

子进程的标准错误输出，如果被 run() 捕获。 否则为 None。

在 3.5 版更改: 添加了 stdout 和 stderr 属性。

安全考量¶

不像一些其他的 popen 功能，此实现绝不会隐式调用一个系统 shell。这意味着任何字符，包括 shell 元字符，可以安全地被传递给子进程。如果 shell 被明确地调用，通过 shell=True 设置，则确保所有空白字符和元字符被恰当地包裹在引号内以避免 shell 注入 漏洞就由应用程序负责了。

当使用 shell=True， shlex.quote() 函数可以作为在将被用于构造 shell 指令的字符串中转义空白字符以及 shell 元字符的方案。

Popen 对象¶

Popen 类的实例拥有以下方法：

Popen.poll()¶

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

Popen.wait(timeout=None)¶

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

如果进程在 timeout 秒后未中断，抛出一个 TimeoutExpired 异常，可以安全地捕获此异常并重新等待。

注解

当 stdout=PIPE 或者 stderr=PIPE 并且子进程产生了足以阻塞 OS 管道缓冲区接收更多数据的输出到管道时，将会发生死锁。当使用管道时用 Popen.communicate() 来规避它。

注解

此函数使用了一个 busy loop （非阻塞调用以及短睡眠） 实现。使用 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 的 creationflags 形参启动的进程。

Popen.terminate()¶

停止子进程。 在 POSIX 操作系统上，此方法会发送 SIGTERM 给子进程。 在 Windows 上则会调用 Win32 API 函数 TerminateProcess() 来停止子进程。

Popen.kill()¶

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

以下属性也是可用的：

Popen.args¶

args 参数传递给 Popen -- 一个程序参数的序列或者一个简单字符串。

3.3 新版功能.

Popen.stdin¶

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

Popen.stdout¶

如果 stdout 参数是 PIPE，此属性是一个类似 open() 返回的可读流。从流中读取子进程提供的输出。如果 encoding 或 errors 参数被指定或者 universal_newlines 参数为 True，此流为文本流，否则为字节流。如果 stdout 参数非 PIPE，此属性为 None。

Popen.stderr¶

如果 stderr 参数是 PIPE，此属性是一个类似 open() 返回的可读流。从流中读取子进程提供的输出。如果 encoding 或 errors 参数被指定或者 universal_newlines 参数为 True，此流为文本流，否则为字节流。如果 stderr 参数非 PIPE，此属性为 None。

Popen.pid¶

子进程的进程号。

注意如果你设置了 shell 参数为 True，则这是生成的子 shell 的进程号。

Popen.returncode¶

此进程的退出码，由 poll() 和 wait() 设置（以及直接由 communicate() 设置）。一个 None 值 表示此进程仍未结束。

一个负值 -N 表示子进程被信号 N 中断 (仅 POSIX).

Windows Popen 助手¶

STARTUPINFO 类和以下常数仅在 Windows 有效。

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

在 Popen 创建时部分支持 Windows 的 STARTUPINFO 结构。接下来的属性仅能通过关键词参数设置。

在 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 ERROR_INVALID_PARAMETER (87) 抛出。

警告

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

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。 如果子进程向管道生成了足以填满 OS 管理缓冲区的输出而管道还未被读取时它将会阻塞。

在 3.3 版更改: timeout 被添加

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

附带参数运行命令。 等待命令完成。 如果返回码为零则正常返回，否则引发 CalledProcessError。 CalledProcessError 对象将在 returncode 属性中保存返回码。

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

run(..., check=True)

要屏蔽 stdout 或 stderr，可提供 DEVNULL 这个值。

上面显示的参数只是常见的一些。 完整的函数签名与 Popen 构造器的相同 —— 此函数会将所提供的 timeout 之外的全部参数直接传递给目标接口。

注解

请不要在此函数中使用 stdout=PIPE 或 stderr=PIPE。 如果子进程向管道生成了足以填满 OS 管理缓冲区的输出而管道还未被读取时它将会阻塞。

在 3.3 版更改: timeout 被添加

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 的一个更具可读性的别名被添加。

使用 subprocess 模块替换旧函数¶

在这一节中，"a 改为 b" 意味着 b 可以被用作 a 的替代。

在下列例子中，我们假定相关的函数都已从 subprocess 模块中导入了。

output=$(mycmd myarg)

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

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]

output=$(dmesg | grep hda)

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

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

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)

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

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"})

(child_stdin, child_stdout) = os.popen2(cmd, mode, bufsize)
==>
p = Popen(cmd, shell=True, bufsize=bufsize,
          stdin=PIPE, stdout=PIPE, close_fds=True)
(child_stdin, child_stdout) = (p.stdin, p.stdout)

(child_stdin,
 child_stdout,
 child_stderr) = os.popen3(cmd, mode, bufsize)
==>
p = Popen(cmd, shell=True, bufsize=bufsize,
          stdin=PIPE, stdout=PIPE, stderr=PIPE, close_fds=True)
(child_stdin,
 child_stdout,
 child_stderr) = (p.stdin, p.stdout, p.stderr)

(child_stdin, child_stdout_and_stderr) = os.popen4(cmd, mode, bufsize)
==>
p = Popen(cmd, shell=True, bufsize=bufsize,
          stdin=PIPE, stdout=PIPE, stderr=STDOUT, close_fds=True)
(child_stdin, child_stdout_and_stderr) = (p.stdin, p.stdout)

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")

(child_stdout, child_stdin) = popen2.popen2("somestring", bufsize, mode)
==>
p = Popen("somestring", shell=True, bufsize=bufsize,
          stdin=PIPE, stdout=PIPE, close_fds=True)
(child_stdout, child_stdin) = (p.stdout, p.stdin)

(child_stdout, child_stdin) = popen2.popen2(["mycmd", "myarg"], bufsize, mode)
==>
p = Popen(["mycmd", "myarg"], bufsize=bufsize,
          stdin=PIPE, stdout=PIPE, close_fds=True)
(child_stdout, child_stdin) = (p.stdout, p.stdin)

旧式的 Shell 发起函数¶

此模块还提供了以下来自 2.x commands 模块的旧版函数。 这些操作会隐式地发起调用系统 shell 并且上文所描述的有关安全与异常处理一致性保证都不适用于这些函数。

subprocess.getstatusoutput(cmd)¶

返回在 shell 中执行 cmd 产生的 (exitcode, output)。

在 shell 中以 Popen.check_output() 执行字符串 cmd 并返回一个 2 元组 (exitcode, output)。 会使用当前区域设置的编码格式；请参阅 常用参数 中的说明来了解详情。

末尾的一个换行符会从输出中被去除。 命令的退出码可被解读为子进程的返回码。 例如:

>>> 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, '')

可用性: POSIX 和 Windows。

在 3.3.4 版更改: 添加了 Windows 支持。

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

subprocess.getoutput(cmd)¶

返回在 shell 中执行 cmd 产生的输出（stdout 和 stderr）。

类似于 getstatusoutput()，但退出码会被忽略并且返回值为包含命令输出的字符串。 例如:

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

可用性: POSIX 和 Windows。

在 3.3.4 版更改: 添加了 Windows 支持

注释¶