17.5.1.Using thesubprocess Module¶

The recommended approach to invoking subprocesses is to use therun()function for all use cases it can handle. For more advanced use cases, theunderlyingPopen interface can be used directly.

Therun() function was added in Python 3.5; if you need to retaincompatibility with older versions, see theOlder high-level API section.

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

Run the command described byargs. Wait for command to complete, thenreturn aCompletedProcess instance.

The arguments shown above are merely the most common ones, described belowinFrequently Used Arguments (hence the use of keyword-only notationin the abbreviated signature). The full function signature is largely thesame as that of thePopen constructor - apart fromtimeout,input andcheck, all the arguments to this function are passed through tothat interface.

This does not capture stdout or stderr by default. To do so, passPIPE for thestdout and/orstderr arguments.

Thetimeout argument is passed toPopen.communicate(). If the timeoutexpires, the child process will be killed and waited for. TheTimeoutExpired exception will be re-raised after the child processhas terminated.

Theinput argument is passed toPopen.communicate() and thus to thesubprocess’s stdin. If used it must be a byte sequence, or a string ifencoding orerrors is specified oruniversal_newlines is true. Whenused, the internalPopen object is automatically created withstdin=PIPE, and thestdin argument may not be used as well.

Ifcheck is true, and the process exits with a non-zero exit code, aCalledProcessError exception will be raised. Attributes of thatexception hold the arguments, the exit code, and stdout and stderr if theywere captured.

Ifencoding orerrors are specified, oruniversal_newlines is true,file objects for stdin, stdout and stderr are opened in text mode using thespecifiedencoding anderrors or theio.TextIOWrapper default.Otherwise, file objects are opened in binary mode.

Ifenv is notNone, it must be a mapping that defines the environmentvariables for the new process; these are used instead of the defaultbehavior of inheriting the current process’ environment. It is passed directlytoPopen.

Examples:

>>>subprocess.run(["ls","-l"])# doesn't capture outputCompletedProcess(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"],stdout=subprocess.PIPE)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')

New in version 3.5.

Changed in version 3.6:Addedencoding anderrors parameters

classsubprocess.CompletedProcess¶

The return value fromrun(), representing a process that has finished.

args¶

The arguments used to launch the process. This may be a list or a string.

returncode¶

Exit status of the child process. Typically, an exit status of 0 indicatesthat it ran successfully.

A negative value-N indicates that the child was terminated by signalN (POSIX only).

stdout¶

Captured stdout from the child process. A bytes sequence, or a string ifrun() was called with an encoding or errors.None if stdout was notcaptured.

If you ran the process withstderr=subprocess.STDOUT, stdout andstderr will be combined in this attribute, andstderr will beNone.

stderr¶

Captured stderr from the child process. A bytes sequence, or a string ifrun() was called with an encoding or errors.None if stderr was notcaptured.

check_returncode()¶

Ifreturncode is non-zero, raise aCalledProcessError.

New in version 3.5.

subprocess.DEVNULL¶

Special value that can be used as thestdin,stdout orstderr argumenttoPopen and indicates that the special fileos.devnullwill be used.

New in version 3.3.

subprocess.PIPE¶

Special value that can be used as thestdin,stdout orstderr argumenttoPopen and indicates that a pipe to the standard stream should beopened. Most useful withPopen.communicate().

subprocess.STDOUT¶

Special value that can be used as thestderr argument toPopen andindicates that standard error should go into the same handle as standardoutput.

exceptionsubprocess.SubprocessError¶

Base class for all other exceptions from this module.

New in version 3.3.

exceptionsubprocess.TimeoutExpired¶

Subclass ofSubprocessError, raised when a timeout expireswhile waiting for a child process.

cmd¶

Command that was used to spawn the child process.

timeout¶

Timeout in seconds.

output¶

Output of the child process if it was captured byrun() orcheck_output(). Otherwise,None.

stdout¶

Alias for output, for symmetry withstderr.

stderr¶

Stderr output of the child process if it was captured byrun().Otherwise,None.

New in version 3.3.

Changed in version 3.5:stdout andstderr attributes added

exceptionsubprocess.CalledProcessError¶

Subclass ofSubprocessError, raised when a process run bycheck_call() orcheck_output() returns a non-zero exit status.

returncode¶

Exit status of the child process. If the process exited due to asignal, this will be the negative signal number.

cmd¶

Command that was used to spawn the child process.

output¶

Output of the child process if it was captured byrun() orcheck_output(). Otherwise,None.

stdout¶

Alias for output, for symmetry withstderr.

stderr¶

Stderr output of the child process if it was captured byrun().Otherwise,None.

Changed in version 3.5:stdout andstderr attributes added

17.5.2.Security Considerations¶

