subprocess — Subprocess management

Source code:Lib/subprocess.py

Thesubprocess module allows you to spawn new processes, connect to theirinput/output/error pipes, and obtain their return codes. This module intends toreplace several older modules and functions:

os.systemos.spawn*

Information about how thesubprocess module can be used to replace thesemodules and functions can be found in the following sections.

See also

PEP 324 – PEP proposing the subprocess module

Availability: not Android, not iOS, not WASI.

This module is not supported onmobile platformsorWebAssembly platforms.

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.

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)

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 - most of the arguments tothis function are passed through to that interface. (timeout,input,check, andcapture_output are not.)

Ifcapture_output is true, stdout and stderr will be captured.When used, the internalPopen object is automatically created withstdout andstderr both set toPIPE.Thestdout andstderr arguments may not be supplied at the same time ascapture_output.If you wish to capture and combine both streams into one,setstdout toPIPEandstderr toSTDOUT,instead of usingcapture_output.

Atimeout may be specified in seconds, it is internally passed on toPopen.communicate(). If the timeout expires, the child process will bekilled and waited for. TheTimeoutExpired exception will bere-raised after the child process has terminated. The initial processcreation itself cannot be interrupted on many platform APIs so you are notguaranteed to see a timeout exception until at least after however longprocess creation takes.

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 ortext is true. Whenused, the internalPopen object is automatically created withstdin set toPIPE,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, ortext is true,file objects for stdin, stdout and stderr are opened in text mode using thespecifiedencoding anderrors or theio.TextIOWrapper default.Theuniversal_newlines argument is equivalent totext and is providedfor backwards compatibility. By default, 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 passeddirectly toPopen. This mapping can be str to str on any platformor bytes to bytes on POSIX platforms much likeos.environ oros.environb.

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"],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.

Changed in version 3.6:Addedencoding anderrors parameters

Changed in version 3.7:Added thetext parameter, as a more understandable alias ofuniversal_newlines.Added thecapture_output parameter.

Changed in version 3.12:Changed Windows shell search order forshell=True. The currentdirectory and%PATH% are replaced with%COMSPEC% and%SystemRoot%\System32\cmd.exe. As a result, dropping amalicious program namedcmd.exe into a current directory nolonger works.

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, errors, or text=True.None if stdout was not captured.

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, errors, or text=True.None if stderr was not captured.

check_returncode()

Ifreturncode is non-zero, raise aCalledProcessError.

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

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

Added 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. This is alwaysbytes when any output was captured regardless of thetext=True setting. It may remainNone instead ofb''when no output was observed.

stdout

Alias for output, for symmetry withstderr.

stderr

Stderr output of the child process if it was captured byrun().Otherwise,None. This is alwaysbytes when stderr outputwas captured regardless of thetext=True setting. It may remainNone instead ofb'' when no stderr output was observed.

Added in version 3.3.

Changed in version 3.5:stdout andstderr attributes added

exceptionsubprocess.CalledProcessError

Subclass ofSubprocessError, raised when a process run bycheck_call(),check_output(), orrun() (withcheck=True)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

Frequently Used Arguments

To support a wide variety of use cases, thePopen constructor (andthe convenience functions) accept a large number of optional arguments. Formost typical use cases, many of these arguments can be safely left at theirdefault values. The arguments that are most commonly needed are:

args is required for all calls and should be a string, or a sequence ofprogram arguments. Providing a sequence of arguments is generallypreferred, as it allows the module to take care of any required escapingand quoting of arguments (e.g. to permit spaces in file names). If passinga single string, eithershell must beTrue (see below) or elsethe string must simply name the program to be executed without specifyingany arguments.

stdin,stdout andstderr specify the executed program’s standard input,standard output and standard error file handles, respectively. Valid valuesareNone,PIPE,DEVNULL, an existing file descriptor (apositive integer), and an existingfile object with a valid filedescriptor. With the default settings ofNone, no redirection willoccur.PIPE indicates that a new pipe to the child should becreated.DEVNULL indicates that the special fileos.devnullwill be used. Additionally,stderr can beSTDOUT, which indicatesthat the stderr data from the child process should be captured into the samefile handle as forstdout.

