:mod:`!subprocess` --- Subprocess management

.. module:: subprocess

:synopsis: Subprocess management.

**Source code:** :source:`Lib/subprocess.py`

modules and functions can be found in the following sections.

.. seealso::

:pep:`324` -- PEP proposing the subprocess module

Using the :mod:`!subprocess` Module

function for all use cases it can handle. For more advanced use cases, the

underlying :class:`Popen` interface can be used directly.

.. function:: run(args, *, stdin=None, input=None, stdout=None, stderr=None,\

Run the command described by *args*. Wait for command to complete, then

The arguments shown above are merely the most common ones, described below

in :ref:`frequently-used-arguments` (hence the use of keyword-only notation

in the abbreviated signature). The full function signature is largely the

same as that of the :class:`Popen` constructor - most of the arguments to

this function are passed through to that interface. (*timeout*, *input*,

*check*, and *capture_output* are not.)

If *capture_output* is true, stdout and stderr will be captured.

When used, the internal :class:`Popen` object is automatically created with

The *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 :data:`~subprocess.PIPE`

and *stderr* to :data:`~subprocess.STDOUT`,

instead of using *capture_output*.

A *timeout* may be specified in seconds, it is internally passed on to

:meth:`Popen.communicate`. If the timeout expires, the child process will be

killed and waited for. The :exc:`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* argument is passed to :meth:`Popen.communicate` and thus to the

subprocess's stdin. If used it must be a byte sequence, or a string if

*stdin* set to :data:`~subprocess.PIPE`,

and the *stdin* argument may not be used as well.

:exc:`CalledProcessError` exception will be raised. Attributes of that

exception hold the arguments, the exit code, and stdout and stderr if they

were captured.

file objects for stdin, stdout and stderr are opened in text mode using the

specified *encoding* and *errors* or the :class:`io.TextIOWrapper` default.

The *universal_newlines* argument is equivalent to *text* and is provided

for backwards compatibility. By default, file objects are opened in binary mode.

If *env* is not ``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. It is passed

directly to :class:`Popen`. This mapping can be str to str on any platform

or bytes to bytes on POSIX platforms much like :data:`os.environ` or

:data:`os.environb`.

Examples::

.. versionchanged:: 3.6

Added *encoding* and *errors* parameters

.. versionchanged:: 3.7

Added the *text* parameter, as a more understandable alias of *universal_newlines*.

Added the *capture_output* parameter.

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.

Exit status of the child process. Typically, an exit status of 0 indicates

that it ran successfully.

A negative value ``-N`` indicates that the child was terminated by signal

``N`` (POSIX only).

:func:`run` was called with an encoding, errors, or text=True.

``None`` if stdout was not captured.

If you ran the process with ``stderr=subprocess.STDOUT``, stdout and

stderr will be combined in this attribute, and :attr:`stderr` will be

:func:`run` was called with an encoding, errors, or text=True.

``None`` if stderr was not captured.

.. data:: DEVNULL

Special value that can be used as the *stdin*, *stdout* or *stderr* argument

to :class:`Popen` and indicates that the special file :data:`os.devnull`

will be used.

.. versionadded:: 3.3

.. data:: PIPE

Special value that can be used as the *stdin*, *stdout* or *stderr* argument

to :class:`Popen` and indicates that a pipe to the standard stream should be

.. data:: STDOUT

Special value that can be used as the *stderr* argument to :class:`Popen` and

indicates that standard error should go into the same handle as standard

output.

.. exception:: SubprocessError

Base class for all other exceptions from this module.

.. versionadded:: 3.3

.. exception:: TimeoutExpired

Subclass of :exc:`SubprocessError`, raised when a timeout expires

while waiting for a child process.

.. attribute:: cmd

Command that was used to spawn the child process.

.. attribute:: timeout

Timeout in seconds.

.. attribute:: output

:func:`check_output`. Otherwise, ``None``. This is always

:class:`bytes` when any output was captured regardless of the

``text=True`` setting. It may remain ``None`` instead of ``b''``

when no output was observed.

.. attribute:: stdout

Alias for output, for symmetry with :attr:`stderr`.

.. attribute:: stderr

Stderr output of the child process if it was captured by :func:`run`.

Otherwise, ``None``. This is always :class:`bytes` when stderr output

was captured regardless of the ``text=True`` setting. It may remain

``None`` instead of ``b''`` when no stderr output was observed.

.. versionadded:: 3.3

.. versionchanged:: 3.5

*stdout* and *stderr* attributes added

.. exception:: CalledProcessError

Subclass of :exc:`SubprocessError`, raised when a process run by

:func:`check_call`, :func:`check_output`, or :func:`run` (with ``check=True``)

returns a non-zero exit status.

.. attribute:: returncode

Exit status of the child process, an integer. If the process

exited due to a signal, this will be the negative signal number.

.. attribute:: cmd

Command that was used to spawn the child process.

.. attribute:: output

:func:`check_output`. Otherwise, ``None``.

.. attribute:: stdout

Alias for output, for symmetry with :attr:`stderr`.

.. attribute:: stderr

Stderr output of the child process if it was captured by :func:`run`.

Otherwise, ``None``.

.. versionchanged:: 3.5

*stdout* and *stderr* attributes added

.. _frequently-used-arguments:

Frequently Used Arguments

To support a wide variety of use cases, the :class:`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* must be :const:`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``, :data:`PIPE`, :data:`DEVNULL`, an existing file descriptor (a

positive integer), and an existing :term:`file object` with a valid file

descriptor. With the default settings of ``None``, no redirection will

occur. :data:`PIPE` indicates that a new pipe to the child should be

created. :data:`DEVNULL` indicates that the special file :data:`os.devnull`

will be used. Additionally, *stderr* can be :data:`STDOUT`, which indicates

that the stderr data from the child process should be captured into the same

file handle as for *stdout*.

.. index::

single: universal newlines; subprocess module

If *encoding* or *errors* are specified, or *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 :class:`io.TextIOWrapper`.

For *stdin*, line ending characters ``'\n'`` in the input will be converted

to the default line separator :data:`os.linesep`. For *stdout* and *stderr*,

all line endings in the output will be converted to ``'\n'``. For more

information see the documentation of the :class:`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.

.. versionchanged:: 3.6

Added the *encoding* and *errors* parameters.

Added the *text* parameter as an alias for *universal_newlines*.

.. note::

The newlines attribute of the file objects :attr:`Popen.stdin`,

:attr:`Popen.stdout` and :attr:`Popen.stderr` are not updated by

the :meth:`Popen.communicate` method.

If *shell* is ``True``, the specified command will be executed through

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, :mod:`glob`,

:mod:`fnmatch`, :func:`os.walk`, :func:`os.path.expandvars`,

:func:`os.path.expanduser`, and :mod:`shutil`).

