CINXE.COM

<!DOCTYPE html> <html lang="en"> <head> <meta charset="utf-8"> <meta name="viewport" content="width=device-width, initial-scale=1.0"> <meta name="color-scheme" content="light dark"> <title>PEP 324 – subprocess - New process module | peps.python.org</title> <link rel="shortcut icon" href="../_static/py.png"> <link rel="canonical" href="https://peps.python.org/pep-0324/"> <link rel="stylesheet" href="../_static/style.css" type="text/css"> <link rel="stylesheet" href="../_static/mq.css" type="text/css"> <link rel="stylesheet" href="../_static/pygments.css" type="text/css" media="(prefers-color-scheme: light)" id="pyg-light"> <link rel="stylesheet" href="../_static/pygments_dark.css" type="text/css" media="(prefers-color-scheme: dark)" id="pyg-dark"> <link rel="alternate" type="application/rss+xml" title="Latest PEPs" href="https://peps.python.org/peps.rss"> <meta property="og:title" content='PEP 324 – subprocess - New process module | peps.python.org'> <meta property="og:description" content="This PEP describes a new module for starting and communicating with processes."> <meta property="og:type" content="website"> <meta property="og:url" content="https://peps.python.org/pep-0324/"> <meta property="og:site_name" content="Python Enhancement Proposals (PEPs)"> <meta property="og:image" content="https://peps.python.org/_static/og-image.png"> <meta property="og:image:alt" content="Python PEPs"> <meta property="og:image:width" content="200"> <meta property="og:image:height" content="200"> <meta name="description" content="This PEP describes a new module for starting and communicating with processes."> <meta name="theme-color" content="#3776ab"> </head> <body> <svg xmlns="http://www.w3.org/2000/svg" style="display: none;"> <symbol id="svg-sun-half" viewBox="0 0 24 24" pointer-events="all"> <title>Following system colour scheme</title> <svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"> <circle cx="12" cy="12" r="9"></circle> <path d="M12 3v18m0-12l4.65-4.65M12 14.3l7.37-7.37M12 19.6l8.85-8.85"></path> </svg> </symbol> <symbol id="svg-moon" viewBox="0 0 24 24" pointer-events="all"> <title>Selected dark colour scheme</title> <svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"> <path stroke="none" d="M0 0h24v24H0z" fill="none"></path> <path d="M12 3c.132 0 .263 0 .393 0a7.5 7.5 0 0 0 7.92 12.446a9 9 0 1 1 -8.313 -12.454z"></path> </svg> </symbol> <symbol id="svg-sun" viewBox="0 0 24 24" pointer-events="all"> <title>Selected light colour scheme</title> <svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"> <circle cx="12" cy="12" r="5"></circle> <line x1="12" y1="1" x2="12" y2="3"></line> <line x1="12" y1="21" x2="12" y2="23"></line> <line x1="4.22" y1="4.22" x2="5.64" y2="5.64"></line> <line x1="18.36" y1="18.36" x2="19.78" y2="19.78"></line> <line x1="1" y1="12" x2="3" y2="12"></line> <line x1="21" y1="12" x2="23" y2="12"></line> <line x1="4.22" y1="19.78" x2="5.64" y2="18.36"></line> <line x1="18.36" y1="5.64" x2="19.78" y2="4.22"></line> </svg> </symbol> </svg> <script> document.documentElement.dataset.colour_scheme = localStorage.getItem("colour_scheme") || "auto" </script> <section id="pep-page-section"> <header> <h1>Python Enhancement Proposals</h1> <ul class="breadcrumbs"> <li><a href="https://www.python.org/" title="The Python Programming Language">Python</a> » </li> <li><a href="../pep-0000/">PEP Index</a> » </li> <li>PEP 324</li> </ul> <button id="colour-scheme-cycler" onClick="setColourScheme(nextColourScheme())"> <svg aria-hidden="true" class="colour-scheme-icon-when-auto"><use href="#svg-sun-half"></use></svg> <svg aria-hidden="true" class="colour-scheme-icon-when-dark"><use href="#svg-moon"></use></svg> <svg aria-hidden="true" class="colour-scheme-icon-when-light"><use href="#svg-sun"></use></svg> Toggle light / dark / auto colour theme </button> </header> <article> <section id="pep-content"> <h1 class="page-title">PEP 324 – subprocess - New process module</h1> <dl class="rfc2822 field-list simple"> <dt class="field-odd">Author:</dt> <dd class="field-odd">Peter Astrand <astrand at lysator.liu.se></dd> <dt class="field-even">Status:</dt> <dd class="field-even"><abbr title="Accepted and implementation complete, or no longer active">Final</abbr></dd> <dt class="field-odd">Type:</dt> <dd class="field-odd"><abbr title="Normative PEP with a new feature for Python, implementation change for CPython or interoperability standard for the ecosystem">Standards Track</abbr></dd> <dt class="field-even">Created:</dt> <dd class="field-even">19-Nov-2003</dd> <dt class="field-odd">Python-Version:</dt> <dd class="field-odd">2.4</dd> <dt class="field-even">Post-History:</dt> <dd class="field-even"></dd> </dl> <hr class="docutils" /> <section id="contents"> <details><summary>Table of Contents</summary><ul class="simple"> <li><a class="reference internal" href="#abstract">Abstract</a></li> <li><a class="reference internal" href="#motivation">Motivation</a></li> <li><a class="reference internal" href="#rationale">Rationale</a></li> <li><a class="reference internal" href="#specification">Specification</a><ul> <li><a class="reference internal" href="#exceptions">Exceptions</a></li> <li><a class="reference internal" href="#security">Security</a></li> <li><a class="reference internal" href="#popen-objects">Popen objects</a></li> </ul> </li> <li><a class="reference internal" href="#replacing-older-functions-with-the-subprocess-module">Replacing older functions with the subprocess module</a><ul> <li><a class="reference internal" href="#replacing-bin-sh-shell-backquote">Replacing /bin/sh shell backquote</a></li> <li><a class="reference internal" href="#replacing-shell-pipe-line">Replacing shell pipe line</a></li> <li><a class="reference internal" href="#replacing-os-system">Replacing <code class="docutils literal notranslate">os.system()</code></a></li> <li><a class="reference internal" href="#replacing-os-spawn">Replacing <code class="docutils literal notranslate">os.spawn*</code></a></li> <li><a class="reference internal" href="#replacing-os-popen">Replacing <code class="docutils literal notranslate">os.popen*</code></a></li> <li><a class="reference internal" href="#replacing-popen2">Replacing <code class="docutils literal notranslate">popen2.*</code></a></li> </ul> </li> <li><a class="reference internal" href="#open-issues">Open Issues</a></li> <li><a class="reference internal" href="#backwards-compatibility">Backwards Compatibility</a></li> <li><a class="reference internal" href="#reference-implementation">Reference Implementation</a></li> <li><a class="reference internal" href="#references">References</a></li> <li><a class="reference internal" href="#copyright">Copyright</a></li> </ul> </details></section> <section id="abstract"> <h2><a class="toc-backref" href="#abstract" role="doc-backlink">Abstract</a></h2> This PEP describes a new module for starting and communicating with processes. </section> <section id="motivation"> <h2><a class="toc-backref" href="#motivation" role="doc-backlink">Motivation</a></h2> Starting new processes is a common task in any programming language, and very common in a high-level language like Python. Good support for this task is needed, because: <ul class="simple"> <li>Inappropriate functions for starting processes could mean a security risk: If the program is started through the shell, and the arguments contain shell meta characters, the result can be disastrous. <a class="footnote-reference brackets" href="#id7" id="id1">[1]</a></li> <li>It makes Python an even better replacement language for over-complicated shell scripts.</li> </ul> Currently, Python has a large number of different functions for process creation. This makes it hard for developers to choose. The subprocess module provides the following enhancements over previous functions: <ul class="simple"> <li>One “unified” module provides all functionality from previous functions.</li> <li>Cross-process exceptions: Exceptions happening in the child before the new process has started to execute are re-raised in the parent. This means that it’s easy to handle <code class="docutils literal notranslate">exec()</code> failures, for example. With popen2, for example, it’s impossible to detect if the execution failed.</li> <li>A hook for executing custom code between fork and exec. This can be used for, for example, changing uid.</li> <li>No implicit call of /bin/sh. This means that there is no need for escaping dangerous shell meta characters.</li> <li>All combinations of file descriptor redirection is possible. For example, the “python-dialog” <a class="footnote-reference brackets" href="#id8" id="id2">[2]</a> needs to spawn a process and redirect stderr, but not stdout. This is not possible with current functions, without using temporary files.</li> <li>With the subprocess module, it’s possible to control if all open file descriptors should be closed before the new program is executed.</li> <li>Support for connecting several subprocesses (shell “pipe”).</li> <li>Universal newline support.</li> <li>A <code class="docutils literal notranslate">communicate()</code> method, which makes it easy to send stdin data and read stdout and stderr data, without risking deadlocks. Most people are aware of the flow control issues involved with child process communication, but not all have the patience or skills to write a fully correct and deadlock-free select loop. This means that many Python applications contain race conditions. A <code class="docutils literal notranslate">communicate()</code> method in the standard library solves this problem.</li> </ul> </section> <section id="rationale"> <h2><a class="toc-backref" href="#rationale" role="doc-backlink">Rationale</a></h2> The following points summarizes the design: <ul> <li>subprocess was based on popen2, which is tried-and-tested.</li> <li>The factory functions in popen2 have been removed, because I consider the class constructor equally easy to work with.</li> <li>popen2 contains several factory functions and classes for different combinations of redirection. subprocess, however, contains one single class. Since the subprocess module supports 12 different combinations of redirection, providing a class or function for each of them would be cumbersome and not very intuitive. Even with popen2, this is a readability problem. For example, many people cannot tell the difference between popen2.popen2 and popen2.popen4 without using the documentation.</li> <li>One small utility function is provided: <code class="docutils literal notranslate">subprocess.call()</code>. It aims to be an enhancement over <code class="docutils literal notranslate">os.system()</code>, while still very easy to use:<ul class="simple"> <li>It does not use the Standard C function system(), which has limitations.</li> <li>It does not call the shell implicitly.</li> <li>No need for quoting; using an argument list.</li> <li>The return value is easier to work with.</li> </ul> The <code class="docutils literal notranslate">call()</code> utility function accepts an ‘args’ argument, just like the <code class="docutils literal notranslate">Popen</code> class constructor. It waits for the command to complete, then returns the <code class="docutils literal notranslate">returncode</code> attribute. The implementation is very simple: <div class="highlight-default notranslate"><div class="highlight"><pre>def call(*args, **kwargs): return Popen(*args, **kwargs).wait() </pre></div> </div> The motivation behind the <code class="docutils literal notranslate">call()</code> function is simple: Starting a process and wait for it to finish is a common task. While <code class="docutils literal notranslate">Popen</code> supports a wide range of options, many users have simple needs. Many people are using <code class="docutils literal notranslate">os.system()</code> today, mainly because it provides a simple interface. Consider this example: <div class="highlight-default notranslate"><div class="highlight"><pre>os.system("stty sane -F " + device) </pre></div> </div> With <code class="docutils literal notranslate">subprocess.call()</code>, this would look like: <div class="highlight-default notranslate"><div class="highlight"><pre>subprocess.call(["stty", "sane", "-F", device]) </pre></div> </div> or, if executing through the shell: <div class="highlight-default notranslate"><div class="highlight"><pre>subprocess.call("stty sane -F " + device, shell=True) </pre></div> </div> </li> <li>The “preexec” functionality makes it possible to run arbitrary code between fork and exec. One might ask why there are special arguments for setting the environment and current directory, but not for, for example, setting the uid. The answer is:<ul class="simple"> <li>Changing environment and working directory is considered fairly common.</li> <li>Old functions like <code class="docutils literal notranslate">spawn()</code> has support for an “env”-argument.</li> <li>env and cwd are considered quite cross-platform: They make sense even on Windows.</li> </ul> </li> <li>On POSIX platforms, no extension module is required: the module uses <code class="docutils literal notranslate">os.fork()</code>, <code class="docutils literal notranslate">os.execvp()</code> etc.</li> <li>On Windows platforms, the module requires either Mark Hammond’s Windows extensions <a class="footnote-reference brackets" href="#id11" id="id3">[5]</a>, or a small extension module called _subprocess.</li> </ul> </section> <section id="specification"> <h2><a class="toc-backref" href="#specification" role="doc-backlink">Specification</a></h2> This module defines one class called Popen: <div class="highlight-default notranslate"><div class="highlight"><pre>class Popen(args, bufsize=0, executable=None, stdin=None, stdout=None, stderr=None, preexec_fn=None, close_fds=False, shell=False, cwd=None, env=None, universal_newlines=False, startupinfo=None, creationflags=0): </pre></div> </div> Arguments are: <ul> <li><code class="docutils literal notranslate">args</code> should be a string, or a sequence of program arguments. The program to execute is normally the first item in the args sequence or string, but can be explicitly set by using the executable argument.On UNIX, with <code class="docutils literal notranslate">shell=False</code> (default): In this case, the <code class="docutils literal notranslate">Popen</code> class uses <code class="docutils literal notranslate">os.execvp()</code> to execute the child program. <code class="docutils literal notranslate">args</code> should normally be a sequence. A string will be treated as a sequence with the string as the only item (the program to execute). On UNIX, with <code class="docutils literal notranslate">shell=True</code>: If <code class="docutils literal notranslate">args</code> is a string, it specifies the command string to execute through the shell. If <code class="docutils literal notranslate">args</code> is a sequence, the first item specifies the command string, and any additional items will be treated as additional shell arguments. On Windows: the <code class="docutils literal notranslate">Popen</code> class uses <code class="docutils literal notranslate">CreateProcess()</code> to execute the child program, which operates on strings. If <code class="docutils literal notranslate">args</code> is a sequence, it will be converted to a string using the <code class="docutils literal notranslate">list2cmdline</code> method. Please note that not all MS Windows applications interpret the command line the same way: The <code class="docutils literal notranslate">list2cmdline</code> is designed for applications using the same rules as the MS C runtime. </li> <li><code class="docutils literal notranslate">bufsize</code>, if given, has the same meaning as the corresponding argument to the built-in <code class="docutils literal notranslate">open()</code> function: 0 means unbuffered, 1 means line buffered, any other positive value means use a buffer of (approximately) that size. A negative <code class="docutils literal notranslate">bufsize</code> means to use the system default, which usually means fully buffered. The default value for <code class="docutils literal notranslate">bufsize</code> is 0 (unbuffered).</li> <li><code class="docutils literal notranslate">stdin</code>, <code class="docutils literal notranslate">stdout</code> and <code class="docutils literal notranslate">stderr</code> specify the executed programs’ standard input, standard output and standard error file handles, respectively. Valid values are <code class="docutils literal notranslate">PIPE</code>, an existing file descriptor (a positive integer), an existing file object, and <code class="docutils literal notranslate">None</code>. <code class="docutils literal notranslate">PIPE</code> indicates that a new pipe to the child should be created. With <code class="docutils literal notranslate">None</code>, no redirection will occur; the child’s file handles will be inherited from the parent. Additionally, <code class="docutils literal notranslate">stderr</code> can be STDOUT, which indicates that the stderr data from the applications should be captured into the same file handle as for stdout.</li> <li>If <code class="docutils literal notranslate">preexec_fn</code> is set to a callable object, this object will be called in the child process just before the child is executed.</li> <li>If <code class="docutils literal notranslate">close_fds</code> is true, all file descriptors except 0, 1 and 2 will be closed before the child process is executed.</li> <li>If <code class="docutils literal notranslate">shell</code> is true, the specified command will be executed through the shell.</li> <li>If <code class="docutils literal notranslate">cwd</code> is not <code class="docutils literal notranslate">None</code>, the current directory will be changed to cwd before the child is executed.</li> <li>If <code class="docutils literal notranslate">env</code> is not <code class="docutils literal notranslate">None</code>, it defines the environment variables for the new process.</li> <li>If <code class="docutils literal notranslate">universal_newlines</code> is true, the file objects stdout and stderr are opened as a text file, but lines may be terminated by any of <code class="docutils literal notranslate">\n</code>, the Unix end-of-line convention, <code class="docutils literal notranslate">\r</code>, the Macintosh convention or <code class="docutils literal notranslate">\r\n</code>, the Windows convention. All of these external representations are seen as <code class="docutils literal notranslate">\n</code> by the Python program. Note: This feature is only available if Python is built with universal newline support (the default). Also, the newlines attribute of the file objects stdout, stdin and stderr are not updated by the <code class="docutils literal notranslate">communicate()</code> method.</li> <li>The <code class="docutils literal notranslate">startupinfo</code> and <code class="docutils literal notranslate">creationflags</code>, if given, will be passed to the underlying <code class="docutils literal notranslate">CreateProcess()</code> function. They can specify things such as appearance of the main window and priority for the new process. (Windows only)</li> </ul> This module also defines two shortcut functions: <ul> <li><dl> <dt><code class="docutils literal notranslate">call(*args, **kwargs)</code>:</dt><dd>Run command with arguments. Wait for command to complete, then return the <code class="docutils literal notranslate">returncode</code> attribute.The arguments are the same as for the Popen constructor. Example: <div class="highlight-default notranslate"><div class="highlight"><pre>retcode = call(["ls", "-l"]) </pre></div> </div> </dd> </dl> </li> </ul> <section id="exceptions"> <h3><a class="toc-backref" href="#exceptions" role="doc-backlink">Exceptions</a></h3> Exceptions raised in the child process, before the new program has started to execute, will be re-raised in the parent. Additionally, the exception object will have one extra attribute called ‘child_traceback’, which is a string containing traceback information from the child’s point of view. The most common exception raised is <code class="docutils literal notranslate">OSError</code>. This occurs, for example, when trying to execute a non-existent file. Applications should prepare for <code class="docutils literal notranslate">OSErrors</code>. A <code class="docutils literal notranslate">ValueError</code> will be raised if Popen is called with invalid arguments. </section> <section id="security"> <h3><a class="toc-backref" href="#security" role="doc-backlink">Security</a></h3> Unlike some other popen functions, this implementation will never call /bin/sh implicitly. This means that all characters, including shell meta-characters, can safely be passed to child processes. </section> <section id="popen-objects"> <h3><a class="toc-backref" href="#popen-objects" role="doc-backlink">Popen objects</a></h3> Instances of the Popen class have the following methods: <dl> <dt><code class="docutils literal notranslate">poll()</code></dt><dd>Check if child process has terminated. Returns <code class="docutils literal notranslate">returncode</code> attribute.</dd> <dt><code class="docutils literal notranslate">wait()</code></dt><dd>Wait for child process to terminate. Returns <code class="docutils literal notranslate">returncode</code> attribute.</dd> <dt><code class="docutils literal notranslate">communicate(input=None)</code></dt><dd>Interact with process: Send data to stdin. Read data from stdout and stderr, until end-of-file is reached. Wait for process to terminate. The optional stdin argument should be a string to be sent to the child process, or <code class="docutils literal notranslate">None</code>, if no data should be sent to the child.<code class="docutils literal notranslate">communicate()</code> returns a tuple <code class="docutils literal notranslate">(stdout, stderr)</code>. Note: The data read is buffered in memory, so do not use this method if the data size is large or unlimited. </dd> </dl> The following attributes are also available: <dl class="simple"> <dt><code class="docutils literal notranslate">stdin</code></dt><dd>If the <code class="docutils literal notranslate">stdin</code> argument is <code class="docutils literal notranslate">PIPE</code>, this attribute is a file object that provides input to the child process. Otherwise, it is <code class="docutils literal notranslate">None</code>.</dd> <dt><code class="docutils literal notranslate">stdout</code></dt><dd>If the <code class="docutils literal notranslate">stdout</code> argument is <code class="docutils literal notranslate">PIPE</code>, this attribute is a file object that provides output from the child process. Otherwise, it is <code class="docutils literal notranslate">None</code>.</dd> <dt><code class="docutils literal notranslate">stderr</code></dt><dd>If the <code class="docutils literal notranslate">stderr</code> argument is <code class="docutils literal notranslate">PIPE</code>, this attribute is file object that provides error output from the child process. Otherwise, it is <code class="docutils literal notranslate">None</code>.</dd> <dt><code class="docutils literal notranslate">pid</code></dt><dd>The process ID of the child process.</dd> <dt><code class="docutils literal notranslate">returncode</code></dt><dd>The child return code. A <code class="docutils literal notranslate">None</code> value indicates that the process hasn’t terminated yet. A negative value -N indicates that the child was terminated by signal N (UNIX only).</dd> </dl> </section> </section> <section id="replacing-older-functions-with-the-subprocess-module"> <h2><a class="toc-backref" href="#replacing-older-functions-with-the-subprocess-module" role="doc-backlink">Replacing older functions with the subprocess module</a></h2> In this section, “a ==> b” means that b can be used as a replacement for a. Note: All functions in this section fail (more or less) silently if the executed program cannot be found; this module raises an OSError exception. In the following examples, we assume that the subprocess module is imported with <code class="docutils literal notranslate">from subprocess import *</code>. <section id="replacing-bin-sh-shell-backquote"> <h3><a class="toc-backref" href="#replacing-bin-sh-shell-backquote" role="doc-backlink">Replacing /bin/sh shell backquote</a></h3> <div class="highlight-default notranslate"><div class="highlight"><pre>output=`mycmd myarg` ==> output = Popen(["mycmd", "myarg"], stdout=PIPE).communicate()[0] </pre></div> </div> </section> <section id="replacing-shell-pipe-line"> <h3><a class="toc-backref" href="#replacing-shell-pipe-line" role="doc-backlink">Replacing shell pipe line</a></h3> <div class="highlight-default notranslate"><div class="highlight"><pre>output=`dmesg | grep hda` ==> p1 = Popen(["dmesg"], stdout=PIPE) p2 = Popen(["grep", "hda"], stdin=p1.stdout, stdout=PIPE) output = p2.communicate()[0] </pre></div> </div> </section> <section id="replacing-os-system"> <h3><a class="toc-backref" href="#replacing-os-system" role="doc-backlink">Replacing <code class="docutils literal notranslate">os.system()</code></a></h3> <div class="highlight-default notranslate"><div class="highlight"><pre>sts = os.system("mycmd" + " myarg") ==> p = Popen("mycmd" + " myarg", shell=True) sts = os.waitpid(p.pid, 0) </pre></div> </div> Note: <ul class="simple"> <li>Calling the program through the shell is usually not required.</li> <li>It’s easier to look at the returncode attribute than the exit status.</li> </ul> A more real-world example would look like this: <div class="highlight-default notranslate"><div class="highlight"><pre>try: retcode = call("mycmd" + " myarg", shell=True) if retcode < 0: print >>sys.stderr, "Child was terminated by signal", -retcode else: print >>sys.stderr, "Child returned", retcode except OSError, e: print >>sys.stderr, "Execution failed:", e </pre></div> </div> </section> <section id="replacing-os-spawn"> <h3><a class="toc-backref" href="#replacing-os-spawn" role="doc-backlink">Replacing <code class="docutils literal notranslate">os.spawn*</code></a></h3> P_NOWAIT example: <div class="highlight-default notranslate"><div class="highlight"><pre>pid = os.spawnlp(os.P_NOWAIT, "/bin/mycmd", "mycmd", "myarg") ==> pid = Popen(["/bin/mycmd", "myarg"]).pid </pre></div> </div> P_WAIT example: <div class="highlight-default notranslate"><div class="highlight"><pre>retcode = os.spawnlp(os.P_WAIT, "/bin/mycmd", "mycmd", "myarg") ==> retcode = call(["/bin/mycmd", "myarg"]) </pre></div> </div> Vector example: <div class="highlight-default notranslate"><div class="highlight"><pre>os.spawnvp(os.P_NOWAIT, path, args) ==> Popen([path] + args[1:]) </pre></div> </div> Environment example: <div class="highlight-default notranslate"><div class="highlight"><pre>os.spawnlpe(os.P_NOWAIT, "/bin/mycmd", "mycmd", "myarg", env) ==> Popen(["/bin/mycmd", "myarg"], env={"PATH": "/usr/bin"}) </pre></div> </div> </section> <section id="replacing-os-popen"> <h3><a class="toc-backref" href="#replacing-os-popen" role="doc-backlink">Replacing <code class="docutils literal notranslate">os.popen*</code></a></h3> <div class="highlight-default notranslate"><div class="highlight"><pre>pipe = os.popen(cmd, mode='r', bufsize) ==> pipe = Popen(cmd, shell=True, bufsize=bufsize, stdout=PIPE).stdout pipe = os.popen(cmd, mode='w', bufsize) ==> pipe = Popen(cmd, shell=True, bufsize=bufsize, stdin=PIPE).stdin (child_stdin, child_stdout) = os.popen2(cmd, mode, bufsize) ==> p = Popen(cmd, shell=True, bufsize=bufsize, stdin=PIPE, stdout=PIPE, close_fds=True) (child_stdin, child_stdout) = (p.stdin, p.stdout) (child_stdin, child_stdout, child_stderr) = os.popen3(cmd, mode, bufsize) ==> p = Popen(cmd, shell=True, bufsize=bufsize, stdin=PIPE, stdout=PIPE, stderr=PIPE, close_fds=True) (child_stdin, child_stdout, child_stderr) = (p.stdin, p.stdout, p.stderr) (child_stdin, child_stdout_and_stderr) = os.popen4(cmd, mode, bufsize) ==> p = Popen(cmd, shell=True, bufsize=bufsize, stdin=PIPE, stdout=PIPE, stderr=STDOUT, close_fds=True) (child_stdin, child_stdout_and_stderr) = (p.stdin, p.stdout) </pre></div> </div> </section> <section id="replacing-popen2"> <h3><a class="toc-backref" href="#replacing-popen2" role="doc-backlink">Replacing <code class="docutils literal notranslate">popen2.*</code></a></h3> Note: If the cmd argument to <code class="docutils literal notranslate">popen2</code> functions is a string, the command is executed through /bin/sh. If it is a list, the command is directly executed. <div class="highlight-default notranslate"><div class="highlight"><pre>(child_stdout, child_stdin) = popen2.popen2("somestring", bufsize, mode) ==> p = Popen(["somestring"], shell=True, bufsize=bufsize stdin=PIPE, stdout=PIPE, close_fds=True) (child_stdout, child_stdin) = (p.stdout, p.stdin) (child_stdout, child_stdin) = popen2.popen2(["mycmd", "myarg"], bufsize, mode) ==> p = Popen(["mycmd", "myarg"], bufsize=bufsize, stdin=PIPE, stdout=PIPE, close_fds=True) (child_stdout, child_stdin) = (p.stdout, p.stdin) </pre></div> </div> The <code class="docutils literal notranslate">popen2.Popen3</code> and <code class="docutils literal notranslate">popen3.Popen4</code> basically works as <code class="docutils literal notranslate">subprocess.Popen</code>, except that: <ul class="simple"> <li><code class="docutils literal notranslate">subprocess.Popen</code> raises an exception if the execution fails</li> <li>the <code class="docutils literal notranslate">capturestderr</code> argument is replaced with the stderr argument.</li> <li><code class="docutils literal notranslate">stdin=PIPE</code> and <code class="docutils literal notranslate">stdout=PIPE</code> must be specified.</li> <li><code class="docutils literal notranslate">popen2</code> closes all file descriptors by default, but you have to specify <code class="docutils literal notranslate">close_fds=True</code> with <code class="docutils literal notranslate">subprocess.Popen</code>.</li> </ul> </section> </section> <section id="open-issues"> <h2><a class="toc-backref" href="#open-issues" role="doc-backlink">Open Issues</a></h2> Some features have been requested but is not yet implemented. This includes: <ul class="simple"> <li>Support for managing a whole flock of subprocesses</li> <li>Support for managing “daemon” processes</li> <li>Built-in method for killing subprocesses</li> </ul> While these are useful features, it’s expected that these can be added later without problems. <ul class="simple"> <li>expect-like functionality, including pty support.</li> </ul> pty support is highly platform-dependent, which is a problem. Also, there are already other modules that provide this kind of functionality <a class="footnote-reference brackets" href="#id12" id="id4">[6]</a>. </section> <section id="backwards-compatibility"> <h2><a class="toc-backref" href="#backwards-compatibility" role="doc-backlink">Backwards Compatibility</a></h2> Since this is a new module, no major backward compatible issues are expected. The module name “subprocess” might collide with other, previous modules <a class="footnote-reference brackets" href="#id9" id="id5">[3]</a> with the same name, but the name “subprocess” seems to be the best suggested name so far. The first name of this module was “popen5”, but this name was considered too unintuitive. For a while, the module was called “process”, but this name is already used by Trent Mick’s module <a class="footnote-reference brackets" href="#id10" id="id6">[4]</a>. The functions and modules that this new module is trying to replace (<code class="docutils literal notranslate">os.system</code>, <code class="docutils literal notranslate">os.spawn*</code>, <code class="docutils literal notranslate">os.popen*</code>, <code class="docutils literal notranslate">popen2.*</code>, <code class="docutils literal notranslate">commands.*</code>) are expected to be available in future Python versions for a long time, to preserve backwards compatibility. </section> <section id="reference-implementation"> <h2><a class="toc-backref" href="#reference-implementation" role="doc-backlink">Reference Implementation</a></h2> A reference implementation is available from <a class="reference external" href="http://www.lysator.liu.se/~astrand/popen5/">http://www.lysator.liu.se/~astrand/popen5/</a>. </section> <section id="references"> <h2><a class="toc-backref" href="#references" role="doc-backlink">References</a></h2> <aside class="footnote-list brackets"> <aside class="footnote brackets" id="id7" role="doc-footnote"> <dt class="label" id="id7">[<a href="#id1">1</a>]</dt> <dd>Secure Programming for Linux and Unix HOWTO, section 8.3. <a class="reference external" href="http://www.dwheeler.com/secure-programs/">http://www.dwheeler.com/secure-programs/</a></aside> <aside class="footnote brackets" id="id8" role="doc-footnote"> <dt class="label" id="id8">[<a href="#id2">2</a>]</dt> <dd>Python Dialog <a class="reference external" href="http://pythondialog.sourceforge.net/">http://pythondialog.sourceforge.net/</a></aside> <aside class="footnote brackets" id="id9" role="doc-footnote"> <dt class="label" id="id9">[<a href="#id5">3</a>]</dt> <dd><a class="reference external" href="http://www.iol.ie/~padraiga/libs/subProcess.py">http://www.iol.ie/~padraiga/libs/subProcess.py</a></aside> <aside class="footnote brackets" id="id10" role="doc-footnote"> <dt class="label" id="id10">[<a href="#id6">4</a>]</dt> <dd><a class="reference external" href="http://starship.python.net/crew/tmick/">http://starship.python.net/crew/tmick/</a></aside> <aside class="footnote brackets" id="id11" role="doc-footnote"> <dt class="label" id="id11">[<a href="#id3">5</a>]</dt> <dd><a class="reference external" href="http://starship.python.net/crew/mhammond/win32/">http://starship.python.net/crew/mhammond/win32/</a></aside> <aside class="footnote brackets" id="id12" role="doc-footnote"> <dt class="label" id="id12">[<a href="#id4">6</a>]</dt> <dd><a class="reference external" href="http://www.lysator.liu.se/~ceder/pcl-expect/">http://www.lysator.liu.se/~ceder/pcl-expect/</a></aside> </aside> </section> <section id="copyright"> <h2><a class="toc-backref" href="#copyright" role="doc-backlink">Copyright</a></h2> This document has been placed in the public domain. </section> </section> <hr class="docutils" /> Source: <a class="reference external" href="https://github.com/python/peps/blob/main/peps/pep-0324.rst">https://github.com/python/peps/blob/main/peps/pep-0324.rst</a> Last modified: <a class="reference external" href="https://github.com/python/peps/commits/main/peps/pep-0324.rst">2025-02-01 08:59:27 GMT</a> </article> <nav id="pep-sidebar"> <h2>Contents</h2> <ul> <li><a class="reference internal" href="#abstract">Abstract</a></li> <li><a class="reference internal" href="#motivation">Motivation</a></li> <li><a class="reference internal" href="#rationale">Rationale</a></li> <li><a class="reference internal" href="#specification">Specification</a><ul> <li><a class="reference internal" href="#exceptions">Exceptions</a></li> <li><a class="reference internal" href="#security">Security</a></li> <li><a class="reference internal" href="#popen-objects">Popen objects</a></li> </ul> </li> <li><a class="reference internal" href="#replacing-older-functions-with-the-subprocess-module">Replacing older functions with the subprocess module</a><ul> <li><a class="reference internal" href="#replacing-bin-sh-shell-backquote">Replacing /bin/sh shell backquote</a></li> <li><a class="reference internal" href="#replacing-shell-pipe-line">Replacing shell pipe line</a></li> <li><a class="reference internal" href="#replacing-os-system">Replacing <code class="docutils literal notranslate">os.system()</code></a></li> <li><a class="reference internal" href="#replacing-os-spawn">Replacing <code class="docutils literal notranslate">os.spawn*</code></a></li> <li><a class="reference internal" href="#replacing-os-popen">Replacing <code class="docutils literal notranslate">os.popen*</code></a></li> <li><a class="reference internal" href="#replacing-popen2">Replacing <code class="docutils literal notranslate">popen2.*</code></a></li> </ul> </li> <li><a class="reference internal" href="#open-issues">Open Issues</a></li> <li><a class="reference internal" href="#backwards-compatibility">Backwards Compatibility</a></li> <li><a class="reference internal" href="#reference-implementation">Reference Implementation</a></li> <li><a class="reference internal" href="#references">References</a></li> <li><a class="reference internal" href="#copyright">Copyright</a></li> </ul> <a id="source" href="https://github.com/python/peps/blob/main/peps/pep-0324.rst">Page Source (GitHub)</a> </nav> </section> <script src="../_static/colour_scheme.js"></script> <script src="../_static/wrap_tables.js"></script> <script src="../_static/sticky_banner.js"></script> </body> </html>