Ifencoding orerrors are specified, ortext (also known asuniversal_newlines) is true,the file objectsstdin,stdout andstderr will be opened in textmode using theencoding anderrors specified in the call or thedefaults forio.TextIOWrapper.

Forstdin, line ending characters'\n' in the input will be convertedto the default line separatoros.linesep. Forstdout andstderr,all line endings in the output will be converted to'\n'. For moreinformation see the documentation of theio.TextIOWrapper classwhen thenewline argument to its constructor isNone.

If text mode is not used,stdin,stdout andstderr will be opened asbinary streams. No encoding or line ending conversion is performed.

Changed in version 3.6:Added theencoding anderrors parameters.

Changed in version 3.7:Added thetext parameter as an alias foruniversal_newlines.

Note

The newlines attribute of the file objectsPopen.stdin,Popen.stdout andPopen.stderr are not updated bythePopen.communicate() method.

Ifshell isTrue, the specified command will be executed throughthe shell. This can be useful if you are using Python primarily for theenhanced control flow it offers over most system shells and still wantconvenient access to other shell features such as shell pipes, filenamewildcards, environment variable expansion, and expansion of~ to auser’s home directory. However, note that Python itself offersimplementations of many shell-like features (in particular,glob,fnmatch,os.walk(),os.path.expandvars(),os.path.expanduser(), andshutil).

Changed in version 3.3:Whenuniversal_newlines isTrue, the class uses the encodinglocale.getpreferredencoding(False)instead oflocale.getpreferredencoding(). See theio.TextIOWrapper class for more information on this change.

Note

Read theSecurity Considerations section before usingshell=True.

These options, along with all of the other options, are described in moredetail in thePopen constructor documentation.

Popen Constructor

The underlying process creation and management in this module is handled bythePopen class. It offers a lot of flexibility so that developersare able to handle the less common cases not covered by the conveniencefunctions.

classsubprocess.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)

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

args should be a sequence of program arguments or else a single stringorpath-like object.By default, the program to execute is the first item inargs ifargs isa sequence. Ifargs is a string, the interpretation isplatform-dependent and described below. See theshell andexecutablearguments for additional differences from the default behavior. Unlessotherwise stated, it is recommended to passargs as a sequence.

Warning

For maximum reliability, use a fully qualified path for the executable.To search for an unqualified name onPATH, useshutil.which(). On all platforms, passingsys.executableis 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 ofexecutable (or the first item ofargs) isplatform dependent. For POSIX, seeos.execvpe(), and note thatwhen resolving or searching for the executable path,cwd overrides thecurrent working directory andenv can override thePATHenvironment variable. For Windows, see the documentation of thelpApplicationName andlpCommandLine parameters of WinAPICreateProcess, and note that when resolving or searching for theexecutable path withshell=False,cwd does not override thecurrent working directory andenv cannot override thePATHenvironment variable. Using a full path avoids all of these variations.

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

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

On POSIX, ifargs is a string, the string is interpreted as the name orpath of the program to execute. However, this can only be done if notpassing arguments to the program.

Note

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 todetermine the correct tokenization forargs:

>>>importshlex,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 (suchaseggs.txt) that are separated by whitespace in the shell go in separatelist elements, while arguments that need quoting or backslash escaping whenused in the shell (such as filenames containing spaces or theecho commandshown above) are single list elements.

On Windows, ifargs is a sequence, it will be converted to a string in amanner described inConverting an argument sequence to a string on Windows. This is becausethe underlyingCreateProcess() operates on strings.

Changed in version 3.6:args parameter accepts apath-like object ifshell isFalse and a sequence containing path-like objects on POSIX.

Changed in version 3.8:args parameter accepts apath-like object ifshell isFalse and a sequence containing bytes and path-like objectson Windows.

Theshell argument (which defaults toFalse) specifies whether to usethe shell as the program to execute. Ifshell isTrue, it isrecommended to passargs as a string rather than as a sequence.

