Debian Codegraph @

Doc/library/subprocess.rst

raw
1 :mod:`!subprocess` --- Subprocess management
2 ============================================
3
4 .. module:: subprocess
5 :synopsis: Subprocess management.
6
7 .. moduleauthor:: Peter Åstrand <[email protected]>
8 .. sectionauthor:: Peter Åstrand <[email protected]>
9
10 **Source code:** :source:`Lib/subprocess.py`
11
12 --------------
13
14 The :mod:`!subprocess` module allows you to spawn new processes, connect to their
15 input/output/error pipes, and obtain their return codes. This module intends to
16 replace several older modules and functions::
17
18 os.system
19 os.spawn*
20
21 Information about how the :mod:`!subprocess` module can be used to replace these
22 modules and functions can be found in the following sections.
23
24 .. seealso::
25
26 :pep:`324` -- PEP proposing the subprocess module
27
28 .. include:: ../includes/wasm-mobile-notavail.rst
29
30 Using the :mod:`!subprocess` Module
31 -----------------------------------
32
33 The recommended approach to invoking subprocesses is to use the :func:`run`
34 function for all use cases it can handle. For more advanced use cases, the
35 underlying :class:`Popen` interface can be used directly.
36
37
38 .. function:: run(args, *, stdin=None, input=None, stdout=None, stderr=None,\
39 capture_output=False, shell=False, cwd=None, timeout=None, \
40 check=False, encoding=None, errors=None, text=None, env=None, \
41 universal_newlines=None, **other_popen_kwargs)
42
43 Run the command described by *args*. Wait for command to complete, then
44 return a :class:`CompletedProcess` instance.
45
46 The arguments shown above are merely the most common ones, described below
47 in :ref:`frequently-used-arguments` (hence the use of keyword-only notation
48 in the abbreviated signature). The full function signature is largely the
49 same as that of the :class:`Popen` constructor - most of the arguments to
50 this function are passed through to that interface. (*timeout*, *input*,
51 *check*, and *capture_output* are not.)
52
53 If *capture_output* is true, stdout and stderr will be captured.
54 When used, the internal :class:`Popen` object is automatically created with
55 *stdout* and *stderr* both set to :data:`~subprocess.PIPE`.
56 The *stdout* and *stderr* arguments may not be supplied at the same time as *capture_output*.
57 If you wish to capture and combine both streams into one,
58 set *stdout* to :data:`~subprocess.PIPE`
59 and *stderr* to :data:`~subprocess.STDOUT`,
60 instead of using *capture_output*.
61
62 A *timeout* may be specified in seconds, it is internally passed on to
63 :meth:`Popen.communicate`. If the timeout expires, the child process will be
64 killed and waited for. The :exc:`TimeoutExpired` exception will be
65 re-raised after the child process has terminated. The initial process
66 creation itself cannot be interrupted on many platform APIs so you are not
67 guaranteed to see a timeout exception until at least after however long
68 process creation takes.
69
70 The *input* argument is passed to :meth:`Popen.communicate` and thus to the
71 subprocess's stdin. If used it must be a byte sequence, or a string if
72 *encoding* or *errors* is specified or *text* is true. When
73 used, the internal :class:`Popen` object is automatically created with
74 *stdin* set to :data:`~subprocess.PIPE`,
75 and the *stdin* argument may not be used as well.
76
77 If *check* is true, and the process exits with a non-zero exit code, a
78 :exc:`CalledProcessError` exception will be raised. Attributes of that
79 exception hold the arguments, the exit code, and stdout and stderr if they
80 were captured.
81
82 If *encoding* or *errors* are specified, or *text* is true,
83 file objects for stdin, stdout and stderr are opened in text mode using the
84 specified *encoding* and *errors* or the :class:`io.TextIOWrapper` default.
85 The *universal_newlines* argument is equivalent to *text* and is provided
86 for backwards compatibility. By default, file objects are opened in binary mode.
87
88 If *env* is not ``None``, it must be a mapping that defines the environment
89 variables for the new process; these are used instead of the default
90 behavior of inheriting the current process' environment. It is passed
91 directly to :class:`Popen`. This mapping can be str to str on any platform
92 or bytes to bytes on POSIX platforms much like :data:`os.environ` or
93 :data:`os.environb`.
94
95 Examples::
96
97 >>> subprocess.run(["ls", "-l"]) # doesn't capture output
98 CompletedProcess(args=['ls', '-l'], returncode=0)
99
100 >>> subprocess.run("exit 1", shell=True, check=True)
101 Traceback (most recent call last):
102 ...
103 subprocess.CalledProcessError: Command 'exit 1' returned non-zero exit status 1
104
105 >>> subprocess.run(["ls", "-l", "/dev/null"], capture_output=True)
106 CompletedProcess(args=['ls', '-l', '/dev/null'], returncode=0,
107 stdout=b'crw-rw-rw- 1 root root 1, 3 Jan 23 16:23 /dev/null\n', stderr=b'')
108
109 .. versionadded:: 3.5
110
111 .. versionchanged:: 3.6
112
113 Added *encoding* and *errors* parameters
114
115 .. versionchanged:: 3.7
116
117 Added the *text* parameter, as a more understandable alias of *universal_newlines*.
118 Added the *capture_output* parameter.
119
120 .. versionchanged:: 3.12
121
122 Changed Windows shell search order for ``shell=True``. The current
123 directory and ``%PATH%`` are replaced with ``%COMSPEC%`` and
124 ``%SystemRoot%\System32\cmd.exe``. As a result, dropping a
125 malicious program named ``cmd.exe`` into a current directory no
126 longer works.
127
128 .. class:: CompletedProcess
129
130 The return value from :func:`run`, representing a process that has finished.
131
132 .. attribute:: args
133
134 The arguments used to launch the process. This may be a list or a string.
135
136 .. attribute:: returncode
137
138 Exit status of the child process. Typically, an exit status of 0 indicates
139 that it ran successfully.
140
141 A negative value ``-N`` indicates that the child was terminated by signal
142 ``N`` (POSIX only).
143
144 .. attribute:: stdout
145
146 Captured stdout from the child process. A bytes sequence, or a string if
147 :func:`run` was called with an encoding, errors, or text=True.
148 ``None`` if stdout was not captured.
149
150 If you ran the process with ``stderr=subprocess.STDOUT``, stdout and
151 stderr will be combined in this attribute, and :attr:`stderr` will be
152 ``None``.
153
154 .. attribute:: stderr
155
156 Captured stderr from the child process. A bytes sequence, or a string if
157 :func:`run` was called with an encoding, errors, or text=True.
158 ``None`` if stderr was not captured.
159
160 .. method:: check_returncode()
161
162 If :attr:`returncode` is non-zero, raise a :exc:`CalledProcessError`.
163
164 .. versionadded:: 3.5
165
166 .. data:: DEVNULL
167
168 Special value that can be used as the *stdin*, *stdout* or *stderr* argument
169 to :class:`Popen` and indicates that the special file :data:`os.devnull`
170 will be used.
171
172 .. versionadded:: 3.3
173
174
175 .. data:: PIPE
176
177 Special value that can be used as the *stdin*, *stdout* or *stderr* argument
178 to :class:`Popen` and indicates that a pipe to the standard stream should be
179 opened. Most useful with :meth:`Popen.communicate`.
180
181
182 .. data:: STDOUT
183
184 Special value that can be used as the *stderr* argument to :class:`Popen` and
185 indicates that standard error should go into the same handle as standard
186 output.
187
188
189 .. exception:: SubprocessError
190
191 Base class for all other exceptions from this module.
192
193 .. versionadded:: 3.3
194
195
196 .. exception:: TimeoutExpired
197
198 Subclass of :exc:`SubprocessError`, raised when a timeout expires
199 while waiting for a child process.
200
201 .. attribute:: cmd
202
203 Command that was used to spawn the child process.
204
205 .. attribute:: timeout
206
207 Timeout in seconds.
208
209 .. attribute:: output
210
211 Output of the child process if it was captured by :func:`run` or
212 :func:`check_output`. Otherwise, ``None``. This is always
213 :class:`bytes` when any output was captured regardless of the
214 ``text=True`` setting. It may remain ``None`` instead of ``b''``
215 when no output was observed.
216
217 .. attribute:: stdout
218
219 Alias for output, for symmetry with :attr:`stderr`.
220
221 .. attribute:: stderr
222
223 Stderr output of the child process if it was captured by :func:`run`.
224 Otherwise, ``None``. This is always :class:`bytes` when stderr output
225 was captured regardless of the ``text=True`` setting. It may remain
226 ``None`` instead of ``b''`` when no stderr output was observed.
227
228 .. versionadded:: 3.3
229
230 .. versionchanged:: 3.5
231 *stdout* and *stderr* attributes added
232
233 .. exception:: CalledProcessError
234
235 Subclass of :exc:`SubprocessError`, raised when a process run by
236 :func:`check_call`, :func:`check_output`, or :func:`run` (with ``check=True``)
237 returns a non-zero exit status.
238
239
240 .. attribute:: returncode
241
242 Exit status of the child process. If the process exited due to a
243 signal, this will be the negative signal number.
244
245 .. attribute:: cmd
246
247 Command that was used to spawn the child process.
248
249 .. attribute:: output
250
251 Output of the child process if it was captured by :func:`run` or
252 :func:`check_output`. Otherwise, ``None``.
253
254 .. attribute:: stdout
255
256 Alias for output, for symmetry with :attr:`stderr`.
257
258 .. attribute:: stderr
259
260 Stderr output of the child process if it was captured by :func:`run`.
261 Otherwise, ``None``.
262
263 .. versionchanged:: 3.5
264 *stdout* and *stderr* attributes added
265
266
267 .. _frequently-used-arguments:
268
269 Frequently Used Arguments
270 ^^^^^^^^^^^^^^^^^^^^^^^^^
271
272 To support a wide variety of use cases, the :class:`Popen` constructor (and
273 the convenience functions) accept a large number of optional arguments. For
274 most typical use cases, many of these arguments can be safely left at their
275 default values. The arguments that are most commonly needed are:
276
277 *args* is required for all calls and should be a string, or a sequence of
278 program arguments. Providing a sequence of arguments is generally
279 preferred, as it allows the module to take care of any required escaping
280 and quoting of arguments (e.g. to permit spaces in file names). If passing
281 a single string, either *shell* must be :const:`True` (see below) or else
282 the string must simply name the program to be executed without specifying
283 any arguments.
284
285 *stdin*, *stdout* and *stderr* specify the executed program's standard input,
286 standard output and standard error file handles, respectively. Valid values
287 are ``None``, :data:`PIPE`, :data:`DEVNULL`, an existing file descriptor (a
288 positive integer), and an existing :term:`file object` with a valid file
289 descriptor. With the default settings of ``None``, no redirection will
290 occur. :data:`PIPE` indicates that a new pipe to the child should be
291 created. :data:`DEVNULL` indicates that the special file :data:`os.devnull`
292 will be used. Additionally, *stderr* can be :data:`STDOUT`, which indicates
293 that the stderr data from the child process should be captured into the same
294 file handle as for *stdout*.
295
296 .. index::
297 single: universal newlines; subprocess module
298
299 If *encoding* or *errors* are specified, or *text* (also known as
300 *universal_newlines*) is true,
301 the file objects *stdin*, *stdout* and *stderr* will be opened in text
302 mode using the *encoding* and *errors* specified in the call or the
303 defaults for :class:`io.TextIOWrapper`.
304
305 For *stdin*, line ending characters ``'\n'`` in the input will be converted
306 to the default line separator :data:`os.linesep`. For *stdout* and *stderr*,
307 all line endings in the output will be converted to ``'\n'``. For more
308 information see the documentation of the :class:`io.TextIOWrapper` class
309 when the *newline* argument to its constructor is ``None``.
310
311 If text mode is not used, *stdin*, *stdout* and *stderr* will be opened as
312 binary streams. No encoding or line ending conversion is performed.
313
314 .. versionchanged:: 3.6
315 Added the *encoding* and *errors* parameters.
316
317 .. versionchanged:: 3.7
318 Added the *text* parameter as an alias for *universal_newlines*.
319
320 .. note::
321
322 The newlines attribute of the file objects :attr:`Popen.stdin`,
323 :attr:`Popen.stdout` and :attr:`Popen.stderr` are not updated by
324 the :meth:`Popen.communicate` method.
325
326 If *shell* is ``True``, the specified command will be executed through
327 the shell. This can be useful if you are using Python primarily for the
328 enhanced control flow it offers over most system shells and still want
329 convenient access to other shell features such as shell pipes, filename
330 wildcards, environment variable expansion, and expansion of ``~`` to a
331 user's home directory. However, note that Python itself offers
332 implementations of many shell-like features (in particular, :mod:`glob`,
333 :mod:`fnmatch`, :func:`os.walk`, :func:`os.path.expandvars`,
334 :func:`os.path.expanduser`, and :mod:`shutil`).
335
336 .. versionchanged:: 3.3
337 When *universal_newlines* is ``True``, the class uses the encoding
338 :func:`locale.getpreferredencoding(False) <locale.getpreferredencoding>`
339 instead of ``locale.getpreferredencoding()``. See the
340 :class:`io.TextIOWrapper` class for more information on this change.
341
342 .. note::
343
344 Read the `Security Considerations`_ section before using ``shell=True``.
345
346 These options, along with all of the other options, are described in more
347 detail in the :class:`Popen` constructor documentation.
348
349
350 Popen Constructor
351 ^^^^^^^^^^^^^^^^^
352
353 The underlying process creation and management in this module is handled by
354 the :class:`Popen` class. It offers a lot of flexibility so that developers
355 are able to handle the less common cases not covered by the convenience
356 functions.
357
358
359 .. class:: Popen(args, bufsize=-1, executable=None, stdin=None, stdout=None, \
360 stderr=None, preexec_fn=None, close_fds=True, shell=False, \
361 cwd=None, env=None, universal_newlines=None, \
362 startupinfo=None, creationflags=0, restore_signals=True, \
363 start_new_session=False, pass_fds=(), *, group=None, \
364 extra_groups=None, user=None, umask=-1, \
365 encoding=None, errors=None, text=None, pipesize=-1, \
366 process_group=None)
367
368 Execute a child program in a new process. On POSIX, the class uses
369 :meth:`os.execvpe`-like behavior to execute the child program. On Windows,
370 the class uses the Windows ``CreateProcess()`` function. The arguments to
371 :class:`Popen` are as follows.
372
373 *args* should be a sequence of program arguments or else a single string
374 or :term:`path-like object`.
375 By default, the program to execute is the first item in *args* if *args* is
376 a sequence. If *args* is a string, the interpretation is
377 platform-dependent and described below. See the *shell* and *executable*
378 arguments for additional differences from the default behavior. Unless
379 otherwise stated, it is recommended to pass *args* as a sequence.
380
381 .. warning::
382
383 For maximum reliability, use a fully qualified path for the executable.
384 To search for an unqualified name on :envvar:`PATH`, use
385 :meth:`shutil.which`. On all platforms, passing :data:`sys.executable`
386 is the recommended way to launch the current Python interpreter again,
387 and use the ``-m`` command-line format to launch an installed module.
388
389 Resolving the path of *executable* (or the first item of *args*) is
390 platform dependent. For POSIX, see :meth:`os.execvpe`, and note that
391 when resolving or searching for the executable path, *cwd* overrides the
392 current working directory and *env* can override the ``PATH``
393 environment variable. For Windows, see the documentation of the
394 ``lpApplicationName`` and ``lpCommandLine`` parameters of WinAPI
395 ``CreateProcess``, and note that when resolving or searching for the
396 executable path with ``shell=False``, *cwd* does not override the
397 current working directory and *env* cannot override the ``PATH``
398 environment variable. Using a full path avoids all of these variations.
399
400 An example of passing some arguments to an external program
401 as a sequence is::
402
403 Popen(["/usr/bin/git", "commit", "-m", "Fixes a bug."])
404
405 On POSIX, if *args* is a string, the string is interpreted as the name or
406 path of the program to execute. However, this can only be done if not
407 passing arguments to the program.
408
409 .. note::
410
411 It may not be obvious how to break a shell command into a sequence of arguments,
412 especially in complex cases. :meth:`shlex.split` can illustrate how to
413 determine the correct tokenization for *args*::
414
415 >>> import shlex, subprocess
416 >>> command_line = input()
417 /bin/vikings -input eggs.txt -output "spam spam.txt" -cmd "echo '$MONEY'"
418 >>> args = shlex.split(command_line)
419 >>> print(args)
420 ['/bin/vikings', '-input', 'eggs.txt', '-output', 'spam spam.txt', '-cmd', "echo '$MONEY'"]
421 >>> p = subprocess.Popen(args) # Success!
422
423 Note in particular that options (such as *-input*) and arguments (such
424 as *eggs.txt*) that are separated by whitespace in the shell go in separate
425 list elements, while arguments that need quoting or backslash escaping when
426 used in the shell (such as filenames containing spaces or the *echo* command
427 shown above) are single list elements.
428
429 On Windows, if *args* is a sequence, it will be converted to a string in a
430 manner described in :ref:`converting-argument-sequence`. This is because
431 the underlying ``CreateProcess()`` operates on strings.
432
433 .. versionchanged:: 3.6
434 *args* parameter accepts a :term:`path-like object` if *shell* is
435 ``False`` and a sequence containing path-like objects on POSIX.
436
437 .. versionchanged:: 3.8
438 *args* parameter accepts a :term:`path-like object` if *shell* is
439 ``False`` and a sequence containing bytes and path-like objects
440 on Windows.
441
442 The *shell* argument (which defaults to ``False``) specifies whether to use
443 the shell as the program to execute. If *shell* is ``True``, it is
444 recommended to pass *args* as a string rather than as a sequence.
445
446 On POSIX with ``shell=True``, the shell defaults to :file:`/bin/sh`. If
447 *args* is a string, the string specifies the command
448 to execute through the shell. This means that the string must be
449 formatted exactly as it would be when typed at the shell prompt. This
450 includes, for example, quoting or backslash escaping filenames with spaces in
451 them. If *args* is a sequence, the first item specifies the command string, and
452 any additional items will be treated as additional arguments to the shell
453 itself. That is to say, :class:`Popen` does the equivalent of::
454
455 Popen(['/bin/sh', '-c', args[0], args[1], ...])
456
457 On Windows with ``shell=True``, the :envvar:`COMSPEC` environment variable
458 specifies the default shell. The only time you need to specify
459 ``shell=True`` on Windows is when the command you wish to execute is built
460 into the shell (e.g. :command:`dir` or :command:`copy`). You do not need
461 ``shell=True`` to run a batch file or console-based executable.
462
463 .. note::
464
465 Read the `Security Considerations`_ section before using ``shell=True``.
466
467 *bufsize* will be supplied as the corresponding argument to the
468 :func:`open` function when creating the stdin/stdout/stderr pipe
469 file objects:
470
471 - ``0`` means unbuffered (read and write are one
472 system call and can return short)
473 - ``1`` means line buffered
474 (only usable if ``text=True`` or ``universal_newlines=True``)
475 - any other positive value means use a buffer of approximately that
476 size
477 - negative bufsize (the default) means the system default of
478 io.DEFAULT_BUFFER_SIZE will be used.
479
480 .. versionchanged:: 3.3.1
481 *bufsize* now defaults to -1 to enable buffering by default to match the
482 behavior that most code expects. In versions prior to Python 3.2.4 and
483 3.3.1 it incorrectly defaulted to ``0`` which was unbuffered
484 and allowed short reads. This was unintentional and did not match the
485 behavior of Python 2 as most code expected.
486
487 The *executable* argument specifies a replacement program to execute. It
488 is very seldom needed. When ``shell=False``, *executable* replaces the
489 program to execute specified by *args*. However, the original *args* is
490 still passed to the program. Most programs treat the program specified
491 by *args* as the command name, which can then be different from the program
492 actually executed. On POSIX, the *args* name
493 becomes the display name for the executable in utilities such as
494 :program:`ps`. If ``shell=True``, on POSIX the *executable* argument
495 specifies a replacement shell for the default :file:`/bin/sh`.
496
497 .. versionchanged:: 3.6
498 *executable* parameter accepts a :term:`path-like object` on POSIX.
499
500 .. versionchanged:: 3.8
501 *executable* parameter accepts a bytes and :term:`path-like object`
502 on Windows.
503
504 .. versionchanged:: 3.12
505
506 Changed Windows shell search order for ``shell=True``. The current
507 directory and ``%PATH%`` are replaced with ``%COMSPEC%`` and
508 ``%SystemRoot%\System32\cmd.exe``. As a result, dropping a
509 malicious program named ``cmd.exe`` into a current directory no
510 longer works.
511
512 *stdin*, *stdout* and *stderr* specify the executed program's standard input,
513 standard output and standard error file handles, respectively. Valid values
514 are ``None``, :data:`PIPE`, :data:`DEVNULL`, an existing file descriptor (a
515 positive integer), and an existing :term:`file object` with a valid file
516 descriptor. With the default settings of ``None``, no redirection will
517 occur. :data:`PIPE` indicates that a new pipe to the child should be
518 created. :data:`DEVNULL` indicates that the special file :data:`os.devnull`
519 will be used. Additionally, *stderr* can be :data:`STDOUT`, which indicates
520 that the stderr data from the applications should be captured into the same
521 file handle as for *stdout*.
522
523 If *preexec_fn* is set to a callable object, this object will be called in the
524 child process just before the child is executed.
525 (POSIX only)
526
527 .. warning::
528
529 The *preexec_fn* parameter is NOT SAFE to use in the presence of threads
530 in your application. The child process could deadlock before exec is
531 called.
532
533 .. note::
534
535 If you need to modify the environment for the child use the *env*
536 parameter rather than doing it in a *preexec_fn*.
537 The *start_new_session* and *process_group* parameters should take the place of
538 code using *preexec_fn* to call :func:`os.setsid` or :func:`os.setpgid` in the child.
539
540 .. versionchanged:: 3.8
541
542 The *preexec_fn* parameter is no longer supported in subinterpreters.
543 The use of the parameter in a subinterpreter raises
544 :exc:`RuntimeError`. The new restriction may affect applications that
545 are deployed in mod_wsgi, uWSGI, and other embedded environments.
546
547 If *close_fds* is true, all file descriptors except ``0``, ``1`` and
548 ``2`` will be closed before the child process is executed. Otherwise
549 when *close_fds* is false, file descriptors obey their inheritable flag
550 as described in :ref:`fd_inheritance`.
551
552 On Windows, if *close_fds* is true then no handles will be inherited by the
553 child process unless explicitly passed in the ``handle_list`` element of
554 :attr:`STARTUPINFO.lpAttributeList`, or by standard handle redirection.
555
556 .. versionchanged:: 3.2
557 The default for *close_fds* was changed from :const:`False` to
558 what is described above.
559
560 .. versionchanged:: 3.7
561 On Windows the default for *close_fds* was changed from :const:`False` to
562 :const:`True` when redirecting the standard handles. It's now possible to
563 set *close_fds* to :const:`True` when redirecting the standard handles.
564
565 *pass_fds* is an optional sequence of file descriptors to keep open
566 between the parent and child. Providing any *pass_fds* forces
567 *close_fds* to be :const:`True`. (POSIX only)
568
569 .. versionchanged:: 3.2
570 The *pass_fds* parameter was added.
571
572 If *cwd* is not ``None``, the function changes the working directory to
573 *cwd* before executing the child. *cwd* can be a string, bytes or
574 :term:`path-like <path-like object>` object. On POSIX, the function
575 looks for *executable* (or for the first item in *args*) relative to *cwd*
576 if the executable path is a relative path.
577
578 .. versionchanged:: 3.6
579 *cwd* parameter accepts a :term:`path-like object` on POSIX.
580
581 .. versionchanged:: 3.7
582 *cwd* parameter accepts a :term:`path-like object` on Windows.
583
584 .. versionchanged:: 3.8
585 *cwd* parameter accepts a bytes object on Windows.
586
587 If *restore_signals* is true (the default) all signals that Python has set to
588 SIG_IGN are restored to SIG_DFL in the child process before the exec.
589 Currently this includes the SIGPIPE, SIGXFZ and SIGXFSZ signals.
590 (POSIX only)
591
592 .. versionchanged:: 3.2
593 *restore_signals* was added.
594
595 If *start_new_session* is true the ``setsid()`` system call will be made in the
596 child process prior to the execution of the subprocess.
597
598 .. availability:: POSIX
599 .. versionchanged:: 3.2
600 *start_new_session* was added.
601
602 If *process_group* is a non-negative integer, the ``setpgid(0, value)`` system call will
603 be made in the child process prior to the execution of the subprocess.
604
605 .. availability:: POSIX
606 .. versionchanged:: 3.11
607 *process_group* was added.
608
609 If *group* is not ``None``, the setregid() system call will be made in the
610 child process prior to the execution of the subprocess. If the provided
611 value is a string, it will be looked up via :func:`grp.getgrnam` and
612 the value in ``gr_gid`` will be used. If the value is an integer, it
613 will be passed verbatim. (POSIX only)
614
615 .. availability:: POSIX
616 .. versionadded:: 3.9
617
618 If *extra_groups* is not ``None``, the setgroups() system call will be
619 made in the child process prior to the execution of the subprocess.
620 Strings provided in *extra_groups* will be looked up via
621 :func:`grp.getgrnam` and the values in ``gr_gid`` will be used.
622 Integer values will be passed verbatim. (POSIX only)
623
624 .. availability:: POSIX
625 .. versionadded:: 3.9
626
627 If *user* is not ``None``, the setreuid() system call will be made in the
628 child process prior to the execution of the subprocess. If the provided
629 value is a string, it will be looked up via :func:`pwd.getpwnam` and
630 the value in ``pw_uid`` will be used. If the value is an integer, it will
631 be passed verbatim. (POSIX only)
632
633 .. note::
634
635 Specifying *user* will not drop existing supplementary group memberships!
636 The caller must also pass ``extra_groups=()`` to reduce the group membership
637 of the child process for security purposes.
638
639 .. availability:: POSIX
640 .. versionadded:: 3.9
641
642 If *umask* is not negative, the umask() system call will be made in the
643 child process prior to the execution of the subprocess.
644
645 .. availability:: POSIX
646 .. versionadded:: 3.9
647
648 If *env* is not ``None``, it must be a mapping that defines the environment
649 variables for the new process; these are used instead of the default
650 behavior of inheriting the current process' environment. This mapping can be
651 str to str on any platform or bytes to bytes on POSIX platforms much like
652 :data:`os.environ` or :data:`os.environb`.
653
654 .. note::
655
656 If specified, *env* must provide any variables required for the program to
657 execute. On Windows, in order to run a `side-by-side assembly`_ the
658 specified *env* **must** include a valid ``%SystemRoot%``.
659
660 .. _side-by-side assembly: https://en.wikipedia.org/wiki/Side-by-Side_Assembly
661
662 If *encoding* or *errors* are specified, or *text* is true, the file objects
663 *stdin*, *stdout* and *stderr* are opened in text mode with the specified
664 *encoding* and *errors*, as described above in :ref:`frequently-used-arguments`.
665 The *universal_newlines* argument is equivalent to *text* and is provided
666 for backwards compatibility. By default, file objects are opened in binary mode.
667
668 .. versionadded:: 3.6
669 *encoding* and *errors* were added.
670
671 .. versionadded:: 3.7
672 *text* was added as a more readable alias for *universal_newlines*.
673
674 If given, *startupinfo* will be a :class:`STARTUPINFO` object, which is
675 passed to the underlying ``CreateProcess`` function.
676
677 If given, *creationflags*, can be one or more of the following flags:
678
679 * :data:`CREATE_NEW_CONSOLE`
680 * :data:`CREATE_NEW_PROCESS_GROUP`
681 * :data:`ABOVE_NORMAL_PRIORITY_CLASS`
682 * :data:`BELOW_NORMAL_PRIORITY_CLASS`
683 * :data:`HIGH_PRIORITY_CLASS`
684 * :data:`IDLE_PRIORITY_CLASS`
685 * :data:`NORMAL_PRIORITY_CLASS`
686 * :data:`REALTIME_PRIORITY_CLASS`
687 * :data:`CREATE_NO_WINDOW`
688 * :data:`DETACHED_PROCESS`
689 * :data:`CREATE_DEFAULT_ERROR_MODE`
690 * :data:`CREATE_BREAKAWAY_FROM_JOB`
691
692 *pipesize* can be used to change the size of the pipe when
693 :data:`PIPE` is used for *stdin*, *stdout* or *stderr*. The size of the pipe
694 is only changed on platforms that support this (only Linux at this time of
695 writing). Other platforms will ignore this parameter.
696
697 .. versionchanged:: 3.10
698 Added the *pipesize* parameter.
699
700 Popen objects are supported as context managers via the :keyword:`with` statement:
701 on exit, standard file descriptors are closed, and the process is waited for.
702 ::
703
704 with Popen(["ifconfig"], stdout=PIPE) as proc:
705 log.write(proc.stdout.read())
706
707 .. audit-event:: subprocess.Popen executable,args,cwd,env subprocess.Popen
708
709 Popen and the other functions in this module that use it raise an
710 :ref:`auditing event <auditing>` ``subprocess.Popen`` with arguments
711 ``executable``, ``args``, ``cwd``, and ``env``. The value for ``args``
712 may be a single string or a list of strings, depending on platform.
713
714 .. versionchanged:: 3.2
715 Added context manager support.
716
717 .. versionchanged:: 3.6
718 Popen destructor now emits a :exc:`ResourceWarning` warning if the child
719 process is still running.
720
721 .. versionchanged:: 3.8
722 Popen can use :func:`os.posix_spawn` in some cases for better
723 performance. On Windows Subsystem for Linux and QEMU User Emulation,
724 Popen constructor using :func:`os.posix_spawn` no longer raise an
725 exception on errors like missing program, but the child process fails
726 with a non-zero :attr:`~Popen.returncode`.
727
728
729 Exceptions
730 ^^^^^^^^^^
731
732 Exceptions raised in the child process, before the new program has started to
733 execute, will be re-raised in the parent.
734
735 The most common exception raised is :exc:`OSError`. This occurs, for example,
736 when trying to execute a non-existent file. Applications should prepare for
737 :exc:`OSError` exceptions. Note that, when ``shell=True``, :exc:`OSError`
738 will be raised by the child only if the selected shell itself was not found.
739 To determine if the shell failed to find the requested application, it is
740 necessary to check the return code or output from the subprocess.
741
742 A :exc:`ValueError` will be raised if :class:`Popen` is called with invalid
743 arguments.
744
745 :func:`check_call` and :func:`check_output` will raise
746 :exc:`CalledProcessError` if the called process returns a non-zero return
747 code.
748
749 All of the functions and methods that accept a *timeout* parameter, such as
750 :func:`run` and :meth:`Popen.communicate` will raise :exc:`TimeoutExpired` if
751 the timeout expires before the process exits.
752
753 Exceptions defined in this module all inherit from :exc:`SubprocessError`.
754
755 .. versionadded:: 3.3
756 The :exc:`SubprocessError` base class was added.
757
758 .. _subprocess-security:
759
760 Security Considerations
761 -----------------------
762
763 Unlike some other popen functions, this library will not
764 implicitly choose to call a system shell. This means that all characters,
765 including shell metacharacters, can safely be passed to child processes.
766 If the shell is invoked explicitly, via ``shell=True``, it is the application's
767 responsibility to ensure that all whitespace and metacharacters are
768 quoted appropriately to avoid
769 `shell injection <https://en.wikipedia.org/wiki/Shell_injection#Shell_injection>`_
770 vulnerabilities. On :ref:`some platforms <shlex-quote-warning>`, it is possible
771 to use :func:`shlex.quote` for this escaping.
772
773 On Windows, batch files (:file:`*.bat` or :file:`*.cmd`) may be launched by the
774 operating system in a system shell regardless of the arguments passed to this
775 library. This could result in arguments being parsed according to shell rules,
776 but without any escaping added by Python. If you are intentionally launching a
777 batch file with arguments from untrusted sources, consider passing
778 ``shell=True`` to allow Python to escape special characters. See :gh:`114539`
779 for additional discussion.
780
781
782 Popen Objects
783 -------------
784
785 Instances of the :class:`Popen` class have the following methods:
786
787
788 .. method:: Popen.poll()
789
790 Check if child process has terminated. Set and return
791 :attr:`~Popen.returncode` attribute. Otherwise, returns ``None``.
792
793
794 .. method:: Popen.wait(timeout=None)
795
796 Wait for child process to terminate. Set and return
797 :attr:`~Popen.returncode` attribute.
798
799 If the process does not terminate after *timeout* seconds, raise a
800 :exc:`TimeoutExpired` exception. It is safe to catch this exception and
801 retry the wait.
802
803 .. note::
804
805 This will deadlock when using ``stdout=PIPE`` or ``stderr=PIPE``
806 and the child process generates enough output to a pipe such that
807 it blocks waiting for the OS pipe buffer to accept more data.
808 Use :meth:`Popen.communicate` when using pipes to avoid that.
809
810 .. note::
811
812 When the ``timeout`` parameter is not ``None``, then (on POSIX) the
813 function is implemented using a busy loop (non-blocking call and short
814 sleeps). Use the :mod:`asyncio` module for an asynchronous wait: see
815 :class:`asyncio.create_subprocess_exec`.
816
817 .. versionchanged:: 3.3
818 *timeout* was added.
819
820 .. method:: Popen.communicate(input=None, timeout=None)
821
822 Interact with process: Send data to stdin. Read data from stdout and stderr,
823 until end-of-file is reached. Wait for process to terminate and set the
824 :attr:`~Popen.returncode` attribute. The optional *input* argument should be
825 data to be sent to the child process, or ``None``, if no data should be sent
826 to the child. If streams were opened in text mode, *input* must be a string.
827 Otherwise, it must be bytes.
828
829 :meth:`communicate` returns a tuple ``(stdout_data, stderr_data)``.
830 The data will be strings if streams were opened in text mode; otherwise,
831 bytes.
832
833 Note that if you want to send data to the process's stdin, you need to create
834 the Popen object with ``stdin=PIPE``. Similarly, to get anything other than
835 ``None`` in the result tuple, you need to give ``stdout=PIPE`` and/or
836 ``stderr=PIPE`` too.
837
838 If the process does not terminate after *timeout* seconds, a
839 :exc:`TimeoutExpired` exception will be raised. Catching this exception and
840 retrying communication will not lose any output. Supplying *input* to a
841 subsequent post-timeout :meth:`communicate` call is in undefined behavior
842 and may become an error in the future.
843
844 The child process is not killed if the timeout expires, so in order to
845 cleanup properly a well-behaved application should kill the child process and
846 finish communication::
847
848 proc = subprocess.Popen(...)
849 try:
850 outs, errs = proc.communicate(timeout=15)
851 except TimeoutExpired:
852 proc.kill()
853 outs, errs = proc.communicate()
854
855 After a call to :meth:`~Popen.communicate` raises :exc:`TimeoutExpired`, do
856 not call :meth:`~Popen.wait`. Use an additional :meth:`~Popen.communicate`
857 call to finish handling pipes and populate the :attr:`~Popen.returncode`
858 attribute.
859
860 .. note::
861
862 The data read is buffered in memory, so do not use this method if the data
863 size is large or unlimited.
864
865 .. versionchanged:: 3.3
866 *timeout* was added.
867
868
869 .. method:: Popen.send_signal(signal)
870
871 Sends the signal *signal* to the child.
872
873 Do nothing if the process completed.
874
875 .. note::
876
877 On Windows, SIGTERM is an alias for :meth:`terminate`. CTRL_C_EVENT and
878 CTRL_BREAK_EVENT can be sent to processes started with a *creationflags*
879 parameter which includes ``CREATE_NEW_PROCESS_GROUP``.
880
881
882 .. method:: Popen.terminate()
883
884 Stop the child. On POSIX OSs the method sends :py:const:`~signal.SIGTERM` to the
885 child. On Windows the Win32 API function :c:func:`!TerminateProcess` is called
886 to stop the child.
887
888
889 .. method:: Popen.kill()
890
891 Kills the child. On POSIX OSs the function sends SIGKILL to the child.
892 On Windows :meth:`kill` is an alias for :meth:`terminate`.
893
894
895 The following attributes are also set by the class for you to access.
896 Reassigning them to new values is unsupported:
897
898 .. attribute:: Popen.args
899
900 The *args* argument as it was passed to :class:`Popen` -- a
901 sequence of program arguments or else a single string.
902
903 .. versionadded:: 3.3
904
905 .. attribute:: Popen.stdin
906
907 If the *stdin* argument was :data:`PIPE`, this attribute is a writeable
908 stream object as returned by :func:`open`. If the *encoding* or *errors*
909 arguments were specified or the *text* or *universal_newlines* argument
910 was ``True``, the stream is a text stream, otherwise it is a byte stream.
911 If the *stdin* argument was not :data:`PIPE`, this attribute is ``None``.
912
913
914 .. attribute:: Popen.stdout
915
916 If the *stdout* argument was :data:`PIPE`, this attribute is a readable
917 stream object as returned by :func:`open`. Reading from the stream provides
918 output from the child process. If the *encoding* or *errors* arguments were
919 specified or the *text* or *universal_newlines* argument was ``True``, the
920 stream is a text stream, otherwise it is a byte stream. If the *stdout*
921 argument was not :data:`PIPE`, this attribute is ``None``.
922
923
924 .. attribute:: Popen.stderr
925
926 If the *stderr* argument was :data:`PIPE`, this attribute is a readable
927 stream object as returned by :func:`open`. Reading from the stream provides
928 error output from the child process. If the *encoding* or *errors* arguments
929 were specified or the *text* or *universal_newlines* argument was ``True``, the
930 stream is a text stream, otherwise it is a byte stream. If the *stderr* argument
931 was not :data:`PIPE`, this attribute is ``None``.
932
933 .. warning::
934
935 Use :meth:`~Popen.communicate` rather than :attr:`.stdin.write <Popen.stdin>`,
936 :attr:`.stdout.read <Popen.stdout>` or :attr:`.stderr.read <Popen.stderr>` to avoid
937 deadlocks due to any of the other OS pipe buffers filling up and blocking the
938 child process.
939
940
941 .. attribute:: Popen.pid
942
943 The process ID of the child process.
944
945 Note that if you set the *shell* argument to ``True``, this is the process ID
946 of the spawned shell.
947
948
949 .. attribute:: Popen.returncode
950
951 The child return code. Initially ``None``, :attr:`returncode` is set by
952 a call to the :meth:`poll`, :meth:`wait`, or :meth:`communicate` methods
953 if they detect that the process has terminated.
954
955 A ``None`` value indicates that the process hadn't yet terminated at the
956 time of the last method call.
957
958 A negative value ``-N`` indicates that the child was terminated by signal
959 ``N`` (POSIX only).
960
961 When ``shell=True``, the return code reflects the exit status of the shell
962 itself (e.g. ``/bin/sh``), which may map signals to codes such as
963 ``128+N``. See the documentation of the shell (for example, the Bash
964 manual's Exit Status) for details.
965
966
967 Windows Popen Helpers
968 ---------------------
969
970 The :class:`STARTUPINFO` class and following constants are only available
971 on Windows.
972
973 .. class:: STARTUPINFO(*, dwFlags=0, hStdInput=None, hStdOutput=None, \
974 hStdError=None, wShowWindow=0, lpAttributeList=None)
975
976 Partial support of the Windows
977 `STARTUPINFO <https://msdn.microsoft.com/en-us/library/ms686331(v=vs.85).aspx>`__
978 structure is used for :class:`Popen` creation. The following attributes can
979 be set by passing them as keyword-only arguments.
980
981 .. versionchanged:: 3.7
982 Keyword-only argument support was added.
983
984 .. attribute:: dwFlags
985
986 A bit field that determines whether certain :class:`STARTUPINFO`
987 attributes are used when the process creates a window. ::
988
989 si = subprocess.STARTUPINFO()
990 si.dwFlags = subprocess.STARTF_USESTDHANDLES | subprocess.STARTF_USESHOWWINDOW
991
992 .. attribute:: hStdInput
993
994 If :attr:`dwFlags` specifies :data:`STARTF_USESTDHANDLES`, this attribute
995 is the standard input handle for the process. If
996 :data:`STARTF_USESTDHANDLES` is not specified, the default for standard
997 input is the keyboard buffer.
998
999 .. attribute:: hStdOutput
1000
1001 If :attr:`dwFlags` specifies :data:`STARTF_USESTDHANDLES`, this attribute
1002 is the standard output handle for the process. Otherwise, this attribute
1003 is ignored and the default for standard output is the console window's
1004 buffer.
1005
1006 .. attribute:: hStdError
1007
1008 If :attr:`dwFlags` specifies :data:`STARTF_USESTDHANDLES`, this attribute
1009 is the standard error handle for the process. Otherwise, this attribute is
1010 ignored and the default for standard error is the console window's buffer.
1011
1012 .. attribute:: wShowWindow
1013
1014 If :attr:`dwFlags` specifies :data:`STARTF_USESHOWWINDOW`, this attribute
1015 can be any of the values that can be specified in the ``nCmdShow``
1016 parameter for the
1017 `ShowWindow <https://msdn.microsoft.com/en-us/library/ms633548(v=vs.85).aspx>`__
1018 function, except for ``SW_SHOWDEFAULT``. Otherwise, this attribute is
1019 ignored.
1020
1021 :data:`SW_HIDE` is provided for this attribute. It is used when
1022 :class:`Popen` is called with ``shell=True``.
1023
1024 .. attribute:: lpAttributeList
1025
1026 A dictionary of additional attributes for process creation as given in
1027 ``STARTUPINFOEX``, see
1028 `UpdateProcThreadAttribute <https://msdn.microsoft.com/en-us/library/windows/desktop/ms686880(v=vs.85).aspx>`__.
1029
1030 Supported attributes:
1031
1032 **handle_list**
1033 Sequence of handles that will be inherited. *close_fds* must be true if
1034 non-empty.
1035
1036 The handles must be temporarily made inheritable by
1037 :func:`os.set_handle_inheritable` when passed to the :class:`Popen`
1038 constructor, else :class:`OSError` will be raised with Windows error
1039 ``ERROR_INVALID_PARAMETER`` (87).
1040
1041 .. warning::
1042
1043 In a multithreaded process, use caution to avoid leaking handles
1044 that are marked inheritable when combining this feature with
1045 concurrent calls to other process creation functions that inherit
1046 all handles such as :func:`os.system`. This also applies to
1047 standard handle redirection, which temporarily creates inheritable
1048 handles.
1049
1050 .. versionadded:: 3.7
1051
1052 Windows Constants
1053 ^^^^^^^^^^^^^^^^^
1054
1055 The :mod:`!subprocess` module exposes the following constants.
1056
1057 .. data:: STD_INPUT_HANDLE
1058
1059 The standard input device. Initially, this is the console input buffer,
1060 ``CONIN$``.
1061
1062 .. data:: STD_OUTPUT_HANDLE
1063
1064 The standard output device. Initially, this is the active console screen
1065 buffer, ``CONOUT$``.
1066
1067 .. data:: STD_ERROR_HANDLE
1068
1069 The standard error device. Initially, this is the active console screen
1070 buffer, ``CONOUT$``.
1071
1072 .. data:: SW_HIDE
1073
1074 Hides the window. Another window will be activated.
1075
1076 .. data:: STARTF_USESTDHANDLES
1077
1078 Specifies that the :attr:`STARTUPINFO.hStdInput`,
1079 :attr:`STARTUPINFO.hStdOutput`, and :attr:`STARTUPINFO.hStdError` attributes
1080 contain additional information.
1081
1082 .. data:: STARTF_USESHOWWINDOW
1083
1084 Specifies that the :attr:`STARTUPINFO.wShowWindow` attribute contains
1085 additional information.
1086
1087 .. data:: STARTF_FORCEONFEEDBACK
1088
1089 A :attr:`STARTUPINFO.dwFlags` parameter to specify that the
1090 *Working in Background* mouse cursor will be displayed while a
1091 process is launching. This is the default behavior for GUI
1092 processes.
1093
1094 .. versionadded:: 3.13
1095
1096 .. data:: STARTF_FORCEOFFFEEDBACK
1097
1098 A :attr:`STARTUPINFO.dwFlags` parameter to specify that the mouse
1099 cursor will not be changed when launching a process.
1100
1101 .. versionadded:: 3.13
1102
1103 .. data:: CREATE_NEW_CONSOLE
1104
1105 The new process has a new console, instead of inheriting its parent's
1106 console (the default).
1107
1108 .. data:: CREATE_NEW_PROCESS_GROUP
1109
1110 A :class:`Popen` ``creationflags`` parameter to specify that a new process
1111 group will be created. This flag is necessary for using :func:`os.kill`
1112 on the subprocess.
1113
1114 This flag is ignored if :data:`CREATE_NEW_CONSOLE` is specified.
1115
1116 .. data:: ABOVE_NORMAL_PRIORITY_CLASS
1117
1118 A :class:`Popen` ``creationflags`` parameter to specify that a new process
1119 will have an above average priority.
1120
1121 .. versionadded:: 3.7
1122
1123 .. data:: BELOW_NORMAL_PRIORITY_CLASS
1124
1125 A :class:`Popen` ``creationflags`` parameter to specify that a new process
1126 will have a below average priority.
1127
1128 .. versionadded:: 3.7
1129
1130 .. data:: HIGH_PRIORITY_CLASS
1131
1132 A :class:`Popen` ``creationflags`` parameter to specify that a new process
1133 will have a high priority.
1134
1135 .. versionadded:: 3.7
1136
1137 .. data:: IDLE_PRIORITY_CLASS
1138
1139 A :class:`Popen` ``creationflags`` parameter to specify that a new process
1140 will have an idle (lowest) priority.
1141
1142 .. versionadded:: 3.7
1143
1144 .. data:: NORMAL_PRIORITY_CLASS
1145
1146 A :class:`Popen` ``creationflags`` parameter to specify that a new process
1147 will have a normal priority. (default)
1148
1149 .. versionadded:: 3.7
1150
1151 .. data:: REALTIME_PRIORITY_CLASS
1152
1153 A :class:`Popen` ``creationflags`` parameter to specify that a new process
1154 will have realtime priority.
1155 You should almost never use REALTIME_PRIORITY_CLASS, because this interrupts
1156 system threads that manage mouse input, keyboard input, and background disk
1157 flushing. This class can be appropriate for applications that "talk" directly
1158 to hardware or that perform brief tasks that should have limited interruptions.
1159
1160 .. versionadded:: 3.7
1161
1162 .. data:: CREATE_NO_WINDOW
1163
1164 A :class:`Popen` ``creationflags`` parameter to specify that a new process
1165 will not create a window.
1166
1167 .. versionadded:: 3.7
1168
1169 .. data:: DETACHED_PROCESS
1170
1171 A :class:`Popen` ``creationflags`` parameter to specify that a new process
1172 will not inherit its parent's console.
1173 This value cannot be used with CREATE_NEW_CONSOLE.
1174
1175 .. versionadded:: 3.7
1176
1177 .. data:: CREATE_DEFAULT_ERROR_MODE
1178
1179 A :class:`Popen` ``creationflags`` parameter to specify that a new process
1180 does not inherit the error mode of the calling process. Instead, the new
1181 process gets the default error mode.
1182 This feature is particularly useful for multithreaded shell applications
1183 that run with hard errors disabled.
1184
1185 .. versionadded:: 3.7
1186
1187 .. data:: CREATE_BREAKAWAY_FROM_JOB
1188
1189 A :class:`Popen` ``creationflags`` parameter to specify that a new process
1190 is not associated with the job.
1191
1192 .. versionadded:: 3.7
1193
1194 .. _call-function-trio:
1195
1196 Older high-level API
1197 --------------------
1198
1199 Prior to Python 3.5, these three functions comprised the high level API to
1200 subprocess. You can now use :func:`run` in many cases, but lots of existing code
1201 calls these functions.
1202
1203 .. function:: call(args, *, stdin=None, stdout=None, stderr=None, \
1204 shell=False, cwd=None, timeout=None, **other_popen_kwargs)
1205
1206 Run the command described by *args*. Wait for command to complete, then
1207 return the :attr:`~Popen.returncode` attribute.
1208
1209 Code needing to capture stdout or stderr should use :func:`run` instead::
1210
1211 run(...).returncode
1212
1213 To suppress stdout or stderr, supply a value of :data:`DEVNULL`.
1214
1215 The arguments shown above are merely some common ones.
1216 The full function signature is the
1217 same as that of the :class:`Popen` constructor - this function passes all
1218 supplied arguments other than *timeout* directly through to that interface.
1219
1220 .. note::
1221
1222 Do not use ``stdout=PIPE`` or ``stderr=PIPE`` with this
1223 function. The child process will block if it generates enough
1224 output to a pipe to fill up the OS pipe buffer as the pipes are
1225 not being read from.
1226
1227 .. versionchanged:: 3.3
1228 *timeout* was added.
1229
1230 .. versionchanged:: 3.12
1231
1232 Changed Windows shell search order for ``shell=True``. The current
1233 directory and ``%PATH%`` are replaced with ``%COMSPEC%`` and
1234 ``%SystemRoot%\System32\cmd.exe``. As a result, dropping a
1235 malicious program named ``cmd.exe`` into a current directory no
1236 longer works.
1237
1238 .. function:: check_call(args, *, stdin=None, stdout=None, stderr=None, \
1239 shell=False, cwd=None, timeout=None, \
1240 **other_popen_kwargs)
1241
1242 Run command with arguments. Wait for command to complete. If the return
1243 code was zero then return, otherwise raise :exc:`CalledProcessError`. The
1244 :exc:`CalledProcessError` object will have the return code in the
1245 :attr:`~CalledProcessError.returncode` attribute.
1246 If :func:`check_call` was unable to start the process it will propagate the exception
1247 that was raised.
1248
1249 Code needing to capture stdout or stderr should use :func:`run` instead::
1250
1251 run(..., check=True)
1252
1253 To suppress stdout or stderr, supply a value of :data:`DEVNULL`.
1254
1255 The arguments shown above are merely some common ones.
1256 The full function signature is the
1257 same as that of the :class:`Popen` constructor - this function passes all
1258 supplied arguments other than *timeout* directly through to that interface.
1259
1260 .. note::
1261
1262 Do not use ``stdout=PIPE`` or ``stderr=PIPE`` with this
1263 function. The child process will block if it generates enough
1264 output to a pipe to fill up the OS pipe buffer as the pipes are
1265 not being read from.
1266
1267 .. versionchanged:: 3.3
1268 *timeout* was added.
1269
1270 .. versionchanged:: 3.12
1271
1272 Changed Windows shell search order for ``shell=True``. The current
1273 directory and ``%PATH%`` are replaced with ``%COMSPEC%`` and
1274 ``%SystemRoot%\System32\cmd.exe``. As a result, dropping a
1275 malicious program named ``cmd.exe`` into a current directory no
1276 longer works.
1277
1278
1279 .. function:: check_output(args, *, stdin=None, stderr=None, shell=False, \
1280 cwd=None, encoding=None, errors=None, \
1281 universal_newlines=None, timeout=None, text=None, \
1282 **other_popen_kwargs)
1283
1284 Run command with arguments and return its output.
1285
1286 If the return code was non-zero it raises a :exc:`CalledProcessError`. The
1287 :exc:`CalledProcessError` object will have the return code in the
1288 :attr:`~CalledProcessError.returncode` attribute and any output in the
1289 :attr:`~CalledProcessError.output` attribute.
1290
1291 This is equivalent to::
1292
1293 run(..., check=True, stdout=PIPE).stdout
1294
1295 The arguments shown above are merely some common ones.
1296 The full function signature is largely the same as that of :func:`run` -
1297 most arguments are passed directly through to that interface.
1298 One API deviation from :func:`run` behavior exists: passing ``input=None``
1299 will behave the same as ``input=b''`` (or ``input=''``, depending on other
1300 arguments) rather than using the parent's standard input file handle.
1301
1302 By default, this function will return the data as encoded bytes. The actual
1303 encoding of the output data may depend on the command being invoked, so the
1304 decoding to text will often need to be handled at the application level.
1305
1306 This behaviour may be overridden by setting *text*, *encoding*, *errors*,
1307 or *universal_newlines* to ``True`` as described in
1308 :ref:`frequently-used-arguments` and :func:`run`.
1309
1310 To also capture standard error in the result, use
1311 ``stderr=subprocess.STDOUT``::
1312
1313 >>> subprocess.check_output(
1314 ... "ls non_existent_file; exit 0",
1315 ... stderr=subprocess.STDOUT,
1316 ... shell=True)
1317 'ls: non_existent_file: No such file or directory\n'
1318
1319 .. versionadded:: 3.1
1320
1321 .. versionchanged:: 3.3
1322 *timeout* was added.
1323
1324 .. versionchanged:: 3.4
1325 Support for the *input* keyword argument was added.
1326
1327 .. versionchanged:: 3.6
1328 *encoding* and *errors* were added. See :func:`run` for details.
1329
1330 .. versionadded:: 3.7
1331 *text* was added as a more readable alias for *universal_newlines*.
1332
1333 .. versionchanged:: 3.12
1334
1335 Changed Windows shell search order for ``shell=True``. The current
1336 directory and ``%PATH%`` are replaced with ``%COMSPEC%`` and
1337 ``%SystemRoot%\System32\cmd.exe``. As a result, dropping a
1338 malicious program named ``cmd.exe`` into a current directory no
1339 longer works.
1340
1341
1342 .. _subprocess-replacements:
1343
1344 Replacing Older Functions with the :mod:`!subprocess` Module
1345 ------------------------------------------------------------
1346
1347 In this section, "a becomes b" means that b can be used as a replacement for a.
1348
1349 .. note::
1350
1351 All "a" functions in this section fail (more or less) silently if the
1352 executed program cannot be found; the "b" replacements raise :exc:`OSError`
1353 instead.
1354
1355 In addition, the replacements using :func:`check_output` will fail with a
1356 :exc:`CalledProcessError` if the requested operation produces a non-zero
1357 return code. The output is still available as the
1358 :attr:`~CalledProcessError.output` attribute of the raised exception.
1359
1360 In the following examples, we assume that the relevant functions have already
1361 been imported from the :mod:`!subprocess` module.
1362
1363
1364 Replacing :program:`/bin/sh` shell command substitution
1365 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
1366
1367 .. code-block:: bash
1368
1369 output=$(mycmd myarg)
1370
1371 becomes::
1372
1373 output = check_output(["mycmd", "myarg"])
1374
1375 Replacing shell pipeline
1376 ^^^^^^^^^^^^^^^^^^^^^^^^
1377
1378 .. code-block:: bash
1379
1380 output=$(dmesg | grep hda)
1381
1382 becomes::
1383
1384 p1 = Popen(["dmesg"], stdout=PIPE)
1385 p2 = Popen(["grep", "hda"], stdin=p1.stdout, stdout=PIPE)
1386 p1.stdout.close() # Allow p1 to receive a SIGPIPE if p2 exits.
1387 output = p2.communicate()[0]
1388
1389 The ``p1.stdout.close()`` call after starting the p2 is important in order for
1390 p1 to receive a SIGPIPE if p2 exits before p1.
1391
1392 Alternatively, for trusted input, the shell's own pipeline support may still
1393 be used directly:
1394
1395 .. code-block:: bash
1396
1397 output=$(dmesg | grep hda)
1398
1399 becomes::
1400
1401 output = check_output("dmesg | grep hda", shell=True)
1402
1403
1404 Replacing :func:`os.system`
1405 ^^^^^^^^^^^^^^^^^^^^^^^^^^^
1406
1407 ::
1408
1409 sts = os.system("mycmd" + " myarg")
1410 # becomes
1411 retcode = call("mycmd" + " myarg", shell=True)
1412
1413 Notes:
1414
1415 * Calling the program through the shell is usually not required.
1416 * The :func:`call` return value is encoded differently to that of
1417 :func:`os.system`.
1418
1419 * The :func:`os.system` function ignores SIGINT and SIGQUIT signals while
1420 the command is running, but the caller must do this separately when
1421 using the :mod:`!subprocess` module.
1422
1423 A more realistic example would look like this::
1424
1425 try:
1426 retcode = call("mycmd" + " myarg", shell=True)
1427 if retcode < 0:
1428 print("Child was terminated by signal", -retcode, file=sys.stderr)
1429 else:
1430 print("Child returned", retcode, file=sys.stderr)
1431 except OSError as e:
1432 print("Execution failed:", e, file=sys.stderr)
1433
1434
1435 Replacing the :func:`os.spawn <os.spawnl>` family
1436 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
1437
1438 P_NOWAIT example::
1439
1440 pid = os.spawnlp(os.P_NOWAIT, "/bin/mycmd", "mycmd", "myarg")
1441 ==>
1442 pid = Popen(["/bin/mycmd", "myarg"]).pid
1443
1444 P_WAIT example::
1445
1446 retcode = os.spawnlp(os.P_WAIT, "/bin/mycmd", "mycmd", "myarg")
1447 ==>
1448 retcode = call(["/bin/mycmd", "myarg"])
1449
1450 Vector example::
1451
1452 os.spawnvp(os.P_NOWAIT, path, args)
1453 ==>
1454 Popen([path] + args[1:])
1455
1456 Environment example::
1457
1458 os.spawnlpe(os.P_NOWAIT, "/bin/mycmd", "mycmd", "myarg", env)
1459 ==>
1460 Popen(["/bin/mycmd", "myarg"], env={"PATH": "/usr/bin"})
1461
1462
1463
1464 Replacing :func:`os.popen`
1465 ^^^^^^^^^^^^^^^^^^^^^^^^^^
1466
1467 Return code handling translates as follows::
1468
1469 pipe = os.popen(cmd, 'w')
1470 ...
1471 rc = pipe.close()
1472 if rc is not None and rc >> 8:
1473 print("There were some errors")
1474 ==>
1475 process = Popen(cmd, stdin=PIPE)
1476 ...
1477 process.stdin.close()
1478 if process.wait() != 0:
1479 print("There were some errors")
1480
1481
1482 Legacy Shell Invocation Functions
1483 ---------------------------------
1484
1485 This module also provides the following legacy functions from the 2.x
1486 ``commands`` module. These operations implicitly invoke the system shell and
1487 none of the guarantees described above regarding security and exception
1488 handling consistency are valid for these functions.
1489
1490 .. function:: getstatusoutput(cmd, *, encoding=None, errors=None)
1491
1492 Return ``(exitcode, output)`` of executing *cmd* in a shell.
1493
1494 Execute the string *cmd* in a shell with :func:`check_output` and
1495 return a 2-tuple ``(exitcode, output)``.
1496 *encoding* and *errors* are used to decode output;
1497 see the notes on :ref:`frequently-used-arguments` for more details.
1498
1499 A trailing newline is stripped from the output.
1500 The exit code for the command can be interpreted as the return code
1501 of subprocess. Example::
1502
1503 >>> subprocess.getstatusoutput('ls /bin/ls')
1504 (0, '/bin/ls')
1505 >>> subprocess.getstatusoutput('cat /bin/junk')
1506 (1, 'cat: /bin/junk: No such file or directory')
1507 >>> subprocess.getstatusoutput('/bin/junk')
1508 (127, 'sh: /bin/junk: not found')
1509 >>> subprocess.getstatusoutput('/bin/kill $$')
1510 (-15, '')
1511
1512 .. availability:: Unix, Windows.
1513
1514 .. versionchanged:: 3.3.4
1515 Windows support was added.
1516
1517 The function now returns (exitcode, output) instead of (status, output)
1518 as it did in Python 3.3.3 and earlier. exitcode has the same value as
1519 :attr:`~Popen.returncode`.
1520
1521 .. versionchanged:: 3.11
1522 Added the *encoding* and *errors* parameters.
1523
1524 .. function:: getoutput(cmd, *, encoding=None, errors=None)
1525
1526 Return output (stdout and stderr) of executing *cmd* in a shell.
1527
1528 Like :func:`getstatusoutput`, except the exit code is ignored and the return
1529 value is a string containing the command's output. Example::
1530
1531 >>> subprocess.getoutput('ls /bin/ls')
1532 '/bin/ls'
1533
1534 .. availability:: Unix, Windows.
1535
1536 .. versionchanged:: 3.3.4
1537 Windows support added
1538
1539 .. versionchanged:: 3.11
1540 Added the *encoding* and *errors* parameters.
1541
1542
1543 Notes
1544 -----
1545
1546 .. _subprocess-timeout-behavior:
1547
1548 Timeout Behavior
1549 ^^^^^^^^^^^^^^^^
1550
1551 When using the ``timeout`` parameter in functions like :func:`run`,
1552 :meth:`Popen.wait`, or :meth:`Popen.communicate`,
1553 users should be aware of the following behaviors:
1554
1555 1. **Process Creation Delay**: The initial process creation itself cannot be interrupted
1556 on many platform APIs. This means that even when specifying a timeout, you are not
1557 guaranteed to see a timeout exception until at least after however long process
1558 creation takes.
1559
1560 2. **Extremely Small Timeout Values**: Setting very small timeout values (such as a few
1561 milliseconds) may result in almost immediate :exc:`TimeoutExpired` exceptions because
1562 process creation and system scheduling inherently require time.
1563
1564 .. _converting-argument-sequence:
1565
1566 Converting an argument sequence to a string on Windows
1567 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
1568
1569 On Windows, an *args* sequence is converted to a string that can be parsed
1570 using the following rules (which correspond to the rules used by the MS C
1571 runtime):
1572
1573 1. Arguments are delimited by white space, which is either a
1574 space or a tab.
1575
1576 2. A string surrounded by double quotation marks is
1577 interpreted as a single argument, regardless of white space
1578 contained within. A quoted string can be embedded in an
1579 argument.
1580
1581 3. A double quotation mark preceded by a backslash is
1582 interpreted as a literal double quotation mark.
1583
1584 4. Backslashes are interpreted literally, unless they
1585 immediately precede a double quotation mark.
1586
1587 5. If backslashes immediately precede a double quotation mark,
1588 every pair of backslashes is interpreted as a literal
1589 backslash. If the number of backslashes is odd, the last
1590 backslash escapes the next double quotation mark as
1591 described in rule 3.
1592
1593
1594 .. seealso::
1595
1596 :mod:`shlex`
1597 Module which provides function to parse and escape command lines.
1598
1599
1600 .. _disable_posix_spawn:
1601
1602 Disable use of ``posix_spawn()``
1603 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
1604
1605 On Linux, :mod:`!subprocess` defaults to using the ``vfork()`` system call
1606 internally when it is safe to do so rather than ``fork()``. This greatly
1607 improves performance.
1608
1609 ::
1610
1611 subprocess._USE_POSIX_SPAWN = False # See CPython issue gh-NNNNNN.
1612
1613 It is safe to set this to false on any Python version. It will have no
1614 effect on older or newer versions where unsupported. Do not assume the attribute
1615 is available to read. Despite the name, a true value does not indicate the
1616 corresponding function will be used, only that it may be.
1617
1618 Please file issues any time you have to use these private knobs with a way to
1619 reproduce the issue you were seeing. Link to that issue from a comment in your
1620 code.
1621
1622 .. versionadded:: 3.8 ``_USE_POSIX_SPAWN``