内容表

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 实例。

The arguments shown above are merely the most common ones, described below in 经常使用的自变量 (hence the use of keyword-only notation in the abbreviated signature). The full function signature is largely the same as that of the Popen constructor - most of the arguments to this function are passed through to that interface. ( timeout , input , check ，和 capture_output are not.)

若 capture_output is true, stdout and stderr will be captured. When used, the internal Popen object is automatically created with stdout and stderr both set to PIPE 。 stdout and stderr arguments may not be supplied at the same time as capture_output . If you wish to capture and combine both streams into one, set stdout to PIPE and stderr to STDOUT , instead of using capture_output .

A timeout may be specified in seconds, it is internally passed on to Popen.communicate() . If the timeout expires, the child process will be killed and waited for. The TimeoutExpired exception will be re-raised after the child process has terminated. The initial process creation itself cannot be interrupted on many platform APIs so you are not guaranteed to see a timeout exception until at least after however long process creation takes.

The input 自变量会被传递给 Popen.communicate() and thus to the subprocess’s stdin. If used it must be a byte sequence, or a string if encoding or errors is specified or text is true. When used, the internal Popen object is automatically created with stdin 设为 PIPE ，和 stdin argument may not be used as well.

若 check is true, and the process exits with a non-zero exit code, a CalledProcessError exception will be raised. Attributes of that exception hold the arguments, the exit code, and stdout and stderr if they were captured.

若 encoding or errors 被指定，或 text is true, file objects for stdin, stdout and stderr are opened in text mode using the specified encoding and errors 或 io.TextIOWrapper 默认。 universal_newlines argument is equivalent to text and is provided for backwards compatibility. By default, file objects are opened in binary mode.

若 env 不是 None ，它必须是为新进程定义环境变量的映射；使用这些代替继承当前进程环境的默认行为。它被直接传递给 Popen . This mapping can be str to str on any platform or bytes to bytes on POSIX platforms much like os.environ or 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'')

Added in version 3.5.

3.6 版改变：添加 encoding and errors 参数

3.7 版改变：添加 text 参数，作为更可理解的别名化 universal_newlines 。添加 capture_output 参数。

Changed in version 3.12: Changed Windows shell search order for shell=True . The current directory and %PATH% are replaced with %COMSPEC% and %SystemRoot%\System32\cmd.exe . As a result, dropping a malicious program named cmd.exe into a current directory no longer works.

class subprocess. CompletedProcess ¶

返回值来自 run() ，表示进程已完成。

args ¶: 用于发起进程的自变量。这可以是列表 (或字符串)。

returncode ¶

子级进程的退出状态。通常，退出状态 0 指示运行成功。

负值 -N 指示子级被终止，通过信号 N (仅 POSIX)。

stdout ¶

Captured stdout from the child process. A bytes sequence, or a string if run() was called with an encoding, errors, or text=True. None 若未捕获 stdout。

If you ran the process with stderr=subprocess.STDOUT , stdout and stderr will be combined in this attribute, and stderr 将是 None .

stderr ¶: 从子级进程捕获 stderr。字节序列，或字符串若 run() was called with an encoding, errors, or text=True. None 若未捕获 stderr。

check_returncode ( ) ¶: 若 returncode 非零，引发 CalledProcessError .

Added in version 3.5.

subprocess. DEVNULL ¶

Special value that can be used as the stdin , stdout or stderr 自变量对于 Popen and indicates that the special file os.devnull 会被使用。

Added in version 3.3.

subprocess. PIPE ¶: Special value that can be used as the stdin , stdout or stderr 自变量对于 Popen and indicates that a pipe to the standard stream should be opened. Most useful with Popen.communicate() .

subprocess. STDOUT ¶: Special value that can be used as the stderr 自变量对于 Popen and indicates that standard error should go into the same handle as standard output.

exception subprocess. SubprocessError ¶

来自此模块的所有其它异常的基类。

Added in version 3.3.

exception subprocess. TimeoutExpired ¶

子类化的 SubprocessError , raised when a timeout expires while waiting for a child process.

cmd ¶: 用于卵生子级进程的命令。

timeout ¶: 超时 (以秒为单位)。

output ¶: 子级进程的输出，若被捕获通过 run() or check_output() 。否则， None . This is always bytes when any output was captured regardless of the text=True setting. It may remain None 而不是 b'' when no output was observed.

stdout ¶: 输出的别名，对称性于 stderr .