On POSIX withshell=True, the shell defaults to/bin/sh. Ifargs is a string, the string specifies the commandto execute through the shell. This means that the string must beformatted exactly as it would be when typed at the shell prompt. Thisincludes, for example, quoting or backslash escaping filenames with spaces inthem. Ifargs is a sequence, the first item specifies the command string, andany additional items will be treated as additional arguments to the shellitself. That is to say,Popen does the equivalent of:

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

On Windows withshell=True, theCOMSPEC environment variablespecifies the default shell. The only time you need to specifyshell=True on Windows is when the command you wish to execute is builtinto the shell (e.g.dir orcopy). You do not needshell=True to run a batch file or console-based executable.

Note

Read theSecurity Considerations section before usingshell=True.

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

  • 0 means unbuffered (read and write are onesystem call and can return short)

  • 1 means line buffered(only usable iftext=True oruniversal_newlines=True)

  • any other positive value means use a buffer of approximately thatsize

  • negative bufsize (the default) means the system default ofio.DEFAULT_BUFFER_SIZE will be used.

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

Theexecutable argument specifies a replacement program to execute. Itis very seldom needed. Whenshell=False,executable replaces theprogram to execute specified byargs. However, the originalargs isstill passed to the program. Most programs treat the program specifiedbyargs as the command name, which can then be different from the programactually executed. On POSIX, theargs namebecomes the display name for the executable in utilities such asps. Ifshell=True, on POSIX theexecutable argumentspecifies a replacement shell for the default/bin/sh.

Changed in version 3.6:executable parameter accepts apath-like object on POSIX.

Changed in version 3.8:executable parameter accepts a bytes andpath-like objecton Windows.

Changed in version 3.12:Changed Windows shell search order forshell=True. The currentdirectory and%PATH% are replaced with%COMSPEC% and%SystemRoot%\System32\cmd.exe. As a result, dropping amalicious program namedcmd.exe into a current directory nolonger works.

stdin,stdout andstderr specify the executed program’s standard input,standard output and standard error file handles, respectively. Valid valuesareNone,PIPE,DEVNULL, an existing file descriptor (apositive integer), and an existingfile object with a valid filedescriptor. With the default settings ofNone, no redirection willoccur.PIPE indicates that a new pipe to the child should becreated.DEVNULL indicates that the special fileos.devnullwill be used. Additionally,stderr can beSTDOUT, which indicatesthat the stderr data from the applications should be captured into the samefile handle as forstdout.

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

Warning

Thepreexec_fn parameter is NOT SAFE to use in the presence of threadsin your application. The child process could deadlock before exec iscalled.

Note

If you need to modify the environment for the child use theenvparameter rather than doing it in apreexec_fn.Thestart_new_session andprocess_group parameters should take the place ofcode usingpreexec_fn to callos.setsid() oros.setpgid() in the child.

Changed in version 3.8:Thepreexec_fn parameter is no longer supported in subinterpreters.The use of the parameter in a subinterpreter raisesRuntimeError. The new restriction may affect applications thatare deployed in mod_wsgi, uWSGI, and other embedded environments.

Ifclose_fds is true, all file descriptors except0,1 and2 will be closed before the child process is executed. Otherwisewhenclose_fds is false, file descriptors obey their inheritable flagas described inInheritance of File Descriptors.

On Windows, ifclose_fds is true then no handles will be inherited by thechild process unless explicitly passed in thehandle_list element ofSTARTUPINFO.lpAttributeList, or by standard handle redirection.

Changed in version 3.2:The default forclose_fds was changed fromFalse towhat is described above.

Changed in version 3.7:On Windows the default forclose_fds was changed fromFalse toTrue when redirecting the standard handles. It’s now possible tosetclose_fds toTrue when redirecting the standard handles.

pass_fds is an optional sequence of file descriptors to keep openbetween the parent and child. Providing anypass_fds forcesclose_fds to beTrue. (POSIX only)

Changed in version 3.2:Thepass_fds parameter was added.

