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