stderr ¶: 子级进程的 stderr 输出，若被捕获通过 run() 。否则， None . This is always bytes when stderr output was captured regardless of the text=True setting. It may remain None 而不是 b'' when no stderr output was observed.

Added in version 3.3.

3.5 版改变： stdout and stderr 属性被添加

exception subprocess. CalledProcessError ¶

子类化的 SubprocessError ，被引发当进程运行通过 check_call() , check_output() ，或 run() (with check=True ) returns a non-zero exit status.

returncode ¶: Exit status of the child process. If the process exited due to a signal, this will be the negative signal number.

cmd ¶: 用于卵生子级进程的命令。

output ¶: 子级进程的输出，若被捕获通过 run() or check_output() 。否则， None .

stdout ¶: 输出的别名，对称性于 stderr .

stderr ¶: 子级进程的 stderr 输出，若被捕获通过 run() 。否则， None .

3.5 版改变： stdout and stderr 属性被添加

经常使用的自变量 ¶

为支持各种使用案例， Popen constructor (and the convenience functions) accept a large number of optional arguments. For most typical use cases, many of these arguments can be safely left at their default values. The arguments that are most commonly needed are:

args is required for all calls and should be a string, or a sequence of program arguments. Providing a sequence of arguments is generally preferred, as it allows the module to take care of any required escaping and quoting of arguments (e.g. to permit spaces in file names). If passing a single string, either shell 必须为 True (see below) or else the string must simply name the program to be executed without specifying any arguments.

stdin , stdout and stderr specify the executed program’s standard input, standard output and standard error file handles, respectively. Valid values are None , PIPE , DEVNULL , an existing file descriptor (a positive integer), and an existing 文件对象 with a valid file descriptor. With the default settings of None , no redirection will occur. PIPE indicates that a new pipe to the child should be created. DEVNULL indicates that the special file os.devnull will be used. Additionally, stderr 可以是 STDOUT , which indicates that the stderr data from the child process should be captured into the same file handle as for stdout .

若 encoding or errors 被指定，或 text (also known as universal_newlines ) is true, the file objects stdin , stdout and stderr will be opened in text mode using the encoding and errors specified in the call or the defaults for io.TextIOWrapper .

For stdin , line ending characters '\n' in the input will be converted to the default line separator os.linesep 。对于 stdout and stderr , all line endings in the output will be converted to '\n' . For more information see the documentation of the io.TextIOWrapper class when the newline argument to its constructor is None .

If text mode is not used, stdin , stdout and stderr will be opened as binary streams. No encoding or line ending conversion is performed.

3.6 版改变：添加 encoding and errors 参数。

3.7 版改变：添加 text parameter as an alias for universal_newlines .

注意

The newlines attribute of the file objects Popen.stdin , Popen.stdout and Popen.stderr are not updated by the Popen.communicate() 方法。

若 shell is True , the specified command will be executed through the shell. This can be useful if you are using Python primarily for the enhanced control flow it offers over most system shells and still want convenient access to other shell features such as shell pipes, filename wildcards, environment variable expansion, and expansion of ~ to a user’s home directory. However, note that Python itself offers implementations of many shell-like features (in particular, glob , fnmatch , os.walk() , os.path.expandvars() , os.path.expanduser() ，和 shutil ).

3.3 版改变：当 universal_newlines is True , the class uses the encoding 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 should be a sequence of program arguments or else a single string or 像路径对象 . By default, the program to execute is the first item in args if args is a sequence. If args is a string, the interpretation is platform-dependent and described below. See the shell and executable arguments for additional differences from the default behavior. Unless otherwise stated, it is recommended to pass args as a sequence.

警告

For maximum reliability, use a fully qualified path for the executable. To search for an unqualified name on PATH ，使用 shutil.which() . On all platforms, passing sys.executable is the recommended way to launch the current Python interpreter again, and use the -m command-line format to launch an installed module.

Resolving the path of executable (or the first item of args ) is platform dependent. For POSIX, see os.execvpe() , and note that when resolving or searching for the executable path, cwd overrides the current working directory and env can override the PATH environment variable. For Windows, see the documentation of the lpApplicationName and lpCommandLine parameters of WinAPI CreateProcess , and note that when resolving or searching for the executable path with shell=False , cwd does not override the current working directory and env cannot override the PATH environment variable. Using a full path avoids all of these variations.

An example of passing some arguments to an external program as a sequence is:

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