Ifcwd is notNone, the function changes the working directory tocwd before executing the child.cwd can be a string, bytes orpath-like object. On POSIX, the functionlooks forexecutable (or for the first item inargs) relative tocwdif the executable path is a relative path.

Changed in version 3.6:cwd parameter accepts apath-like object on POSIX.

Changed in version 3.7:cwd parameter accepts apath-like object on Windows.

Changed in version 3.8:cwd parameter accepts a bytes object on Windows.

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

Changed in version 3.2:restore_signals was added.

Ifstart_new_session is true thesetsid() system call will be made in thechild process prior to the execution of the subprocess.

Changed in version 3.2:start_new_session was added.

Ifprocess_group is a non-negative integer, thesetpgid(0,value) system call willbe made in the child process prior to the execution of the subprocess.

Changed in version 3.11:process_group was added.

Ifgroup is notNone, the setregid() system call will be made in thechild process prior to the execution of the subprocess. If the providedvalue is a string, it will be looked up viagrp.getgrnam() andthe value ingr_gid will be used. If the value is an integer, itwill be passed verbatim. (POSIX only)

Added in version 3.9.

Ifextra_groups is notNone, the setgroups() system call will bemade in the child process prior to the execution of the subprocess.Strings provided inextra_groups will be looked up viagrp.getgrnam() and the values ingr_gid will be used.Integer values will be passed verbatim. (POSIX only)

Added in version 3.9.

Ifuser is notNone, the setreuid() system call will be made in thechild process prior to the execution of the subprocess. If the providedvalue is a string, it will be looked up viapwd.getpwnam() andthe value inpw_uid will be used. If the value is an integer, it willbe passed verbatim. (POSIX only)

Added in version 3.9.

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

Added in version 3.9.

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. This mapping can bestr to str on any platform or bytes to bytes on POSIX platforms much likeos.environ oros.environb.

Note

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

Ifencoding orerrors are specified, ortext is true, the file objectsstdin,stdout andstderr are opened in text mode with the specifiedencoding anderrors, as described above inFrequently Used Arguments.Theuniversal_newlines argument is equivalent totext and is providedfor backwards compatibility. By default, file objects are opened in binary mode.

Added in version 3.6:encoding anderrors were added.

Added in version 3.7:text was added as a more readable alias foruniversal_newlines.

If given,startupinfo will be aSTARTUPINFO object, which ispassed to the underlyingCreateProcess function.

If given,creationflags, can be one or more of the following flags:

pipesize can be used to change the size of the pipe whenPIPE is used forstdin,stdout orstderr. The size of the pipeis only changed on platforms that support this (only Linux at this time ofwriting). Other platforms will ignore this parameter.

Changed in version 3.10:Added thepipesize parameter.

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

withPopen(["ifconfig"],stdout=PIPE)asproc:log.write(proc.stdout.read())

Popen and the other functions in this module that use it raise anauditing eventsubprocess.Popen with argumentsexecutable,args,cwd, andenv. The value forargsmay be a single string or a list of strings, depending on platform.

Changed in version 3.2:Added context manager support.

Changed in version 3.6:Popen destructor now emits aResourceWarning warning if the childprocess is still running.

Changed in version 3.8:Popen can useos.posix_spawn() in some cases for betterperformance. On Windows Subsystem for Linux and QEMU User Emulation,Popen constructor usingos.posix_spawn() no longer raise anexception on errors like missing program, but the child process failswith a non-zeroreturncode.

Exceptions

Exceptions raised in the child process, before the new program has started toexecute, will be re-raised in the parent.

The most common exception raised isOSError. This occurs, for example,when trying to execute a non-existent file. Applications should prepare forOSError exceptions. Note that, whenshell=True,OSErrorwill 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 isnecessary to check the return code or output from the subprocess.

AValueError will be raised ifPopen is called with invalidarguments.

check_call() andcheck_output() will raiseCalledProcessError if the called process returns a non-zero returncode.

All of the functions and methods that accept atimeout parameter, such asrun() andPopen.communicate() will raiseTimeoutExpired ifthe timeout expires before the process exits.

