17.1. subprocess — Subprocess management — Python 2.7.18 documentation (original) (raw)

Execute a child program in a new process. On Unix, the class usesos.execvp()-like behavior to execute the child program. On Windows, the class uses the Windows CreateProcess() function. The arguments toPopen are as follows.

args should be a sequence of program arguments or else a single string. 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.

On Unix, if 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.

Note

shlex.split() can be useful when determining the correct tokenization for args, especially in complex cases:

import shlex, subprocess command_line = raw_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.

On Windows, if args is a sequence, it will be converted to a string in a manner described in Converting an argument sequence to a string on Windows. This is because the underlying CreateProcess() operates on strings.

The shell argument (which defaults to 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.

On Unix with shell=True, the shell defaults to /bin/sh. If_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], ...])

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

Warning

Passing shell=True can be a security hazard if combined with untrusted input. See the warning under Frequently Used Argumentsfor details.

bufsize, if given, has the same meaning as the corresponding argument to the built-in open() function: 0 means unbuffered, 1 means line buffered, any other positive value means use a buffer of (approximately) that size. A negative bufsize means to use the system default, which usually means fully buffered. The default value for bufsize is 0 (unbuffered).

Note

If you experience performance issues, it is recommended that you try to enable buffering by setting bufsize to either -1 or a large enough positive value (such as 4096).

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 Unix, the args name becomes the display name for the executable in utilities such asps. If shell=True, on Unix the executable argument specifies a replacement shell for the default /bin/sh.

stdin, stdout and stderr specify the executed program’s standard input, standard output and standard error file handles, respectively. Valid values are PIPE, an existing file descriptor (a positive integer), an existing file object, and None. PIPE indicates that a new pipe to the child should be created. With the default settings of None, no redirection will occur; the child’s file handles will be inherited from the parent. Additionally, stderr can be STDOUT, which indicates that the stderr data from the child process should be captured into the same file handle as for stdout.

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

If close_fds is true, all file descriptors except 0, 1 and2 will be closed before the child process is executed. (Unix only). Or, on Windows, if close_fds is true then no handles will be inherited by the child process. Note that on Windows, you cannot set close_fds to true and also redirect the standard handles by setting stdin, stdout or stderr.

If cwd is not None, the child’s current directory will be changed to cwd_before it is executed. Note that this directory is not considered when searching the executable, so you can’t specify the program’s path relative to_cwd.

If env is not None, it must be a mapping that defines the environment variables for the new process; these are used instead of inheriting the current process’ environment, which is the default behavior.

Note

If specified, env must provide any variables required for the program to execute. On Windows, in order to run aside-by-side assembly the specified env must include a validSystemRoot.

If universal_newlines is True, the file objects stdout and _stderr_are opened as text files in universal newlines mode. Lines may be terminated by any of '\n', the Unix end-of-line convention, '\r', the old Macintosh convention or '\r\n', the Windows convention. All of these external representations are seen as '\n' by the Python program.

Note

This feature is only available if Python is built with universal newline support (the default). Also, the newlines attribute of the file objectsstdout, stdin and stderr are not updated by the communicate() method.

If given, startupinfo will be a STARTUPINFO object, which is passed to the underlying CreateProcess function.creationflags, if given, can be CREATE_NEW_CONSOLE orCREATE_NEW_PROCESS_GROUP. (Windows only)