在 POSIX (便携式操作系统接口)，若 args is a string, the string is interpreted as the name or path of the program to execute. However, this can only be done if not passing arguments to the program.

注意

It may not be obvious how to break a shell command into a sequence of arguments, especially in complex cases. shlex.split() can illustrate how to determine the correct tokenization for 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!

Note in particular that options (such as -input ) and arguments (such as eggs.txt ) that are separated by whitespace in the shell go in separate list elements, while arguments that need quoting or backslash escaping when used in the shell (such as filenames containing spaces or the echo command shown above) are single list elements.

在 Windows，若 args is a sequence, it will be converted to a string in a manner described in 在 Windows 将自变量序列转换成字符串 . This is because the underlying CreateProcess() operates on strings.

3.6 版改变： args 参数接受像路径对象 if shell is False and a sequence containing path-like objects on POSIX.

3.8 版改变： args 参数接受像路径对象 if shell is False and a sequence containing bytes and path-like objects on Windows.

The shell 自变量 (默认为 False ) specifies whether to use the shell as the program to execute. If shell is True , it is recommended to pass args as a string rather than as a sequence.

在 POSIX (便携式操作系统接口) 采用 shell=True , the shell defaults to /bin/sh 。若 args is a string, the string specifies the command to execute through the shell. This means that the string must be formatted exactly as it would be when typed at the shell prompt. This includes, for example, quoting or backslash escaping filenames with spaces in them. If args is a sequence, the first item specifies the command string, and any additional items will be treated as additional arguments to the shell itself. That is to say, Popen does the equivalent of:

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

在 Windows 采用 shell=True ， COMSPEC environment variable specifies the default shell. The only time you need to specify shell=True on Windows is when the command you wish to execute is built into the shell (e.g. dir or copy ). You do not need shell=True to run a batch file or console-based executable.

注意

阅读安全注意事项章节先于使用 shell=True .

bufsize will be supplied as the corresponding argument to the open() function when creating the stdin/stdout/stderr pipe file objects:

0 means unbuffered (read and write are one system call and can return short)
1 means line buffered (only usable if text=True or universal_newlines=True )
any other positive value means use a buffer of approximately that size
negative bufsize (the default) means the system default of io.DEFAULT_BUFFER_SIZE will be used.

Changed in version 3.3.1: bufsize now defaults to -1 to enable buffering by default to match the behavior that most code expects. In versions prior to Python 3.2.4 and 3.3.1 it incorrectly defaulted to 0 which was unbuffered and allowed short reads. This was unintentional and did not match the behavior of Python 2 as most code expected.

The executable argument specifies a replacement program to execute. It is very seldom needed. When shell=False , executable replaces the program to execute specified by args . However, the original args is still passed to the program. Most programs treat the program specified by args as the command name, which can then be different from the program actually executed. On POSIX, the args name becomes the display name for the executable in utilities such as ps 。若 shell=True , on POSIX the executable argument specifies a replacement shell for the default /bin/sh .

3.6 版改变： executable 参数接受像路径对象 on POSIX.

3.8 版改变： executable parameter accepts a bytes and 像路径对象在 Windows。

stdin , stdout and stderr specify the executed program’s standard input, standard output and standard error file handles, respectively. Valid values are None , PIPE , DEVNULL , an existing file descriptor (a positive integer), and an existing 文件对象 with a valid file descriptor. With the default settings of None , no redirection will occur. PIPE indicates that a new pipe to the child should be created. DEVNULL indicates that the special file os.devnull will be used. Additionally, stderr 可以是 STDOUT , which indicates that the stderr data from the applications should be captured into the same file handle as for stdout .

若 preexec_fn is set to a callable object, this object will be called in the child process just before the child is executed. (POSIX only)

警告

The preexec_fn parameter is NOT SAFE to use in the presence of threads in your application. The child process could deadlock before exec is called.

注意

若需要为子级修改环境使用 env 参数而不是处理它在 preexec_fn 。 start_new_session and process_group parameters should take the place of code using preexec_fn to call os.setsid() or os.setpgid() in the child.

3.8 版改变： The preexec_fn parameter is no longer supported in subinterpreters. The use of the parameter in a subinterpreter raises RuntimeError . The new restriction may affect applications that are deployed in mod_wsgi, uWSGI, and other embedded environments.

若 close_fds is true, all file descriptors except 0 , 1 and 2 will be closed before the child process is executed. Otherwise when close_fds is false, file descriptors obey their inheritable flag as described in 文件描述符的继承 .