Exceptions defined in this module all inherit fromSubprocessError.

Added in version 3.3:TheSubprocessError base class was added.

Security Considerations

Unlike some other popen functions, this library will notimplicitly 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, viashell=True, it is the application’sresponsibility to ensure that all whitespace and metacharacters arequoted appropriately to avoidshell injectionvulnerabilities. Onsome platforms, it is possibleto useshlex.quote() for this escaping.

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

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

When thetimeout parameter is notNone, then (on POSIX) thefunction is implemented using a busy loop (non-blocking call and shortsleeps). Use theasyncio module for an asynchronous wait: seeasyncio.create_subprocess_exec.

Changed in version 3.3:timeout was added.

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 and set thereturncode attribute. The optionalinput argument should bedata to be sent to the child process, orNone, if no data should be sentto the child. If streams were opened in text 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.

Do nothing if the process completed.

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 sendsSIGTERM 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 set by the class for you to access.Reassigning them to new values is unsupported:

Popen.args

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

Added 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 thetext oruniversal_newlines argumentwasTrue, the stream is a text stream, otherwise it is a byte stream.If thestdin argument 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 thetext oruniversal_newlines argument wasTrue, thestream is a text stream, otherwise it is a byte stream. If thestdoutargument 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 thetext oruniversal_newlines argument wasTrue, thestream is a text stream, otherwise it is a byte stream. If thestderr argumentwas notPIPE, this attribute isNone.

Warning

Usecommunicate() rather than.stdin.write,.stdout.read or.stderr.read to avoiddeadlocks due to any of the other OS pipe buffers filling up and blocking thechild process.

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. InitiallyNone,returncode is set bya call to thepoll(),wait(), orcommunicate() methodsif they detect that the process has terminated.

ANone value indicates that the process hadn’t yet terminated at thetime of the last method call.

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

Windows Popen Helpers

TheSTARTUPINFO class and following constants are only availableon Windows.

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

Partial support of the WindowsSTARTUPINFOstructure is used forPopen creation. The following attributes canbe set by passing them as keyword-only arguments.

Changed in version 3.7:Keyword-only argument support was added.

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.

lpAttributeList

A dictionary of additional attributes for process creation as given inSTARTUPINFOEX, seeUpdateProcThreadAttribute.

Supported attributes:

handle_list

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

The handles must be temporarily made inheritable byos.set_handle_inheritable() when passed to thePopenconstructor, elseOSError will be raised with Windows errorERROR_INVALID_PARAMETER (87).

Warning

In a multithreaded process, use caution to avoid leaking handlesthat are marked inheritable when combining this feature withconcurrent calls to other process creation functions that inheritall handles such asos.system(). This also applies tostandard handle redirection, which temporarily creates inheritablehandles.

Added in version 3.7.

Windows Constants

Thesubprocess module exposes the following constants.

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 screenbuffer,CONOUT$.

subprocess.STD_ERROR_HANDLE

The standard error device. Initially, this is the active console screenbuffer,CONOUT$.

subprocess.SW_HIDE

Hides the window. Another window will be activated.

subprocess.STARTF_USESTDHANDLES

Specifies that theSTARTUPINFO.hStdInput,STARTUPINFO.hStdOutput, andSTARTUPINFO.hStdError attributescontain additional information.

subprocess.STARTF_USESHOWWINDOW

Specifies that theSTARTUPINFO.wShowWindow attribute containsadditional information.

subprocess.STARTF_FORCEONFEEDBACK

ASTARTUPINFO.dwFlags parameter to specify that theWorking in Background mouse cursor will be displayed while aprocess is launching. This is the default behavior for GUIprocesses.

Added in version 3.13.

subprocess.STARTF_FORCEOFFFEEDBACK

ASTARTUPINFO.dwFlags parameter to specify that the mousecursor will not be changed when launching a process.

Added in version 3.13.

subprocess.CREATE_NEW_CONSOLE

The new process has a new console, instead of inheriting its parent’sconsole (the default).