.. versionchanged:: 3.3

When *universal_newlines* is ``True``, the class uses the encoding

:func:`locale.getpreferredencoding(False) <locale.getpreferredencoding>`

instead of ``locale.getpreferredencoding()``. See the

:class:`io.TextIOWrapper` class for more information on this change.

These options, along with all of the other options, are described in more

detail in the :class:`Popen` constructor documentation.

The underlying process creation and management in this module is handled by

the :class:`Popen` class. It offers a lot of flexibility so that developers

are able to handle the less common cases not covered by the convenience

functions.

the class uses the Windows ``CreateProcess()`` function. The arguments to

:class:`Popen` are as follows.

*args* should be a sequence of program arguments or else a single string

or :term:`path-like object`.

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.

.. warning::

To search for an unqualified name on :envvar:`PATH`, use

:meth:`shutil.which`. On all platforms, passing :data:`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 :meth:`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::

path of the program to execute. However, this can only be done if not

passing 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. :meth:`shlex.split` can illustrate how to

determine the correct tokenization for *args*::

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 :ref:`converting-argument-sequence`. This is because

the underlying ``CreateProcess()`` operates on strings.

.. versionchanged:: 3.6

*args* parameter accepts a :term:`path-like object` if *shell* is

``False`` and a sequence containing path-like objects on POSIX.

.. versionchanged:: 3.8

*args* parameter accepts a :term:`path-like object` if *shell* is

``False`` and a sequence containing bytes and path-like objects

on Windows.

The *shell* argument (which defaults to ``False``) specifies whether to use

the shell as the program to execute. If *shell* is ``True``, it is

*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