在 Windows，若 close_fds is true then no handles will be inherited by the child process unless explicitly passed in the handle_list 元素的 STARTUPINFO.lpAttributeList , or by standard handle redirection.

3.2 版改变：默认为 close_fds was changed from False to what is described above.

3.7 版改变： On Windows the default for close_fds was changed from False to True when redirecting the standard handles. It’s now possible to set close_fds to True when redirecting the standard handles.

pass_fds is an optional sequence of file descriptors to keep open between the parent and child. Providing any pass_fds forces close_fds 到 True . (POSIX only)

3.2 版改变： The pass_fds 参数被添加。

若 cwd 不是 None , the function changes the working directory to cwd before executing the child. cwd can be a string, bytes or 像路径 object. On POSIX, the function looks for executable (or for the first item in args ) relative to cwd if the executable path is a relative path.

3.6 版改变： cwd 参数接受像路径对象 on POSIX.

3.7 版改变： cwd 参数接受像路径对象在 Windows。

3.8 版改变： cwd parameter accepts a bytes object on Windows.

若 restore_signals is true (the default) all signals that Python has set to SIG_IGN are restored to SIG_DFL in the child process before the exec. Currently this includes the SIGPIPE, SIGXFZ and SIGXFSZ signals. (POSIX only)

3.2 版改变： restore_signals 被添加。

若 start_new_session 为 True setsid() system call will be made in the child process prior to the execution of the subprocess.

可用性 : POSIX

3.2 版改变： start_new_session 被添加。

若 process_group is a non-negative integer, the setpgid(0, value) system call will be made in the child process prior to the execution of the subprocess.

可用性 : POSIX

3.11 版改变： process_group 被添加。

若 group 不是 None , the setregid() system call will be made in the child process prior to the execution of the subprocess. If the provided value is a string, it will be looked up via grp.getgrnam() and the value in gr_gid will be used. If the value is an integer, it will be passed verbatim. (POSIX only)

可用性 : POSIX

Added in version 3.9.

若 extra_groups 不是 None , the setgroups() system call will be made in the child process prior to the execution of the subprocess. Strings provided in extra_groups will be looked up via grp.getgrnam() and the values in gr_gid will be used. Integer values will be passed verbatim. (POSIX only)

可用性 : POSIX

Added in version 3.9.

若 user 不是 None , the setreuid() system call will be made in the child process prior to the execution of the subprocess. If the provided value is a string, it will be looked up via pwd.getpwnam() and the value in pw_uid will be used. If the value is an integer, it will be passed verbatim. (POSIX only)

可用性 : POSIX

Added in version 3.9.

若 umask is not negative, the umask() system call will be made in the child process prior to the execution of the subprocess.

可用性 : POSIX

Added in version 3.9.

若 env 不是 None , it must be a mapping that defines the environment variables for the new process; these are used instead of the default behavior of inheriting the current process’ environment. This mapping can be str to str on any platform or bytes to bytes on POSIX platforms much like os.environ or os.environb .

注意

若指定， env 必须提供要执行程序要求的任何变量。在 Windows，为运行并行汇编指定 env must 包括有效 SystemRoot .

若 encoding or errors 被指定，或 text is true, the file objects stdin , stdout and stderr are opened in text mode with the specified encoding and errors , as described above in 经常使用的自变量。 universal_newlines argument is equivalent to text and is provided for backwards compatibility. By default, file objects are opened in binary mode.

Added in version 3.6: encoding and errors 被添加。

Added in version 3.7: text 被添加作为更可读的别名化 universal_newlines .

若给定， startupinfo 将是 STARTUPINFO 对象，会被传递给底层 CreateProcess 函数。

若给定， creationflags , can be one or more of the following flags:

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

pipesize can be used to change the size of the pipe when PIPE is used for stdin , stdout or stderr . The size of the pipe is only changed on platforms that support this (only Linux at this time of writing). Other platforms will ignore this parameter.

3.10 版改变：添加 pipesize 参数。

Popen objects are supported as context managers via the with statement: on exit, standard file descriptors are closed, and the process is waited for.

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 warning if the child process is still running.

3.8 版改变： Popen 可以使用 os.posix_spawn() in some cases for better performance. On Windows Subsystem for Linux and QEMU User Emulation, Popen constructor using os.posix_spawn() no longer raise an exception on errors like missing program, but the child process fails with a non-zero returncode .