subprocess.CREATE_NEW_PROCESS_GROUP

APopencreationflags parameter to specify that a new processgroup will be created. This flag is necessary for usingos.kill()on the subprocess.

This flag is ignored ifCREATE_NEW_CONSOLE is specified.

subprocess.ABOVE_NORMAL_PRIORITY_CLASS

APopencreationflags parameter to specify that a new processwill have an above average priority.

Added in version 3.7.

subprocess.BELOW_NORMAL_PRIORITY_CLASS

APopencreationflags parameter to specify that a new processwill have a below average priority.

Added in version 3.7.

subprocess.HIGH_PRIORITY_CLASS

APopencreationflags parameter to specify that a new processwill have a high priority.

Added in version 3.7.

subprocess.IDLE_PRIORITY_CLASS

APopencreationflags parameter to specify that a new processwill have an idle (lowest) priority.

Added in version 3.7.

subprocess.NORMAL_PRIORITY_CLASS

APopencreationflags parameter to specify that a new processwill have a normal priority. (default)

Added in version 3.7.

subprocess.REALTIME_PRIORITY_CLASS

APopencreationflags parameter to specify that a new processwill have realtime priority.You should almost never use REALTIME_PRIORITY_CLASS, because this interruptssystem threads that manage mouse input, keyboard input, and background diskflushing. This class can be appropriate for applications that “talk” directlyto hardware or that perform brief tasks that should have limited interruptions.

Added in version 3.7.

subprocess.CREATE_NO_WINDOW

APopencreationflags parameter to specify that a new processwill not create a window.

Added in version 3.7.

subprocess.DETACHED_PROCESS

APopencreationflags parameter to specify that a new processwill 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

APopencreationflags parameter to specify that a new processdoes not inherit the error mode of the calling process. Instead, the newprocess gets the default error mode.This feature is particularly useful for multithreaded shell applicationsthat run with hard errors disabled.

Added in version 3.7.

subprocess.CREATE_BREAKAWAY_FROM_JOB

APopencreationflags parameter to specify that a new processis not associated with the job.

Added in version 3.7.

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,**other_popen_kwargs)

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

Code needing to capture stdout or stderr should userun() instead:

run(...).returncode

To suppress stdout or stderr, supply a value ofDEVNULL.

The arguments shown above are merely some common ones.The full function signature is 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.

Changed in version 3.12:Changed Windows shell search order forshell=True. The currentdirectory and%PATH% are replaced with%COMSPEC% and%SystemRoot%\System32\cmd.exe. As a result, dropping amalicious program namedcmd.exe into a current directory nolonger works.

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 returncode was zero then return, otherwise raiseCalledProcessError. TheCalledProcessError object will have the return code in thereturncode attribute.Ifcheck_call() was unable to start the process it will propagate the exceptionthat was raised.

Code needing to capture stdout or stderr should userun() instead:

run(...,check=True)

To suppress stdout or stderr, supply a value ofDEVNULL.

The arguments shown above are merely some common ones.The full function signature is 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.

Changed in version 3.12:Changed Windows shell search order forshell=True. The currentdirectory and%PATH% are replaced with%COMSPEC% and%SystemRoot%\System32\cmd.exe. As a result, dropping amalicious program namedcmd.exe into a current directory nolonger works.

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 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 some common ones.The full function signature is largely the same as that ofrun() -most arguments are passed directly through to that interface.One API deviation fromrun() behavior exists: passinginput=Nonewill behave the same asinput=b'' (orinput='', depending on otherarguments) rather than using the parent’s standard input file handle.

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 settingtext,encoding,errors,oruniversal_newlines toTrue as described inFrequently Used Arguments andrun().

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'

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

Added in version 3.7:text was added as a more readable alias foruniversal_newlines.

Changed in version 3.12:Changed Windows shell search order forshell=True. The currentdirectory and%PATH% are replaced with%COMSPEC% and%SystemRoot%\System32\cmd.exe. As a result, dropping amalicious program namedcmd.exe into a current directory nolonger works.

Replacing Older Functions with thesubprocess Module

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