Unlike some other popen functions, this implementation will neverimplicitly 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, viashell=True, it is the application’sresponsibility to ensure that all whitespace and metacharacters arequoted appropriately to avoidshell injectionvulnerabilities.

When usingshell=True, theshlex.quote() function can beused to properly escape whitespace and shell metacharacters in stringsthat are going to be used to construct shell commands.

17.5.3.Popen Objects¶

Instances of thePopen class have the following methods:

Popen.poll()¶

Check if child process has terminated. Set and returnreturncode attribute. Otherwise, returnsNone.

Popen.wait(timeout=None)¶

Wait for child process to terminate. Set and returnreturncode attribute.

If the process does not terminate aftertimeout seconds, raise aTimeoutExpired exception. It is safe to catch this exception andretry the wait.

Note

This will deadlock when usingstdout=PIPE orstderr=PIPEand the child process generates enough output to a pipe such thatit blocks waiting for the OS pipe buffer to accept more data.UsePopen.communicate() when using pipes to avoid that.

Note

The function is implemented using a busy loop (non-blocking call andshort sleeps). Use theasyncio module for an asynchronous wait:seeasyncio.create_subprocess_exec.

Changed in version 3.3:timeout was added.

Deprecated since version 3.4:Do not use theendtime parameter. It is was unintentionallyexposed in 3.3 but was left undocumented as it was intended to beprivate for internal use. Usetimeout instead.

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

Interact with process: Send data to stdin. Read data from stdout and stderr,until end-of-file is reached. Wait for process to terminate. The optionalinput argument should be data to be sent to the child process, orNone, if no data should be sent to the child. If streams were opened intext mode,input must be a string. Otherwise, it must be bytes.

communicate() returns a tuple(stdout_data,stderr_data).The data will be strings if streams were opened in text mode; otherwise,bytes.

Note that if you want to send data to the process’s stdin, you need to createthe Popen object withstdin=PIPE. Similarly, to get anything other thanNone in the result tuple, you need to givestdout=PIPE and/orstderr=PIPE too.

If the process does not terminate aftertimeout seconds, aTimeoutExpired exception will be raised. Catching this exception andretrying communication will not lose any output.

The child process is not killed if the timeout expires, so in order tocleanup properly a well-behaved application should kill the child process andfinish communication:

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

Note

The data read is buffered in memory, so do not use this method if the datasize is large or unlimited.

Changed in version 3.3:timeout was added.

Popen.send_signal(signal)¶

Sends the signalsignal to the child.

Note

On Windows, SIGTERM is an alias forterminate(). CTRL_C_EVENT andCTRL_BREAK_EVENT can be sent to processes started with acreationflagsparameter which includesCREATE_NEW_PROCESS_GROUP.

Popen.terminate()¶

Stop the child. On Posix OSs the method sends SIGTERM to thechild. On Windows the Win32 API functionTerminateProcess() is calledto stop the child.

Popen.kill()¶

Kills the child. On Posix OSs the function sends SIGKILL to the child.On Windowskill() is an alias forterminate().

The following attributes are also available:

Popen.args¶

Theargs argument as it was passed toPopen – asequence of program arguments or else a single string.

New in version 3.3.

Popen.stdin¶

If thestdin argument wasPIPE, this attribute is a writeablestream object as returned byopen(). If theencoding orerrorsarguments were specified or theuniversal_newlines argument wasTrue,the stream is a text stream, otherwise it is a byte stream. If thestdinargument was notPIPE, this attribute isNone.

Popen.stdout¶

If thestdout argument wasPIPE, this attribute is a readablestream object as returned byopen(). Reading from the stream providesoutput from the child process. If theencoding orerrors arguments werespecified or theuniversal_newlines argument wasTrue, the stream is atext stream, otherwise it is a byte stream. If thestdout argument was notPIPE, this attribute isNone.

Popen.stderr¶

If thestderr argument wasPIPE, this attribute is a readablestream object as returned byopen(). Reading from the stream provideserror output from the child process. If theencoding orerrors argumentswere specified or theuniversal_newlines argument wasTrue, the streamis a text stream, otherwise it is a byte stream. If thestderr argument wasnotPIPE, this attribute isNone.

Popen.pid¶

The process ID of the child process.

Note that if you set theshell argument toTrue, this is the process IDof the spawned shell.

Popen.returncode¶

The child return code, set bypoll() andwait() (and indirectlybycommunicate()). ANone value indicates that the processhasn’t terminated yet.

A negative value-N indicates that the child was terminated by signalN (POSIX only).

17.5.4.Windows Popen Helpers¶

TheSTARTUPINFO class and following constants are only availableon Windows.

classsubprocess.STARTUPINFO¶

Partial support of the WindowsSTARTUPINFOstructure is used forPopen creation.

dwFlags¶

A bit field that determines whether certainSTARTUPINFOattributes are used when the process creates a window.

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

hStdInput¶