异常 ¶

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

最常引发的异常是 OSError . This occurs, for example, when trying to execute a non-existent file. Applications should prepare for OSError exceptions. Note that, when shell=True , OSError will be raised by the child only if the selected shell itself was not found. To determine if the shell failed to find the requested application, it is necessary to check the return code or output from the subprocess.

A ValueError 会被引发若 Popen is called with invalid arguments.

check_call() and check_output() 会引发 CalledProcessError if the called process returns a non-zero return code.

All of the functions and methods that accept a timeout parameter, such as run() and Popen.communicate() 会引发 TimeoutExpired if the timeout expires before the process exits.

此模块中定义的异常都继承自 SubprocessError .

Added in version 3.3: The SubprocessError 基类被添加。

安全注意事项 ¶

Unlike some other popen functions, this library will not implicitly choose to call a system shell. This means that all characters, including shell metacharacters, can safely be passed to child processes. If the shell is invoked explicitly, via shell=True , it is the application’s responsibility to ensure that all whitespace and metacharacters are quoted appropriately to avoid shell injection vulnerabilities. On some platforms , it is possible to use shlex.quote() for this escaping.

On Windows, batch files ( *.bat or *.cmd ) may be launched by the operating system in a system shell regardless of the arguments passed to this library. This could result in arguments being parsed according to shell rules, but without any escaping added by Python. If you are intentionally launching a batch file with arguments from untrusted sources, consider passing shell=True to allow Python to escape special characters. See gh-114539 for additional discussion.

Popen 对象 ¶

实例化的 Popen 类具有下列方法：

Popen. poll ( ) ¶: 校验子级进程是否已终止。设置并返回 returncode 属性。否则，返回 None .

Popen. wait ( timeout = None ) ¶

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

若进程未终止后于 timeout 秒，引发 TimeoutExpired 异常。捕获此异常并试着等待是安全的。

注意

这会死锁，当使用 stdout=PIPE or stderr=PIPE 子级进程生成足够输出到管道，这会阻塞等待的 OS 管道缓冲以接受更多数据。使用 Popen.communicate() 当使用管道时能避免这种情况。

注意

当 timeout parameter is not None , then (on POSIX) the function is implemented using a busy loop (non-blocking call and short sleeps). Use the asyncio 模块对于异步等待：见 asyncio.create_subprocess_exec .

3.3 版改变： timeout 被添加。

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

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

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

注意，若想要把数据发送给进程的 stdin，需要创建 Popen 对象采用 stdin=PIPE 。同样，要获取任何东西除了 None 在结果元组，需要给出 stdout=PIPE and/or 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 发送给进程，启动时采用 creationflags 参数包括 CREATE_NEW_PROCESS_GROUP .

Popen. terminate ( ) ¶: Stop the child. On POSIX OSs the method sends SIGTERM to the child. On Windows the Win32 API function TerminateProcess() 被调用以停止子级。

Popen. kill ( ) ¶: 杀除子级。在 POSIX (便携式操作系统接口) OS，函数将 SIGKILL 发送给子级。在 Windows kill() 是别名化的 terminate() .

The following attributes are also set by the class for you to access. Reassigning them to new values is unsupported:

Popen. args ¶

The args 自变量是被传递给 Popen – 程序自变量 (或单个字符串) 的序列。

Added in version 3.3.

Popen. stdin ¶: 若 stdin 自变量为 PIPE ，此属性是可写流对象返回通过 open() 。若 encoding or errors 自变量有指定或 text or universal_newlines 自变量为 True ，流是文本流，否则流是字节流。若 stdin 自变量不是 PIPE ，此属性为 None .

Popen. stdout ¶: 若 stdout 自变量为 PIPE ，此属性是可读流对象返回通过 open() 。从流读取提供来自子级进程的输出。若 encoding or errors 自变量有指定或 text or universal_newlines 自变量为 True ，流是文本流，否则流是字节流。若 stdout 自变量不是 PIPE ，此属性为 None .

Popen. stderr ¶: 若 stderr 自变量为 PIPE ，此属性是可读流对象返回通过 open() 。从流读取提供来自子级进程的错误输出。若 encoding or errors 自变量有指定或 text or universal_newlines 自变量为 True ，流是文本流，否则流是字节流。若 stderr 自变量不是 PIPE ，此属性为 None .

警告