Note

All “a” functions in this section fail (more or less) silently if theexecuted program cannot be found; the “b” replacements raiseOSErrorinstead.

In addition, the replacements usingcheck_output() will fail with aCalledProcessError if the requested operation produces a non-zeroreturn code. The output is still available as theoutput attribute of the raised exception.

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

Replacing/bin/sh shell command substitution

output=$(mycmdmyarg)

becomes:

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

Replacing shell pipeline

output=$(dmesg|grephda)

becomes:

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]

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

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

output=$(dmesg|grephda)

becomes:

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

Replacingos.system()

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

Notes:

  • Calling the program through the shell is usually not required.

  • Thecall() return value is encoded differently to that ofos.system().

  • Theos.system() function ignores SIGINT and SIGQUIT signals whilethe command is running, but the caller must do this separately whenusing thesubprocess module.

A more realistic example would look like this:

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)

Replacing theos.spawn family

P_NOWAIT example:

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

P_WAIT example:

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

Vector example:

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

Environment example:

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

Replacingos.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)

Return code handling translates as follows:

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

Replacing functions from thepopen2 module

Note

If the cmd argument to popen2 functions is a string, the command is executedthrough /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 andpopen2.Popen4 basically work assubprocess.Popen, except that:

  • Popen raises an exception if the execution fails.

  • Thecapturestderr argument is replaced with thestderr argument.

  • stdin=PIPE andstdout=PIPE must be specified.

  • popen2 closes all file descriptors by default, but you have to specifyclose_fds=True withPopen to guarantee this behavior onall platforms or past Python versions.

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,*,encoding=None,errors=None)

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

Execute the stringcmd in a shell withPopen.check_output() andreturn a 2-tuple(exitcode,output).encoding anderrors are used to decode output;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: Unix, 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.

Changed in version 3.11:Added theencoding anderrors parameters.

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

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: Unix, Windows.

Changed in version 3.3.4:Windows support added

Changed in version 3.11:Added theencoding anderrors parameters.

Notes

Timeout Behavior

When using thetimeout parameter in functions likerun(),Popen.wait(), orPopen.communicate(),users should be aware of the following behaviors:

  1. Process Creation Delay: The initial process creation itself cannot be interruptedon many platform APIs. This means that even when specifying a timeout, you are notguaranteed to see a timeout exception until at least after however long processcreation takes.

  2. Extremely Small Timeout Values: Setting very small timeout values (such as a fewmilliseconds) may result in almost immediateTimeoutExpired exceptions becauseprocess creation and system scheduling inherently require time.

Converting an argument sequence to a string on Windows

On Windows, anargs sequence is converted to a string that can be parsedusing the following rules (which correspond to the rules used by the MS Cruntime):

  1. Arguments are delimited by white space, which is either aspace or a tab.

  2. A string surrounded by double quotation marks isinterpreted as a single argument, regardless of white spacecontained within. A quoted string can be embedded in anargument.

  3. A double quotation mark preceded by a backslash isinterpreted as a literal double quotation mark.

  4. Backslashes are interpreted literally, unless theyimmediately precede a double quotation mark.

  5. If backslashes immediately precede a double quotation mark,every pair of backslashes is interpreted as a literalbackslash. If the number of backslashes is odd, the lastbackslash escapes the next double quotation mark asdescribed in rule 3.

See also

shlex

Module which provides function to parse and escape command lines.

Disabling use ofvfork() orposix_spawn()

On Linux,subprocess defaults to using thevfork() system callinternally when it is safe to do so rather thanfork(). This greatlyimproves performance.

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

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

Setting this has no impact on use ofposix_spawn() which could usevfork() internally within its libc implementation. There is a similarsubprocess._USE_POSIX_SPAWN attribute if you need to prevent use ofthat.

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 noeffect on older versions when unsupported. Do not assume the attributes areavailable to read. Despite their names, a true value does not indicate that thecorresponding function will be used, only that it may be.

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

Added in version 3.8:_USE_POSIX_SPAWN

Added in version 3.11:_USE_VFORK