IfdwFlags specifiesSTARTF_USESTDHANDLES, this attributeis the standard input handle for the process. IfSTARTF_USESTDHANDLES is not specified, the default for standardinput is the keyboard buffer.

hStdOutput¶

IfdwFlags specifiesSTARTF_USESTDHANDLES, this attributeis the standard output handle for the process. Otherwise, this attributeis ignored and the default for standard output is the console window’sbuffer.

hStdError¶

IfdwFlags specifiesSTARTF_USESTDHANDLES, this attributeis the standard error handle for the process. Otherwise, this attribute isignored and the default for standard error is the console window’s buffer.

wShowWindow¶

IfdwFlags specifiesSTARTF_USESHOWWINDOW, this attributecan be any of the values that can be specified in thenCmdShowparameter for theShowWindowfunction, except forSW_SHOWDEFAULT. Otherwise, this attribute isignored.

SW_HIDE is provided for this attribute. It is used whenPopen is called withshell=True.

17.5.5.Older high-level API¶

Prior to Python 3.5, these three functions comprised the high level API tosubprocess. You can now userun() in many cases, but lots of existing codecalls these functions.

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

Run the command described byargs. Wait for command to complete, thenreturn thereturncode attribute.

This is equivalent to:

run(...).returncode

(except that theinput andcheck parameters are not supported)

The arguments shown above are merely the mostcommon ones. The full function signature is largely thesame as that of thePopen constructor - this function passes allsupplied arguments other thantimeout directly through to that interface.

Note

Do not usestdout=PIPE orstderr=PIPE with thisfunction. The child process will block if it generates enoughoutput to a pipe to fill up the OS pipe buffer as the pipes arenot being read from.

Changed in version 3.3:timeout was added.

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

Run command with arguments. Wait for command to complete. If the returncode was zero then return, otherwise raiseCalledProcessError. TheCalledProcessError object will have the return code in thereturncode attribute.

This is equivalent to:

run(...,check=True)

(except that theinput parameter is not supported)

The arguments shown above are merely the mostcommon ones. The full function signature is largely thesame as that of thePopen constructor - this function passes allsupplied arguments other thantimeout directly through to that interface.

Note

Do not usestdout=PIPE orstderr=PIPE with thisfunction. The child process will block if it generates enoughoutput to a pipe to fill up the OS pipe buffer as the pipes arenot being read from.

Changed in version 3.3:timeout was added.

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

Run command with arguments and return its output.

If the return code was non-zero it raises aCalledProcessError. TheCalledProcessError object will have the return code in thereturncode attribute and any output in theoutput attribute.

This is equivalent to:

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

The arguments shown above are merely the most common ones.The full function signature is largely the same as that ofrun() -most arguments are passed directly through to that interface.However, explicitly passinginput=None to inherit the parent’sstandard input file handle is not supported.

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

This behaviour may be overridden by settinguniversal_newlines toTrue as described above inFrequently Used Arguments.

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

New in version 3.1.

Changed in version 3.3:timeout was added.

Changed in version 3.4:Support for theinput keyword argument was added.

Changed in version 3.6:encoding anderrors were added. Seerun() for details.

17.5.6.Replacing Older Functions with thesubprocess Module¶

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

In the following examples, we assume that the relevant functions have alreadybeen imported from thesubprocess module.

output=`mycmdmyarg`

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

output=`dmesg|grephda`

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|grephda`

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

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

try:retcode=call("mycmd"+" myarg",shell=True)ifretcode<0:print("Child was terminated by signal",-retcode,file=sys.stderr)else:print("Child returned",retcode,file=sys.stderr)exceptOSErrorase: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()ifrcisnotNoneandrc>>8:print("There were some errors")==>process=Popen(cmd,stdin=PIPE)...process.stdin.close()ifprocess.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)

17.5.7.Legacy Shell Invocation Functions¶

This module also provides the following legacy functions from the 2.xcommands module. These operations implicitly invoke the system shell andnone of the guarantees described above regarding security and exceptionhandling consistency are valid for these functions.

subprocess.getstatusoutput(cmd)¶

Return(exitcode,output) of executingcmd in a shell.

Execute the stringcmd in a shell withPopen.check_output() andreturn a 2-tuple(exitcode,output). The locale encoding is used;see the notes onFrequently Used Arguments for more details.

A trailing newline is stripped from the output.The exit code for the command can be interpreted as the return codeof 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, '')

Availability: POSIX & Windows

Changed in version 3.3.4:Windows support was added.

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 asreturncode.

subprocess.getoutput(cmd)¶

Return output (stdout and stderr) of executingcmd in a shell.

Likegetstatusoutput(), except the exit code is ignored and the returnvalue is a string containing the command’s output. Example:

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

Availability: POSIX & Windows

Changed in version 3.3.4:Windows support added

17.5.8.Notes¶