使用 communicate() 而不是 .stdin.write , .stdout.read or .stderr.read 能避免由于任何其它 OS 管道缓冲填满和阻塞子级进程而导致死锁。

Popen. pid ¶

子级进程的进程 ID。

注意：若设置 shell 自变量对于 True ，这是卵生 Shell 的进程 ID。

Popen. returncode ¶

The child return code. Initially None , returncode is set by a call to the poll() , wait() ，或 communicate() methods if they detect that the process has terminated.

A None value indicates that the process hadn’t yet terminated at the time of the last method call.

负值 -N 指示子级被终止，通过信号 N (仅 POSIX)。

Windows Popen 帮手 ¶

The STARTUPINFO 类和以下常量只可用于 Windows。

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

部分支持 Windows STARTUPINFO 结构用于 Popen 创建。通过作为仅关键字自变量传递，可以设置下列属性。

3.7 版改变：添加仅关键字自变量支持。

dwFlags ¶

A bit field that determines whether certain STARTUPINFO attributes are used when the process creates a window.

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

hStdInput ¶: 若 dwFlags 指定 STARTF_USESTDHANDLES , this attribute is the standard input handle for the process. If STARTF_USESTDHANDLES is not specified, the default for standard input is the keyboard buffer.

hStdOutput ¶: 若 dwFlags 指定 STARTF_USESTDHANDLES , this attribute is the standard output handle for the process. Otherwise, this attribute is ignored and the default for standard output is the console window’s buffer.

hStdError ¶: 若 dwFlags 指定 STARTF_USESTDHANDLES , this attribute is the standard error handle for the process. Otherwise, this attribute is ignored and the default for standard error is the console window’s buffer.

wShowWindow ¶

若 dwFlags 指定 STARTF_USESHOWWINDOW , this attribute can be any of the values that can be specified in the nCmdShow parameter for the ShowWindow function, except for SW_SHOWDEFAULT . Otherwise, this attribute is ignored.

SW_HIDE is provided for this attribute. It is used when Popen is called with shell=True .

lpAttributeList ¶

A dictionary of additional attributes for process creation as given in STARTUPINFOEX ，见 UpdateProcThreadAttribute .

支持的属性：

handle_list

Sequence of handles that will be inherited. close_fds must be true if non-empty.

The handles must be temporarily made inheritable by os.set_handle_inheritable() 当被传递给 Popen 构造函数，否则 OSError will be raised with Windows error ERROR_INVALID_PARAMETER (87).

警告

In a multithreaded process, use caution to avoid leaking handles that are marked inheritable when combining this feature with concurrent calls to other process creation functions that inherit all handles such as os.system() . This also applies to standard handle redirection, which temporarily creates inheritable handles.

Added in version 3.7.

Windows 常量 ¶

The subprocess 模块暴露以下常量。

subprocess. STD_INPUT_HANDLE ¶: The standard input device. Initially, this is the console input buffer, CONIN$ .

subprocess. STD_OUTPUT_HANDLE ¶: The standard output device. Initially, this is the active console screen buffer, CONOUT$ .

subprocess. STD_ERROR_HANDLE ¶: The standard error device. Initially, this is the active console screen buffer, CONOUT$ .

subprocess. SW_HIDE ¶: 隐藏窗口。将激活另一窗口。

subprocess. STARTF_USESTDHANDLES ¶: Specifies that the STARTUPINFO.hStdInput , STARTUPINFO.hStdOutput ，和 STARTUPINFO.hStdError attributes contain additional information.

subprocess. STARTF_USESHOWWINDOW ¶: Specifies that the STARTUPINFO.wShowWindow attribute contains additional information.

subprocess. CREATE_NEW_CONSOLE ¶: The new process has a new console, instead of inheriting its parent’s console (the default).

subprocess. CREATE_NEW_PROCESS_GROUP ¶

A Popen creationflags parameter to specify that a new process group will be created. This flag is necessary for using os.kill() on the subprocess.

此标志会被忽略，若 CREATE_NEW_CONSOLE 被指定。

subprocess. ABOVE_NORMAL_PRIORITY_CLASS ¶

A Popen creationflags parameter to specify that a new process will have an above average priority.

Added in version 3.7.

subprocess. BELOW_NORMAL_PRIORITY_CLASS ¶

A Popen creationflags parameter to specify that a new process will have a below average priority.

Added in version 3.7.

subprocess. HIGH_PRIORITY_CLASS ¶

A Popen creationflags parameter to specify that a new process will have a high priority.

Added in version 3.7.

subprocess. IDLE_PRIORITY_CLASS ¶

A Popen creationflags parameter to specify that a new process will have an idle (lowest) priority.

Added in version 3.7.

subprocess. NORMAL_PRIORITY_CLASS ¶

A Popen creationflags parameter to specify that a new process will have an normal priority. (default)

Added in version 3.7.

subprocess. REALTIME_PRIORITY_CLASS ¶

A Popen creationflags parameter to specify that a new process will have realtime priority. You should almost never use REALTIME_PRIORITY_CLASS, because this interrupts system threads that manage mouse input, keyboard input, and background disk flushing. This class can be appropriate for applications that “talk” directly to hardware or that perform brief tasks that should have limited interruptions.

Added in version 3.7.

subprocess. CREATE_NO_WINDOW ¶

A Popen creationflags parameter to specify that a new process will not create a window.

Added in version 3.7.

subprocess. DETACHED_PROCESS ¶

A Popen creationflags parameter to specify that a new process will not inherit its parent’s console. This value cannot be used with CREATE_NEW_CONSOLE.

Added in version 3.7.

subprocess. CREATE_DEFAULT_ERROR_MODE ¶

A Popen creationflags parameter to specify that a new process does not inherit the error mode of the calling process. Instead, the new process gets the default error mode. This feature is particularly useful for multithreaded shell applications that run with hard errors disabled.

Added in version 3.7.

subprocess. CREATE_BREAKAWAY_FROM_JOB ¶

A Popen creationflags parameter to specify that a new process is not associated with the job.

Added in version 3.7.

较旧的高级 API ¶

在 Python 3.5 之前，这 3 个函数由子进程的高级 API 构成。现在，可以使用 run() 在很多情况下，但许多现有代码调用这些函数。

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

运行的命令描述通过 args . Wait for command to complete, then return the returncode 属性。

需要捕获 stdout 或 stderr 的代码应使用 run() 代替：

run(...).returncode

To suppress stdout or stderr, supply a value of DEVNULL .

The arguments shown above are merely some common ones. The full function signature is the same as that of the Popen constructor - this function passes all supplied arguments other than timeout directly through to that interface.

注意

不使用 stdout=PIPE or stderr=PIPE with this function. The child process will block if it generates enough output to a pipe to fill up the OS pipe buffer as the pipes are not being read from.

3.3 版改变： timeout 被添加。

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

Run command with arguments. Wait for command to complete. If the return code was zero then return, otherwise raise CalledProcessError 。 CalledProcessError object will have the return code in the returncode attribute. If check_call() was unable to start the process it will propagate the exception that was raised.

需要捕获 stdout 或 stderr 的代码应使用 run() 代替：

run(..., check=True)

To suppress stdout or stderr, supply a value of DEVNULL .

注意

不使用 stdout=PIPE or stderr=PIPE with this function. The child process will block if it generates enough output to a pipe to fill up the OS pipe buffer as the pipes are not being read from.

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

Run command with arguments and return its output.

If the return code was non-zero it raises a CalledProcessError 。 CalledProcessError object will have the return code in the returncode attribute and any output in the output 属性。

这相当于：

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

The arguments shown above are merely some common ones. The full function signature is largely the same as that of run() - most arguments are passed directly through to that interface. One API deviation from run() behavior exists: passing input=None will behave the same as input=b'' (或 input='' , depending on other arguments) rather than using the parent’s standard input file handle.

By default, this function will return the data as encoded bytes. The actual encoding of the output data may depend on the command being invoked, so the decoding to text will often need to be handled at the application level.

This behaviour may be overridden by setting text , encoding , errors ，或 universal_newlines to True as described in 经常使用的自变量 and run() .

To also capture standard error in the result, use 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'

Added in version 3.1.

3.3 版改变： timeout 被添加。

3.4 版改变：支持 input 关键词自变量被添加。

3.6 版改变： encoding and errors 被添加。见 run() 了解细节。

Added in version 3.7: text 被添加作为更可读的别名化 universal_newlines .

替换旧函数采用 `subprocess` 模块 ¶

In this section, “a becomes b” means that b can be used as a replacement for a.

注意

All “a” functions in this section fail (more or less) silently if the executed program cannot be found; the “b” replacements raise OSError 代替。

In addition, the replacements using check_output() will fail with a CalledProcessError if the requested operation produces a non-zero return code. The output is still available as the output attribute of the raised exception.

In the following examples, we assume that the relevant functions have already been imported from the 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]

The p1.stdout.close() call after starting the p2 is important in order for p1 to receive a SIGPIPE if p2 exits before p1.

Alternatively, for trusted input, the shell’s own pipeline support may still be used directly:

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)

注意事项：

Calling the program through the shell is usually not required.
The call() return value is encoded differently to that of os.system() .
The os.system() function ignores SIGINT and SIGQUIT signals while the command is running, but the caller must do this separately when using the 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()` , `os.popen2()` , `os.popen3()` ¶

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

替换函数来自 `popen2` 模块 ¶

注意

If the cmd argument to popen2 functions is a string, the command is executed through /bin/sh. If it is a list, the command is directly executed.

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

popen2.Popen3 and popen2.Popen4 basically work as subprocess.Popen ，除了：

Popen 引发异常若执行失败。
The capturestderr 自变量被替换采用 stderr 自变量。
stdin=PIPE and stdout=PIPE 必须指定。
popen2 closes all file descriptors by default, but you have to specify close_fds=True with Popen to guarantee this behavior on all platforms or past Python versions.

传统 Shell 援引函数 ¶

This module also provides the following legacy functions from the 2.x commands module. These operations implicitly invoke the system shell and none of the guarantees described above regarding security and exception handling consistency are valid for these functions.

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

返回 (exitcode, output) 对于执行 cmd 在 Shell。

执行字符串 cmd 在 Shell 采用 Popen.check_output() 并返回 2 元素元组 (exitcode, output) . encoding and errors are used to decode output; see the notes on 经常使用的自变量了解更多细节。

A trailing newline is stripped from the output. The exit code for the command can be interpreted as the return code of subprocess. Example:

>>> 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 支持。

The function now returns (exitcode, output) instead of (status, output) as it did in Python 3.3.3 and earlier. exitcode has the same value as returncode .

3.11 版改变：添加 encoding and errors 参数。

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

返回输出 (stdout 和 stderr) 对于执行 cmd 在 Shell。

像 getstatusoutput() , except the exit code is ignored and the return value is a string containing the command’s output. Example:

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

可用性：Unix、Windows。

3.3.4 版改变：添加 Windows 支持

3.11 版改变：添加 encoding and errors 参数。

注意事项 ¶

在 Windows 将自变量序列转换成字符串 ¶

在 Windows， args sequence is converted to a string that can be parsed using the following rules (which correspond to the rules used by the MS C runtime):

Arguments are delimited by white space, which is either a space or a tab.
A string surrounded by double quotation marks is interpreted as a single argument, regardless of white space contained within. A quoted string can be embedded in an argument.
A double quotation mark preceded by a backslash is interpreted as a literal double quotation mark.
Backslashes are interpreted literally, unless they immediately precede a double quotation mark.
If backslashes immediately precede a double quotation mark, every pair of backslashes is interpreted as a literal backslash. If the number of backslashes is odd, the last backslash escapes the next double quotation mark as described in rule 3.

另请参阅

shlex: 提供剖析和转义命令行函数的模块。

禁用使用 `vfork()` or `posix_spawn()` ¶

在 Linux， subprocess 默认使用 vfork() system call internally when it is safe to do so rather than fork() . This greatly improves performance.

If you ever encounter a presumed highly unusual situation where you need to prevent vfork() from being used by Python, you can set the subprocess._USE_VFORK attribute to a false value.

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

Setting this has no impact on use of posix_spawn() which could use vfork() internally within its libc implementation. There is a similar subprocess._USE_POSIX_SPAWN attribute if you need to prevent use of that.

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

It is safe to set these to false on any Python version. They will have no effect on older versions when unsupported. Do not assume the attributes are available to read. Despite their names, a true value does not indicate that the corresponding function will be used, only that it may be.

Please file issues any time you have to use these private knobs with a way to reproduce the issue you were seeing. Link to that issue from a comment in your code.

Added in version 3.8: _USE_POSIX_SPAWN

Added in version 3.11: _USE_VFORK

内容表

subprocess — 子进程管理

上一话题

concurrent.futures — 发起并行任务

下一话题

sched — 事件调度器

本页

报告 Bug
展示源

快速搜索

键入搜索术语或模块、类、函数名称。

首页
Python 3.12.4
索引
模块
下一
上一
Python 标准库
并发执行
subprocess — 子进程管理