Team Ai
Apppublic

parthtamu/rag-code-assistant

sourceHugging Faceupdated 7mo agoView on Hugging Face
0likes
subprocess.html2039 linesDownload Raw Back to docs
1<!DOCTYPE html>2 3<html lang="en" data-content_root="../">4  <head>5    <meta charset="utf-8" />6    <meta name="viewport" content="width=device-width, initial-scale=1.0" /><meta name="viewport" content="width=device-width, initial-scale=1" />7<meta property="og:title" content="subprocess — Subprocess management" />8<meta property="og:type" content="website" />9<meta property="og:url" content="https://docs.python.org/3/library/subprocess.html" />10<meta property="og:site_name" content="Python documentation" />11<meta property="og:description" content="Source code: Lib/subprocess.py The subprocess module allows you to spawn new processes, connect to their input/output/error pipes, and obtain their return codes. This module intends to replace seve..." />12<meta property="og:image:width" content="1146" />13<meta property="og:image:height" content="600" />14<meta property="og:image" content="https://docs.python.org/3.15/_images/social_previews/summary_library_subprocess_8d367abf.png" />15<meta property="og:image:alt" content="Source code: Lib/subprocess.py The subprocess module allows you to spawn new processes, connect to their input/output/error pipes, and obtain their return codes. This module intends to replace seve..." />16<meta name="description" content="Source code: Lib/subprocess.py The subprocess module allows you to spawn new processes, connect to their input/output/error pipes, and obtain their return codes. This module intends to replace seve..." />17<meta name="twitter:card" content="summary_large_image" />18<meta name="theme-color" content="#3776ab">19 20    <title>subprocess — Subprocess management &#8212; Python 3.15.0a6 documentation</title><meta name="viewport" content="width=device-width, initial-scale=1.0">21    22    <link rel="stylesheet" type="text/css" href="../_static/pygments.css?v=b86133f3" />23    <link rel="stylesheet" type="text/css" href="../_static/classic.css?v=234b1a7c" />24    <link rel="stylesheet" type="text/css" href="../_static/pydoctheme.css?v=89a2f22a" />25    <link rel="stylesheet" type="text/css" href="../_static/profiling-sampling-visualization.css?v=0c2600ae" />26    <link id="pygments_dark_css" media="(prefers-color-scheme: dark)" rel="stylesheet" type="text/css" href="../_static/pygments_dark.css?v=5349f25f" />27    28    <script src="../_static/documentation_options.js?v=6b7c9ff5"></script>29    <script src="../_static/doctools.js?v=9bcbadda"></script>30    <script src="../_static/sphinx_highlight.js?v=dc90522c"></script>31    <script src="../_static/profiling-sampling-visualization.js?v=9811ed04"></script>32    33    <script src="../_static/sidebar.js"></script>34    35    <link rel="search" type="application/opensearchdescription+xml"36          title="Search within Python 3.15.0a6 documentation"37          href="../_static/opensearch.xml"/>38    <link rel="author" title="About these documents" href="../about.html" />39    <link rel="index" title="Index" href="../genindex.html" />40    <link rel="search" title="Search" href="../search.html" />41    <link rel="copyright" title="Copyright" href="../copyright.html" />42    <link rel="next" title="sched — Event scheduler" href="sched.html" />43    <link rel="prev" title="concurrent.interpreters — Multiple interpreters in the same process" href="concurrent.interpreters.html" />44    45      46      <script defer file-types="bz2,epub,zip" data-domain="docs.python.org" src="https://analytics.python.org/js/script.file-downloads.outbound-links.js"></script>47      48      <link rel="canonical" href="https://docs.python.org/3/library/subprocess.html">49      50    51 52    53    <style>54      @media only screen {55        table.full-width-table {56            width: 100%;57        }58      }59    </style>60<link rel="stylesheet" href="../_static/pydoctheme_dark.css" media="(prefers-color-scheme: dark)" id="pydoctheme_dark_css">61    <link rel="shortcut icon" type="image/png" href="../_static/py.svg">62            <script type="text/javascript" src="../_static/copybutton.js"></script>63            <script type="text/javascript" src="../_static/menu.js"></script>64            <script type="text/javascript" src="../_static/search-focus.js"></script>65            <script type="text/javascript" src="../_static/themetoggle.js"></script> 66            <script type="text/javascript" src="../_static/rtd_switcher.js"></script>67            <meta name="readthedocs-addons-api-version" content="1">68 69  </head>70<body>71<div class="mobile-nav">72    <input type="checkbox" id="menuToggler" class="toggler__input" aria-controls="navigation"73           aria-pressed="false" aria-expanded="false" role="button" aria-label="Menu">74    <nav class="nav-content" role="navigation">75        <label for="menuToggler" class="toggler__label">76            <span></span>77        </label>78        <span class="nav-items-wrapper">79            <a href="https://www.python.org/" class="nav-logo">80                <img src="../_static/py.svg" alt="Python logo">81            </a>82            <span class="version_switcher_placeholder"></span>83            <form role="search" class="search" action="../search.html" method="get">84                <svg xmlns="http://www.w3.org/2000/svg" width="20" height="20" viewBox="0 0 24 24" class="search-icon">85                    <path fill-rule="nonzero" fill="currentColor" d="M15.5 14h-.79l-.28-.27a6.5 6.5 0 001.48-5.34c-.47-2.78-2.79-5-5.59-5.34a6.505 6.505 0 00-7.27 7.27c.34 2.8 2.56 5.12 5.34 5.59a6.5 6.5 0 005.34-1.48l.27.28v.79l4.25 4.25c.41.41 1.08.41 1.49 0 .41-.41.41-1.08 0-1.49L15.5 14zm-6 0C7.01 14 5 11.99 5 9.5S7.01 5 9.5 5 14 7.01 14 9.5 11.99 14 9.5 14z"></path>86                </svg>87                <input placeholder="Quick search" aria-label="Quick search" type="search" name="q">88                <input type="submit" value="Go">89            </form>90        </span>91    </nav>92    <div class="menu-wrapper">93        <nav class="menu" role="navigation" aria-label="main navigation">94            <div class="language_switcher_placeholder"></div>95            96<label class="theme-selector-label">97    Theme98    <select class="theme-selector" oninput="activateTheme(this.value)">99        <option value="auto" selected>Auto</option>100        <option value="light">Light</option>101        <option value="dark">Dark</option>102    </select>103</label>104  <div>105    <h3><a href="../contents.html">Table of Contents</a></h3>106    <ul>107<li><a class="reference internal" href="#"><code class="xref py py-mod docutils literal notranslate"><span class="pre">subprocess</span></code> — Subprocess management</a><ul>108<li><a class="reference internal" href="#using-the-subprocess-module">Using the <code class="xref py py-mod docutils literal notranslate"><span class="pre">subprocess</span></code> Module</a><ul>109<li><a class="reference internal" href="#frequently-used-arguments">Frequently Used Arguments</a></li>110<li><a class="reference internal" href="#popen-constructor">Popen Constructor</a></li>111<li><a class="reference internal" href="#exceptions">Exceptions</a></li>112</ul>113</li>114<li><a class="reference internal" href="#security-considerations">Security Considerations</a></li>115<li><a class="reference internal" href="#popen-objects">Popen Objects</a></li>116<li><a class="reference internal" href="#windows-popen-helpers">Windows Popen Helpers</a><ul>117<li><a class="reference internal" href="#windows-constants">Windows Constants</a></li>118</ul>119</li>120<li><a class="reference internal" href="#older-high-level-api">Older high-level API</a></li>121<li><a class="reference internal" href="#replacing-older-functions-with-the-subprocess-module">Replacing Older Functions with the <code class="xref py py-mod docutils literal notranslate"><span class="pre">subprocess</span></code> Module</a><ul>122<li><a class="reference internal" href="#replacing-bin-sh-shell-command-substitution">Replacing <strong class="program">/bin/sh</strong> shell command substitution</a></li>123<li><a class="reference internal" href="#replacing-shell-pipeline">Replacing shell pipeline</a></li>124<li><a class="reference internal" href="#replacing-os-system">Replacing <code class="xref py py-func docutils literal notranslate"><span class="pre">os.system()</span></code></a></li>125<li><a class="reference internal" href="#replacing-the-os-spawn-family">Replacing the <code class="xref py py-func docutils literal notranslate"><span class="pre">os.spawn</span></code> family</a></li>126<li><a class="reference internal" href="#replacing-os-popen">Replacing <code class="xref py py-func docutils literal notranslate"><span class="pre">os.popen()</span></code></a></li>127</ul>128</li>129<li><a class="reference internal" href="#legacy-shell-invocation-functions">Legacy Shell Invocation Functions</a></li>130<li><a class="reference internal" href="#notes">Notes</a><ul>131<li><a class="reference internal" href="#timeout-behavior">Timeout Behavior</a></li>132<li><a class="reference internal" href="#converting-an-argument-sequence-to-a-string-on-windows">Converting an argument sequence to a string on Windows</a></li>133<li><a class="reference internal" href="#disable-use-of-posix-spawn">Disable use of <code class="docutils literal notranslate"><span class="pre">posix_spawn()</span></code></a></li>134</ul>135</li>136</ul>137</li>138</ul>139 140  </div>141  <div>142    <h4>Previous topic</h4>143    <p class="topless"><a href="concurrent.interpreters.html"144                          title="previous chapter"><code class="xref py py-mod docutils literal notranslate"><span class="pre">concurrent.interpreters</span></code> — Multiple interpreters in the same process</a></p>145  </div>146  <div>147    <h4>Next topic</h4>148    <p class="topless"><a href="sched.html"149                          title="next chapter"><code class="xref py py-mod docutils literal notranslate"><span class="pre">sched</span></code> — Event scheduler</a></p>150  </div>151  <script>152    document.addEventListener('DOMContentLoaded', () => {153        const title = document.querySelector('meta[property="og:title"]').content;154        const elements = document.querySelectorAll('.improvepage');155        const pageurl = window.location.href.split('?')[0];156        elements.forEach(element => {157            const url = new URL(element.href.split('?')[0].replace("-nojs", ""));158            url.searchParams.set('pagetitle', title);159            url.searchParams.set('pageurl', pageurl);160            url.searchParams.set('pagesource', "library/subprocess.rst");161            element.href = url.toString();162        });163    });164  </script>165  <div role="note" aria-label="source link">166    <h3>This page</h3>167    <ul class="this-page-menu">168      <li><a href="../bugs.html">Report a bug</a></li>169      <li><a class="improvepage" href="../improve-page-nojs.html">Improve this page</a></li>170      <li>171        <a href="https://github.com/python/cpython/blob/main/Doc/library/subprocess.rst?plain=1"172            rel="nofollow">Show source173        </a>174      </li>175      176    </ul>177  </div>178        </nav>179    </div>180</div>181 182  183    <div class="related" role="navigation" aria-label="Related">184      <h3>Navigation</h3>185      <ul>186        <li class="right" style="margin-right: 10px">187          <a href="../genindex.html" title="General Index"188             accesskey="I">index</a></li>189        <li class="right" >190          <a href="../py-modindex.html" title="Python Module Index"191             >modules</a> |</li>192        <li class="right" >193          <a href="sched.html" title="sched — Event scheduler"194             accesskey="N">next</a> |</li>195        <li class="right" >196          <a href="concurrent.interpreters.html" title="concurrent.interpreters — Multiple interpreters in the same process"197             accesskey="P">previous</a> |</li>198 199          <li><img src="../_static/py.svg" alt="Python logo" style="vertical-align: middle; margin-top: -1px"></li>200          <li><a href="https://www.python.org/">Python</a> &#187;</li>201          <li class="switchers">202            <div class="language_switcher_placeholder"></div>203            <div class="version_switcher_placeholder"></div>204          </li>205          <li>206              207          </li>208    <li id="cpython-language-and-version">209      <a href="../index.html">3.15.0a6 Documentation</a> &#187;210    </li>211 212          <li class="nav-item nav-item-1"><a href="index.html" >The Python Standard Library</a> &#187;</li>213          <li class="nav-item nav-item-2"><a href="concurrency.html" accesskey="U">Concurrent Execution</a> &#187;</li>214        <li class="nav-item nav-item-this"><a href=""><code class="xref py py-mod docutils literal notranslate"><span class="pre">subprocess</span></code> — Subprocess management</a></li>215                <li class="right">216                    217 218    <div class="inline-search" role="search">219        <form class="inline-search" action="../search.html" method="get">220          <input placeholder="Quick search" aria-label="Quick search" type="search" name="q" id="search-box">221          <input type="submit" value="Go">222        </form>223    </div>224                     |225                </li>226            <li class="right">227<label class="theme-selector-label">228    Theme229    <select class="theme-selector" oninput="activateTheme(this.value)">230        <option value="auto" selected>Auto</option>231        <option value="light">Light</option>232        <option value="dark">Dark</option>233    </select>234</label> |</li>235            236      </ul>237    </div>    238 239    <div class="document">240      <div class="documentwrapper">241        <div class="bodywrapper">242          <div class="body" role="main">243            244  <section id="module-subprocess">245<span id="subprocess-subprocess-management"></span><h1><code class="xref py py-mod docutils literal notranslate"><span class="pre">subprocess</span></code> — Subprocess management<a class="headerlink" href="#module-subprocess" title="Link to this heading">¶</a></h1>246<p><strong>Source code:</strong> <a class="extlink-source reference external" href="https://github.com/python/cpython/tree/main/Lib/subprocess.py">Lib/subprocess.py</a></p>247<hr class="docutils" />248<p>The <code class="xref py py-mod docutils literal notranslate"><span class="pre">subprocess</span></code> module allows you to spawn new processes, connect to their249input/output/error pipes, and obtain their return codes.  This module intends to250replace several older modules and functions:</p>251<div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="n">os</span><span class="o">.</span><span class="n">system</span>252<span class="n">os</span><span class="o">.</span><span class="n">spawn</span><span class="o">*</span>253</pre></div>254</div>255<p>Information about how the <code class="xref py py-mod docutils literal notranslate"><span class="pre">subprocess</span></code> module can be used to replace these256modules and functions can be found in the following sections.</p>257<div class="admonition seealso">258<p class="admonition-title">See also</p>259<p><span class="target" id="index-0"></span><a class="pep reference external" href="https://peps.python.org/pep-0324/"><strong>PEP 324</strong></a> – PEP proposing the subprocess module</p>260</div>261<div class="availability docutils container">262<p><a class="reference internal" href="intro.html#availability"><span class="std std-ref">Availability</span></a>: not Android, not iOS, not WASI.</p>263<p>This module is not supported on <a class="reference internal" href="intro.html#mobile-availability"><span class="std std-ref">mobile platforms</span></a>264or <a class="reference internal" href="intro.html#wasm-availability"><span class="std std-ref">WebAssembly platforms</span></a>.</p>265</div>266<section id="using-the-subprocess-module">267<h2>Using the <code class="xref py py-mod docutils literal notranslate"><span class="pre">subprocess</span></code> Module<a class="headerlink" href="#using-the-subprocess-module" title="Link to this heading">¶</a></h2>268<p>The recommended approach to invoking subprocesses is to use the <a class="reference internal" href="#subprocess.run" title="subprocess.run"><code class="xref py py-func docutils literal notranslate"><span class="pre">run()</span></code></a>269function for all use cases it can handle. For more advanced use cases, the270underlying <a class="reference internal" href="#subprocess.Popen" title="subprocess.Popen"><code class="xref py py-class docutils literal notranslate"><span class="pre">Popen</span></code></a> interface can be used directly.</p>271<dl class="py function">272<dt class="sig sig-object py" id="subprocess.run">273<span class="sig-prename descclassname"><span class="pre">subprocess.</span></span><span class="sig-name descname"><span class="pre">run</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">args</span></span></em>, <em class="sig-param"><span class="keyword-only-separator o"><abbr title="Keyword-only parameters separator (PEP 3102)"><span class="pre">*</span></abbr></span></em>, <em class="sig-param"><span class="n"><span class="pre">stdin</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">None</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">input</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">None</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">stdout</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">None</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">stderr</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">None</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">capture_output</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">False</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">shell</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">False</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">cwd</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">None</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">timeout</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">None</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">check</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">False</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">encoding</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">None</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">errors</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">None</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">text</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">None</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">env</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">None</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">universal_newlines</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">None</span></span></em>, <em class="sig-param"><span class="o"><span class="pre">**</span></span><span class="n"><span class="pre">other_popen_kwargs</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="#subprocess.run" title="Link to this definition">¶</a></dt>274<dd><p>Run the command described by <em>args</em>.  Wait for command to complete, then275return a <a class="reference internal" href="#subprocess.CompletedProcess" title="subprocess.CompletedProcess"><code class="xref py py-class docutils literal notranslate"><span class="pre">CompletedProcess</span></code></a> instance.</p>276<p>The arguments shown above are merely the most common ones, described below277in <a class="reference internal" href="#frequently-used-arguments"><span class="std std-ref">Frequently Used Arguments</span></a> (hence the use of keyword-only notation278in the abbreviated signature). The full function signature is largely the279same as that of the <a class="reference internal" href="#subprocess.Popen" title="subprocess.Popen"><code class="xref py py-class docutils literal notranslate"><span class="pre">Popen</span></code></a> constructor - most of the arguments to280this function are passed through to that interface. (<em>timeout</em>,  <em>input</em>,281<em>check</em>, and <em>capture_output</em> are not.)</p>282<p>If <em>capture_output</em> is true, stdout and stderr will be captured.283When used, the internal <a class="reference internal" href="#subprocess.Popen" title="subprocess.Popen"><code class="xref py py-class docutils literal notranslate"><span class="pre">Popen</span></code></a> object is automatically created with284<em>stdout</em> and <em>stderr</em> both set to <a class="reference internal" href="#subprocess.PIPE" title="subprocess.PIPE"><code class="xref py py-data docutils literal notranslate"><span class="pre">PIPE</span></code></a>.285The <em>stdout</em> and <em>stderr</em> arguments may not be supplied at the same time as <em>capture_output</em>.286If you wish to capture and combine both streams into one,287set <em>stdout</em> to <code class="xref py py-data docutils literal notranslate"><span class="pre">PIPE</span></code>288and <em>stderr</em> to <a class="reference internal" href="#subprocess.STDOUT" title="subprocess.STDOUT"><code class="xref py py-data docutils literal notranslate"><span class="pre">STDOUT</span></code></a>,289instead of using <em>capture_output</em>.</p>290<p>A <em>timeout</em> may be specified in seconds, it is internally passed on to291<a class="reference internal" href="#subprocess.Popen.communicate" title="subprocess.Popen.communicate"><code class="xref py py-meth docutils literal notranslate"><span class="pre">Popen.communicate()</span></code></a>. If the timeout expires, the child process will be292killed and waited for. The <a class="reference internal" href="#subprocess.TimeoutExpired" title="subprocess.TimeoutExpired"><code class="xref py py-exc docutils literal notranslate"><span class="pre">TimeoutExpired</span></code></a> exception will be293re-raised after the child process has terminated. The initial process294creation itself cannot be interrupted on many platform APIs so you are not295guaranteed to see a timeout exception until at least after however long296process creation takes.</p>297<p>The <em>input</em> argument is passed to <a class="reference internal" href="#subprocess.Popen.communicate" title="subprocess.Popen.communicate"><code class="xref py py-meth docutils literal notranslate"><span class="pre">Popen.communicate()</span></code></a> and thus to the298subprocess’s stdin.  If used it must be a byte sequence, or a string if299<em>encoding</em> or <em>errors</em> is specified or <em>text</em> is true.  When300used, the internal <a class="reference internal" href="#subprocess.Popen" title="subprocess.Popen"><code class="xref py py-class docutils literal notranslate"><span class="pre">Popen</span></code></a> object is automatically created with301<em>stdin</em> set to <a class="reference internal" href="#subprocess.PIPE" title="subprocess.PIPE"><code class="xref py py-data docutils literal notranslate"><span class="pre">PIPE</span></code></a>,302and the <em>stdin</em> argument may not be used as well.</p>303<p>If <em>check</em> is true, and the process exits with a non-zero exit code, a304<a class="reference internal" href="#subprocess.CalledProcessError" title="subprocess.CalledProcessError"><code class="xref py py-exc docutils literal notranslate"><span class="pre">CalledProcessError</span></code></a> exception will be raised. Attributes of that305exception hold the arguments, the exit code, and stdout and stderr if they306were captured.</p>307<p>If <em>encoding</em> or <em>errors</em> are specified, or <em>text</em> is true,308file objects for stdin, stdout and stderr are opened in text mode using the309specified <em>encoding</em> and <em>errors</em> or the <a class="reference internal" href="io.html#io.TextIOWrapper" title="io.TextIOWrapper"><code class="xref py py-class docutils literal notranslate"><span class="pre">io.TextIOWrapper</span></code></a> default.310The <em>universal_newlines</em> argument is equivalent  to <em>text</em> and is provided311for backwards compatibility. By default, file objects are opened in binary mode.</p>312<p>If <em>env</em> is not <code class="docutils literal notranslate"><span class="pre">None</span></code>, it must be a mapping that defines the environment313variables for the new process; these are used instead of the default314behavior of inheriting the current process’ environment. It is passed315directly to <a class="reference internal" href="#subprocess.Popen" title="subprocess.Popen"><code class="xref py py-class docutils literal notranslate"><span class="pre">Popen</span></code></a>. This mapping can be str to str on any platform316or bytes to bytes on POSIX platforms much like <a class="reference internal" href="os.html#os.environ" title="os.environ"><code class="xref py py-data docutils literal notranslate"><span class="pre">os.environ</span></code></a> or317<a class="reference internal" href="os.html#os.environb" title="os.environb"><code class="xref py py-data docutils literal notranslate"><span class="pre">os.environb</span></code></a>.</p>318<p>Examples:</p>319<div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="gp">&gt;&gt;&gt; </span><span class="n">subprocess</span><span class="o">.</span><span class="n">run</span><span class="p">([</span><span class="s2">&quot;ls&quot;</span><span class="p">,</span> <span class="s2">&quot;-l&quot;</span><span class="p">])</span>  <span class="c1"># doesn&#39;t capture output</span>320<span class="go">CompletedProcess(args=[&#39;ls&#39;, &#39;-l&#39;], returncode=0)</span>321 322<span class="gp">&gt;&gt;&gt; </span><span class="n">subprocess</span><span class="o">.</span><span class="n">run</span><span class="p">(</span><span class="s2">&quot;exit 1&quot;</span><span class="p">,</span> <span class="n">shell</span><span class="o">=</span><span class="kc">True</span><span class="p">,</span> <span class="n">check</span><span class="o">=</span><span class="kc">True</span><span class="p">)</span>323<span class="gt">Traceback (most recent call last):</span>324<span class="w">  </span><span class="c">...</span>325<span class="gr">subprocess.CalledProcessError</span>: <span class="n">Command &#39;exit 1&#39; returned non-zero exit status 1</span>326 327<span class="gp">&gt;&gt;&gt; </span><span class="n">subprocess</span><span class="o">.</span><span class="n">run</span><span class="p">([</span><span class="s2">&quot;ls&quot;</span><span class="p">,</span> <span class="s2">&quot;-l&quot;</span><span class="p">,</span> <span class="s2">&quot;/dev/null&quot;</span><span class="p">],</span> <span class="n">capture_output</span><span class="o">=</span><span class="kc">True</span><span class="p">)</span>328<span class="go">CompletedProcess(args=[&#39;ls&#39;, &#39;-l&#39;, &#39;/dev/null&#39;], returncode=0,</span>329<span class="go">stdout=b&#39;crw-rw-rw- 1 root root 1, 3 Jan 23 16:23 /dev/null\n&#39;, stderr=b&#39;&#39;)</span>330</pre></div>331</div>332<div class="versionadded">333<p><span class="versionmodified added">Added in version 3.5.</span></p>334</div>335<div class="versionchanged">336<p><span class="versionmodified changed">Changed in version 3.6: </span>Added <em>encoding</em> and <em>errors</em> parameters</p>337</div>338<div class="versionchanged">339<p><span class="versionmodified changed">Changed in version 3.7: </span>Added the <em>text</em> parameter, as a more understandable alias of <em>universal_newlines</em>.340Added the <em>capture_output</em> parameter.</p>341</div>342<div class="versionchanged">343<p><span class="versionmodified changed">Changed in version 3.12: </span>Changed Windows shell search order for <code class="docutils literal notranslate"><span class="pre">shell=True</span></code>. The current344directory and <code class="docutils literal notranslate"><span class="pre">%PATH%</span></code> are replaced with <code class="docutils literal notranslate"><span class="pre">%COMSPEC%</span></code> and345<code class="docutils literal notranslate"><span class="pre">%SystemRoot%\System32\cmd.exe</span></code>. As a result, dropping a346malicious program named <code class="docutils literal notranslate"><span class="pre">cmd.exe</span></code> into a current directory no347longer works.</p>348</div>349</dd></dl>350 351<dl class="py class">352<dt class="sig sig-object py" id="subprocess.CompletedProcess">353<em class="property"><span class="k"><span class="pre">class</span></span><span class="w"> </span></em><span class="sig-prename descclassname"><span class="pre">subprocess.</span></span><span class="sig-name descname"><span class="pre">CompletedProcess</span></span><a class="headerlink" href="#subprocess.CompletedProcess" title="Link to this definition">¶</a></dt>354<dd><p>The return value from <a class="reference internal" href="#subprocess.run" title="subprocess.run"><code class="xref py py-func docutils literal notranslate"><span class="pre">run()</span></code></a>, representing a process that has finished.</p>355<dl class="py attribute">356<dt class="sig sig-object py" id="subprocess.CompletedProcess.args">357<span class="sig-name descname"><span class="pre">args</span></span><a class="headerlink" href="#subprocess.CompletedProcess.args" title="Link to this definition">¶</a></dt>358<dd><p>The arguments used to launch the process. This may be a list or a string.</p>359</dd></dl>360 361<dl class="py attribute">362<dt class="sig sig-object py" id="subprocess.CompletedProcess.returncode">363<span class="sig-name descname"><span class="pre">returncode</span></span><a class="headerlink" href="#subprocess.CompletedProcess.returncode" title="Link to this definition">¶</a></dt>364<dd><p>Exit status of the child process. Typically, an exit status of 0 indicates365that it ran successfully.</p>366<p>A negative value <code class="docutils literal notranslate"><span class="pre">-N</span></code> indicates that the child was terminated by signal367<code class="docutils literal notranslate"><span class="pre">N</span></code> (POSIX only).</p>368</dd></dl>369 370<dl class="py attribute">371<dt class="sig sig-object py" id="subprocess.CompletedProcess.stdout">372<span class="sig-name descname"><span class="pre">stdout</span></span><a class="headerlink" href="#subprocess.CompletedProcess.stdout" title="Link to this definition">¶</a></dt>373<dd><p>Captured stdout from the child process. A bytes sequence, or a string if374<a class="reference internal" href="#subprocess.run" title="subprocess.run"><code class="xref py py-func docutils literal notranslate"><span class="pre">run()</span></code></a> was called with an encoding, errors, or text=True.375<code class="docutils literal notranslate"><span class="pre">None</span></code> if stdout was not captured.</p>376<p>If you ran the process with <code class="docutils literal notranslate"><span class="pre">stderr=subprocess.STDOUT</span></code>, stdout and377stderr will be combined in this attribute, and <a class="reference internal" href="#subprocess.CompletedProcess.stderr" title="subprocess.CompletedProcess.stderr"><code class="xref py py-attr docutils literal notranslate"><span class="pre">stderr</span></code></a> will be378<code class="docutils literal notranslate"><span class="pre">None</span></code>.</p>379</dd></dl>380 381<dl class="py attribute">382<dt class="sig sig-object py" id="subprocess.CompletedProcess.stderr">383<span class="sig-name descname"><span class="pre">stderr</span></span><a class="headerlink" href="#subprocess.CompletedProcess.stderr" title="Link to this definition">¶</a></dt>384<dd><p>Captured stderr from the child process. A bytes sequence, or a string if385<a class="reference internal" href="#subprocess.run" title="subprocess.run"><code class="xref py py-func docutils literal notranslate"><span class="pre">run()</span></code></a> was called with an encoding, errors, or text=True.386<code class="docutils literal notranslate"><span class="pre">None</span></code> if stderr was not captured.</p>387</dd></dl>388 389<dl class="py method">390<dt class="sig sig-object py" id="subprocess.CompletedProcess.check_returncode">391<span class="sig-name descname"><span class="pre">check_returncode</span></span><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#subprocess.CompletedProcess.check_returncode" title="Link to this definition">¶</a></dt>392<dd><p>If <a class="reference internal" href="#subprocess.CompletedProcess.returncode" title="subprocess.CompletedProcess.returncode"><code class="xref py py-attr docutils literal notranslate"><span class="pre">returncode</span></code></a> is non-zero, raise a <a class="reference internal" href="#subprocess.CalledProcessError" title="subprocess.CalledProcessError"><code class="xref py py-exc docutils literal notranslate"><span class="pre">CalledProcessError</span></code></a>.</p>393</dd></dl>394 395<div class="versionadded">396<p><span class="versionmodified added">Added in version 3.5.</span></p>397</div>398</dd></dl>399 400<dl class="py data">401<dt class="sig sig-object py" id="subprocess.DEVNULL">402<span class="sig-prename descclassname"><span class="pre">subprocess.</span></span><span class="sig-name descname"><span class="pre">DEVNULL</span></span><a class="headerlink" href="#subprocess.DEVNULL" title="Link to this definition">¶</a></dt>403<dd><p>Special value that can be used as the <em>stdin</em>, <em>stdout</em> or <em>stderr</em> argument404to <a class="reference internal" href="#subprocess.Popen" title="subprocess.Popen"><code class="xref py py-class docutils literal notranslate"><span class="pre">Popen</span></code></a> and indicates that the special file <a class="reference internal" href="os.html#os.devnull" title="os.devnull"><code class="xref py py-data docutils literal notranslate"><span class="pre">os.devnull</span></code></a>405will be used.</p>406<div class="versionadded">407<p><span class="versionmodified added">Added in version 3.3.</span></p>408</div>409</dd></dl>410 411<dl class="py data">412<dt class="sig sig-object py" id="subprocess.PIPE">413<span class="sig-prename descclassname"><span class="pre">subprocess.</span></span><span class="sig-name descname"><span class="pre">PIPE</span></span><a class="headerlink" href="#subprocess.PIPE" title="Link to this definition">¶</a></dt>414<dd><p>Special value that can be used as the <em>stdin</em>, <em>stdout</em> or <em>stderr</em> argument415to <a class="reference internal" href="#subprocess.Popen" title="subprocess.Popen"><code class="xref py py-class docutils literal notranslate"><span class="pre">Popen</span></code></a> and indicates that a pipe to the standard stream should be416opened.  Most useful with <a class="reference internal" href="#subprocess.Popen.communicate" title="subprocess.Popen.communicate"><code class="xref py py-meth docutils literal notranslate"><span class="pre">Popen.communicate()</span></code></a>.</p>417</dd></dl>418 419<dl class="py data">420<dt class="sig sig-object py" id="subprocess.STDOUT">421<span class="sig-prename descclassname"><span class="pre">subprocess.</span></span><span class="sig-name descname"><span class="pre">STDOUT</span></span><a class="headerlink" href="#subprocess.STDOUT" title="Link to this definition">¶</a></dt>422<dd><p>Special value that can be used as the <em>stderr</em> argument to <a class="reference internal" href="#subprocess.Popen" title="subprocess.Popen"><code class="xref py py-class docutils literal notranslate"><span class="pre">Popen</span></code></a> and423indicates that standard error should go into the same handle as standard424output.</p>425</dd></dl>426 427<dl class="py exception">428<dt class="sig sig-object py" id="subprocess.SubprocessError">429<em class="property"><span class="k"><span class="pre">exception</span></span><span class="w"> </span></em><span class="sig-prename descclassname"><span class="pre">subprocess.</span></span><span class="sig-name descname"><span class="pre">SubprocessError</span></span><a class="headerlink" href="#subprocess.SubprocessError" title="Link to this definition">¶</a></dt>430<dd><p>Base class for all other exceptions from this module.</p>431<div class="versionadded">432<p><span class="versionmodified added">Added in version 3.3.</span></p>433</div>434</dd></dl>435 436<dl class="py exception">437<dt class="sig sig-object py" id="subprocess.TimeoutExpired">438<em class="property"><span class="k"><span class="pre">exception</span></span><span class="w"> </span></em><span class="sig-prename descclassname"><span class="pre">subprocess.</span></span><span class="sig-name descname"><span class="pre">TimeoutExpired</span></span><a class="headerlink" href="#subprocess.TimeoutExpired" title="Link to this definition">¶</a></dt>439<dd><p>Subclass of <a class="reference internal" href="#subprocess.SubprocessError" title="subprocess.SubprocessError"><code class="xref py py-exc docutils literal notranslate"><span class="pre">SubprocessError</span></code></a>, raised when a timeout expires440while waiting for a child process.</p>441<dl class="py attribute">442<dt class="sig sig-object py" id="subprocess.TimeoutExpired.cmd">443<span class="sig-name descname"><span class="pre">cmd</span></span><a class="headerlink" href="#subprocess.TimeoutExpired.cmd" title="Link to this definition">¶</a></dt>444<dd><p>Command that was used to spawn the child process.</p>445</dd></dl>446 447<dl class="py attribute">448<dt class="sig sig-object py" id="subprocess.TimeoutExpired.timeout">449<span class="sig-name descname"><span class="pre">timeout</span></span><a class="headerlink" href="#subprocess.TimeoutExpired.timeout" title="Link to this definition">¶</a></dt>450<dd><p>Timeout in seconds.</p>451</dd></dl>452 453<dl class="py attribute">454<dt class="sig sig-object py" id="subprocess.TimeoutExpired.output">455<span class="sig-name descname"><span class="pre">output</span></span><a class="headerlink" href="#subprocess.TimeoutExpired.output" title="Link to this definition">¶</a></dt>456<dd><p>Output of the child process if it was captured by <a class="reference internal" href="#subprocess.run" title="subprocess.run"><code class="xref py py-func docutils literal notranslate"><span class="pre">run()</span></code></a> or457<a class="reference internal" href="#subprocess.check_output" title="subprocess.check_output"><code class="xref py py-func docutils literal notranslate"><span class="pre">check_output()</span></code></a>.  Otherwise, <code class="docutils literal notranslate"><span class="pre">None</span></code>.  This is always458<a class="reference internal" href="stdtypes.html#bytes" title="bytes"><code class="xref py py-class docutils literal notranslate"><span class="pre">bytes</span></code></a> when any output was captured regardless of the459<code class="docutils literal notranslate"><span class="pre">text=True</span></code> setting.  It may remain <code class="docutils literal notranslate"><span class="pre">None</span></code> instead of <code class="docutils literal notranslate"><span class="pre">b''</span></code>460when no output was observed.</p>461</dd></dl>462 463<dl class="py attribute">464<dt class="sig sig-object py" id="subprocess.TimeoutExpired.stdout">465<span class="sig-name descname"><span class="pre">stdout</span></span><a class="headerlink" href="#subprocess.TimeoutExpired.stdout" title="Link to this definition">¶</a></dt>466<dd><p>Alias for output, for symmetry with <a class="reference internal" href="#subprocess.TimeoutExpired.stderr" title="subprocess.TimeoutExpired.stderr"><code class="xref py py-attr docutils literal notranslate"><span class="pre">stderr</span></code></a>.</p>467</dd></dl>468 469<dl class="py attribute">470<dt class="sig sig-object py" id="subprocess.TimeoutExpired.stderr">471<span class="sig-name descname"><span class="pre">stderr</span></span><a class="headerlink" href="#subprocess.TimeoutExpired.stderr" title="Link to this definition">¶</a></dt>472<dd><p>Stderr output of the child process if it was captured by <a class="reference internal" href="#subprocess.run" title="subprocess.run"><code class="xref py py-func docutils literal notranslate"><span class="pre">run()</span></code></a>.473Otherwise, <code class="docutils literal notranslate"><span class="pre">None</span></code>.  This is always <a class="reference internal" href="stdtypes.html#bytes" title="bytes"><code class="xref py py-class docutils literal notranslate"><span class="pre">bytes</span></code></a> when stderr output474was captured regardless of the <code class="docutils literal notranslate"><span class="pre">text=True</span></code> setting.  It may remain475<code class="docutils literal notranslate"><span class="pre">None</span></code> instead of <code class="docutils literal notranslate"><span class="pre">b''</span></code> when no stderr output was observed.</p>476</dd></dl>477 478<div class="versionadded">479<p><span class="versionmodified added">Added in version 3.3.</span></p>480</div>481<div class="versionchanged">482<p><span class="versionmodified changed">Changed in version 3.5: </span><em>stdout</em> and <em>stderr</em> attributes added</p>483</div>484</dd></dl>485 486<dl class="py exception">487<dt class="sig sig-object py" id="subprocess.CalledProcessError">488<em class="property"><span class="k"><span class="pre">exception</span></span><span class="w"> </span></em><span class="sig-prename descclassname"><span class="pre">subprocess.</span></span><span class="sig-name descname"><span class="pre">CalledProcessError</span></span><a class="headerlink" href="#subprocess.CalledProcessError" title="Link to this definition">¶</a></dt>489<dd><p>Subclass of <a class="reference internal" href="#subprocess.SubprocessError" title="subprocess.SubprocessError"><code class="xref py py-exc docutils literal notranslate"><span class="pre">SubprocessError</span></code></a>, raised when a process run by490<a class="reference internal" href="#subprocess.check_call" title="subprocess.check_call"><code class="xref py py-func docutils literal notranslate"><span class="pre">check_call()</span></code></a>, <a class="reference internal" href="#subprocess.check_output" title="subprocess.check_output"><code class="xref py py-func docutils literal notranslate"><span class="pre">check_output()</span></code></a>, or <a class="reference internal" href="#subprocess.run" title="subprocess.run"><code class="xref py py-func docutils literal notranslate"><span class="pre">run()</span></code></a> (with <code class="docutils literal notranslate"><span class="pre">check=True</span></code>)491returns a non-zero exit status.</p>492<dl class="py attribute">493<dt class="sig sig-object py" id="subprocess.CalledProcessError.returncode">494<span class="sig-name descname"><span class="pre">returncode</span></span><a class="headerlink" href="#subprocess.CalledProcessError.returncode" title="Link to this definition">¶</a></dt>495<dd><p>Exit status of the child process.  If the process exited due to a496signal, this will be the negative signal number.</p>497</dd></dl>498 499<dl class="py attribute">500<dt class="sig sig-object py" id="subprocess.CalledProcessError.cmd">501<span class="sig-name descname"><span class="pre">cmd</span></span><a class="headerlink" href="#subprocess.CalledProcessError.cmd" title="Link to this definition">¶</a></dt>502<dd><p>Command that was used to spawn the child process.</p>503</dd></dl>504 505<dl class="py attribute">506<dt class="sig sig-object py" id="subprocess.CalledProcessError.output">507<span class="sig-name descname"><span class="pre">output</span></span><a class="headerlink" href="#subprocess.CalledProcessError.output" title="Link to this definition">¶</a></dt>508<dd><p>Output of the child process if it was captured by <a class="reference internal" href="#subprocess.run" title="subprocess.run"><code class="xref py py-func docutils literal notranslate"><span class="pre">run()</span></code></a> or509<a class="reference internal" href="#subprocess.check_output" title="subprocess.check_output"><code class="xref py py-func docutils literal notranslate"><span class="pre">check_output()</span></code></a>.  Otherwise, <code class="docutils literal notranslate"><span class="pre">None</span></code>.</p>510</dd></dl>511 512<dl class="py attribute">513<dt class="sig sig-object py" id="subprocess.CalledProcessError.stdout">514<span class="sig-name descname"><span class="pre">stdout</span></span><a class="headerlink" href="#subprocess.CalledProcessError.stdout" title="Link to this definition">¶</a></dt>515<dd><p>Alias for output, for symmetry with <a class="reference internal" href="#subprocess.CalledProcessError.stderr" title="subprocess.CalledProcessError.stderr"><code class="xref py py-attr docutils literal notranslate"><span class="pre">stderr</span></code></a>.</p>516</dd></dl>517 518<dl class="py attribute">519<dt class="sig sig-object py" id="subprocess.CalledProcessError.stderr">520<span class="sig-name descname"><span class="pre">stderr</span></span><a class="headerlink" href="#subprocess.CalledProcessError.stderr" title="Link to this definition">¶</a></dt>521<dd><p>Stderr output of the child process if it was captured by <a class="reference internal" href="#subprocess.run" title="subprocess.run"><code class="xref py py-func docutils literal notranslate"><span class="pre">run()</span></code></a>.522Otherwise, <code class="docutils literal notranslate"><span class="pre">None</span></code>.</p>523</dd></dl>524 525<div class="versionchanged">526<p><span class="versionmodified changed">Changed in version 3.5: </span><em>stdout</em> and <em>stderr</em> attributes added</p>527</div>528</dd></dl>529 530<section id="frequently-used-arguments">531<span id="id1"></span><h3>Frequently Used Arguments<a class="headerlink" href="#frequently-used-arguments" title="Link to this heading">¶</a></h3>532<p>To support a wide variety of use cases, the <a class="reference internal" href="#subprocess.Popen" title="subprocess.Popen"><code class="xref py py-class docutils literal notranslate"><span class="pre">Popen</span></code></a> constructor (and533the convenience functions) accept a large number of optional arguments. For534most typical use cases, many of these arguments can be safely left at their535default values. The arguments that are most commonly needed are:</p>536<blockquote>537<div><p><em>args</em> is required for all calls and should be a string, or a sequence of538program arguments. Providing a sequence of arguments is generally539preferred, as it allows the module to take care of any required escaping540and quoting of arguments (e.g. to permit spaces in file names). If passing541a single string, either <em>shell</em> must be <a class="reference internal" href="constants.html#True" title="True"><code class="xref py py-const docutils literal notranslate"><span class="pre">True</span></code></a> (see below) or else542the string must simply name the program to be executed without specifying543any arguments.</p>544<p><em>stdin</em>, <em>stdout</em> and <em>stderr</em> specify the executed program’s standard input,545standard output and standard error file handles, respectively.  Valid values546are <code class="docutils literal notranslate"><span class="pre">None</span></code>, <a class="reference internal" href="#subprocess.PIPE" title="subprocess.PIPE"><code class="xref py py-data docutils literal notranslate"><span class="pre">PIPE</span></code></a>, <a class="reference internal" href="#subprocess.DEVNULL" title="subprocess.DEVNULL"><code class="xref py py-data docutils literal notranslate"><span class="pre">DEVNULL</span></code></a>, an existing file descriptor (a547positive integer), and an existing <a class="reference internal" href="../glossary.html#term-file-object"><span class="xref std std-term">file object</span></a> with a valid file548descriptor.  With the default settings of <code class="docutils literal notranslate"><span class="pre">None</span></code>, no redirection will549occur.  <code class="xref py py-data docutils literal notranslate"><span class="pre">PIPE</span></code> indicates that a new pipe to the child should be550created.  <code class="xref py py-data docutils literal notranslate"><span class="pre">DEVNULL</span></code> indicates that the special file <a class="reference internal" href="os.html#os.devnull" title="os.devnull"><code class="xref py py-data docutils literal notranslate"><span class="pre">os.devnull</span></code></a>551will be used.  Additionally, <em>stderr</em> can be <a class="reference internal" href="#subprocess.STDOUT" title="subprocess.STDOUT"><code class="xref py py-data docutils literal notranslate"><span class="pre">STDOUT</span></code></a>, which indicates552that the stderr data from the child process should be captured into the same553file handle as for <em>stdout</em>.</p>554<p id="index-1">If <em>encoding</em> or <em>errors</em> are specified, or <em>text</em> (also known as555<em>universal_newlines</em>) is true,556the file objects <em>stdin</em>, <em>stdout</em> and <em>stderr</em> will be opened in text557mode using the <em>encoding</em> and <em>errors</em> specified in the call or the558defaults for <a class="reference internal" href="io.html#io.TextIOWrapper" title="io.TextIOWrapper"><code class="xref py py-class docutils literal notranslate"><span class="pre">io.TextIOWrapper</span></code></a>.</p>559<p>For <em>stdin</em>, line ending characters <code class="docutils literal notranslate"><span class="pre">'\n'</span></code> in the input will be converted560to the default line separator <a class="reference internal" href="os.html#os.linesep" title="os.linesep"><code class="xref py py-data docutils literal notranslate"><span class="pre">os.linesep</span></code></a>. For <em>stdout</em> and <em>stderr</em>,561all line endings in the output will be converted to <code class="docutils literal notranslate"><span class="pre">'\n'</span></code>.  For more562information see the documentation of the <a class="reference internal" href="io.html#io.TextIOWrapper" title="io.TextIOWrapper"><code class="xref py py-class docutils literal notranslate"><span class="pre">io.TextIOWrapper</span></code></a> class563when the <em>newline</em> argument to its constructor is <code class="docutils literal notranslate"><span class="pre">None</span></code>.</p>564<p>If text mode is not used, <em>stdin</em>, <em>stdout</em> and <em>stderr</em> will be opened as565binary streams. No encoding or line ending conversion is performed.</p>566<div class="versionchanged">567<p><span class="versionmodified changed">Changed in version 3.6: </span>Added the <em>encoding</em> and <em>errors</em> parameters.</p>568</div>569<div class="versionchanged">570<p><span class="versionmodified changed">Changed in version 3.7: </span>Added the <em>text</em> parameter as an alias for <em>universal_newlines</em>.</p>571</div>572<div class="admonition note">573<p class="admonition-title">Note</p>574<p>The newlines attribute of the file objects <a class="reference internal" href="#subprocess.Popen.stdin" title="subprocess.Popen.stdin"><code class="xref py py-attr docutils literal notranslate"><span class="pre">Popen.stdin</span></code></a>,575<a class="reference internal" href="#subprocess.Popen.stdout" title="subprocess.Popen.stdout"><code class="xref py py-attr docutils literal notranslate"><span class="pre">Popen.stdout</span></code></a> and <a class="reference internal" href="#subprocess.Popen.stderr" title="subprocess.Popen.stderr"><code class="xref py py-attr docutils literal notranslate"><span class="pre">Popen.stderr</span></code></a> are not updated by576the <a class="reference internal" href="#subprocess.Popen.communicate" title="subprocess.Popen.communicate"><code class="xref py py-meth docutils literal notranslate"><span class="pre">Popen.communicate()</span></code></a> method.</p>577</div>578<p>If <em>shell</em> is <code class="docutils literal notranslate"><span class="pre">True</span></code>, the specified command will be executed through579the shell.  This can be useful if you are using Python primarily for the580enhanced control flow it offers over most system shells and still want581convenient access to other shell features such as shell pipes, filename582wildcards, environment variable expansion, and expansion of <code class="docutils literal notranslate"><span class="pre">~</span></code> to a583user’s home directory.  However, note that Python itself offers584implementations of many shell-like features (in particular, <a class="reference internal" href="glob.html#module-glob" title="glob: Unix shell style pathname pattern expansion."><code class="xref py py-mod docutils literal notranslate"><span class="pre">glob</span></code></a>,585<a class="reference internal" href="fnmatch.html#module-fnmatch" title="fnmatch: Unix shell style filename pattern matching."><code class="xref py py-mod docutils literal notranslate"><span class="pre">fnmatch</span></code></a>, <a class="reference internal" href="os.html#os.walk" title="os.walk"><code class="xref py py-func docutils literal notranslate"><span class="pre">os.walk()</span></code></a>, <a class="reference internal" href="os.path.html#os.path.expandvars" title="os.path.expandvars"><code class="xref py py-func docutils literal notranslate"><span class="pre">os.path.expandvars()</span></code></a>,586<a class="reference internal" href="os.path.html#os.path.expanduser" title="os.path.expanduser"><code class="xref py py-func docutils literal notranslate"><span class="pre">os.path.expanduser()</span></code></a>, and <a class="reference internal" href="shutil.html#module-shutil" title="shutil: High-level file operations, including copying."><code class="xref py py-mod docutils literal notranslate"><span class="pre">shutil</span></code></a>).</p>587<div class="versionchanged">588<p><span class="versionmodified changed">Changed in version 3.3: </span>When <em>universal_newlines</em> is <code class="docutils literal notranslate"><span class="pre">True</span></code>, the class uses the encoding589<a class="reference internal" href="locale.html#locale.getpreferredencoding" title="locale.getpreferredencoding"><code class="xref py py-func docutils literal notranslate"><span class="pre">locale.getpreferredencoding(False)</span></code></a>590instead of <code class="docutils literal notranslate"><span class="pre">locale.getpreferredencoding()</span></code>.  See the591<a class="reference internal" href="io.html#io.TextIOWrapper" title="io.TextIOWrapper"><code class="xref py py-class docutils literal notranslate"><span class="pre">io.TextIOWrapper</span></code></a> class for more information on this change.</p>592</div>593<div class="admonition note">594<p class="admonition-title">Note</p>595<p>Read the <a class="reference internal" href="#security-considerations">Security Considerations</a> section before using <code class="docutils literal notranslate"><span class="pre">shell=True</span></code>.</p>596</div>597</div></blockquote>598<p>These options, along with all of the other options, are described in more599detail in the <a class="reference internal" href="#subprocess.Popen" title="subprocess.Popen"><code class="xref py py-class docutils literal notranslate"><span class="pre">Popen</span></code></a> constructor documentation.</p>600</section>601<section id="popen-constructor">602<h3>Popen Constructor<a class="headerlink" href="#popen-constructor" title="Link to this heading">¶</a></h3>603<p>The underlying process creation and management in this module is handled by604the <a class="reference internal" href="#subprocess.Popen" title="subprocess.Popen"><code class="xref py py-class docutils literal notranslate"><span class="pre">Popen</span></code></a> class. It offers a lot of flexibility so that developers605are able to handle the less common cases not covered by the convenience606functions.</p>607<dl class="py class">608<dt class="sig sig-object py" id="subprocess.Popen">609<em class="property"><span class="k"><span class="pre">class</span></span><span class="w"> </span></em><span class="sig-prename descclassname"><span class="pre">subprocess.</span></span><span class="sig-name descname"><span class="pre">Popen</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">args</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">bufsize</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">-1</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">executable</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">None</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">stdin</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">None</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">stdout</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">None</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">stderr</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">None</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">preexec_fn</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">None</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">close_fds</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">True</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">shell</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">False</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">cwd</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">None</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">env</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">None</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">universal_newlines</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">None</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">startupinfo</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">None</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">creationflags</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">0</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">restore_signals</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">True</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">start_new_session</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">False</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">pass_fds</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">()</span></span></em>, <em class="sig-param"><span class="keyword-only-separator o"><abbr title="Keyword-only parameters separator (PEP 3102)"><span class="pre">*</span></abbr></span></em>, <em class="sig-param"><span class="n"><span class="pre">group</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">None</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">extra_groups</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">None</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">user</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">None</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">umask</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">-1</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">encoding</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">None</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">errors</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">None</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">text</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">None</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">pipesize</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">-1</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">process_group</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">None</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="#subprocess.Popen" title="Link to this definition">¶</a></dt>610<dd><p>Execute a child program in a new process.  On POSIX, the class uses611<a class="reference internal" href="os.html#os.execvpe" title="os.execvpe"><code class="xref py py-meth docutils literal notranslate"><span class="pre">os.execvpe()</span></code></a>-like behavior to execute the child program.  On Windows,612the class uses the Windows <code class="docutils literal notranslate"><span class="pre">CreateProcess()</span></code> function.  The arguments to613<code class="xref py py-class docutils literal notranslate"><span class="pre">Popen</span></code> are as follows.</p>614<p><em>args</em> should be a sequence of program arguments or else a single string615or <a class="reference internal" href="../glossary.html#term-path-like-object"><span class="xref std std-term">path-like object</span></a>.616By default, the program to execute is the first item in <em>args</em> if <em>args</em> is617a sequence.  If <em>args</em> is a string, the interpretation is618platform-dependent and described below.  See the <em>shell</em> and <em>executable</em>619arguments for additional differences from the default behavior.  Unless620otherwise stated, it is recommended to pass <em>args</em> as a sequence.</p>621<div class="admonition warning">622<p class="admonition-title">Warning</p>623<p>For maximum reliability, use a fully qualified path for the executable.624To search for an unqualified name on <span class="target" id="index-2"></span><code class="xref std std-envvar docutils literal notranslate"><span class="pre">PATH</span></code>, use625<a class="reference internal" href="shutil.html#shutil.which" title="shutil.which"><code class="xref py py-meth docutils literal notranslate"><span class="pre">shutil.which()</span></code></a>. On all platforms, passing <a class="reference internal" href="sys.html#sys.executable" title="sys.executable"><code class="xref py py-data docutils literal notranslate"><span class="pre">sys.executable</span></code></a>626is the recommended way to launch the current Python interpreter again,627and use the <code class="docutils literal notranslate"><span class="pre">-m</span></code> command-line format to launch an installed module.</p>628<p>Resolving the path of <em>executable</em> (or the first item of <em>args</em>) is629platform dependent. For POSIX, see <a class="reference internal" href="os.html#os.execvpe" title="os.execvpe"><code class="xref py py-meth docutils literal notranslate"><span class="pre">os.execvpe()</span></code></a>, and note that630when resolving or searching for the executable path, <em>cwd</em> overrides the631current working directory and <em>env</em> can override the <code class="docutils literal notranslate"><span class="pre">PATH</span></code>632environment variable. For Windows, see the documentation of the633<code class="docutils literal notranslate"><span class="pre">lpApplicationName</span></code> and <code class="docutils literal notranslate"><span class="pre">lpCommandLine</span></code> parameters of WinAPI634<code class="docutils literal notranslate"><span class="pre">CreateProcess</span></code>, and note that when resolving or searching for the635executable path with <code class="docutils literal notranslate"><span class="pre">shell=False</span></code>, <em>cwd</em> does not override the636current working directory and <em>env</em> cannot override the <code class="docutils literal notranslate"><span class="pre">PATH</span></code>637environment variable. Using a full path avoids all of these variations.</p>638</div>639<p>An example of passing some arguments to an external program640as a sequence is:</p>641<div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="n">Popen</span><span class="p">([</span><span class="s2">&quot;/usr/bin/git&quot;</span><span class="p">,</span> <span class="s2">&quot;commit&quot;</span><span class="p">,</span> <span class="s2">&quot;-m&quot;</span><span class="p">,</span> <span class="s2">&quot;Fixes a bug.&quot;</span><span class="p">])</span>642</pre></div>643</div>644<p>On POSIX, if <em>args</em> is a string, the string is interpreted as the name or645path of the program to execute.  However, this can only be done if not646passing arguments to the program.</p>647<div class="admonition note">648<p class="admonition-title">Note</p>649<p>It may not be obvious how to break a shell command into a sequence of arguments,650especially in complex cases. <a class="reference internal" href="shlex.html#shlex.split" title="shlex.split"><code class="xref py py-meth docutils literal notranslate"><span class="pre">shlex.split()</span></code></a> can illustrate how to651determine the correct tokenization for <em>args</em>:</p>652<div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="gp">&gt;&gt;&gt; </span><span class="kn">import</span><span class="w"> </span><span class="nn">shlex</span><span class="o">,</span><span class="w"> </span><span class="nn">subprocess</span>653<span class="gp">&gt;&gt;&gt; </span><span class="n">command_line</span> <span class="o">=</span> <span class="nb">input</span><span class="p">()</span>654<span class="go">/bin/vikings -input eggs.txt -output &quot;spam spam.txt&quot; -cmd &quot;echo &#39;$MONEY&#39;&quot;</span>655<span class="gp">&gt;&gt;&gt; </span><span class="n">args</span> <span class="o">=</span> <span class="n">shlex</span><span class="o">.</span><span class="n">split</span><span class="p">(</span><span class="n">command_line</span><span class="p">)</span>656<span class="gp">&gt;&gt;&gt; </span><span class="nb">print</span><span class="p">(</span><span class="n">args</span><span class="p">)</span>657<span class="go">[&#39;/bin/vikings&#39;, &#39;-input&#39;, &#39;eggs.txt&#39;, &#39;-output&#39;, &#39;spam spam.txt&#39;, &#39;-cmd&#39;, &quot;echo &#39;$MONEY&#39;&quot;]</span>658<span class="gp">&gt;&gt;&gt; </span><span class="n">p</span> <span class="o">=</span> <span class="n">subprocess</span><span class="o">.</span><span class="n">Popen</span><span class="p">(</span><span class="n">args</span><span class="p">)</span> <span class="c1"># Success!</span>659</pre></div>660</div>661<p>Note in particular that options (such as <em>-input</em>) and arguments (such662as <em>eggs.txt</em>) that are separated by whitespace in the shell go in separate663list elements, while arguments that need quoting or backslash escaping when664used in the shell (such as filenames containing spaces or the <em>echo</em> command665shown above) are single list elements.</p>666</div>667<p>On Windows, if <em>args</em> is a sequence, it will be converted to a string in a668manner described in <a class="reference internal" href="#converting-argument-sequence"><span class="std std-ref">Converting an argument sequence to a string on Windows</span></a>.  This is because669the underlying <code class="docutils literal notranslate"><span class="pre">CreateProcess()</span></code> operates on strings.</p>670<div class="versionchanged">671<p><span class="versionmodified changed">Changed in version 3.6: </span><em>args</em> parameter accepts a <a class="reference internal" href="../glossary.html#term-path-like-object"><span class="xref std std-term">path-like object</span></a> if <em>shell</em> is672<code class="docutils literal notranslate"><span class="pre">False</span></code> and a sequence containing path-like objects on POSIX.</p>673</div>674<div class="versionchanged">675<p><span class="versionmodified changed">Changed in version 3.8: </span><em>args</em> parameter accepts a <a class="reference internal" href="../glossary.html#term-path-like-object"><span class="xref std std-term">path-like object</span></a> if <em>shell</em> is676<code class="docutils literal notranslate"><span class="pre">False</span></code> and a sequence containing bytes and path-like objects677on Windows.</p>678</div>679<p>The <em>shell</em> argument (which defaults to <code class="docutils literal notranslate"><span class="pre">False</span></code>) specifies whether to use680the shell as the program to execute.  If <em>shell</em> is <code class="docutils literal notranslate"><span class="pre">True</span></code>, it is681recommended to pass <em>args</em> as a string rather than as a sequence.</p>682<p>On POSIX with <code class="docutils literal notranslate"><span class="pre">shell=True</span></code>, the shell defaults to <code class="file docutils literal notranslate"><span class="pre">/bin/sh</span></code>.  If683<em>args</em> is a string, the string specifies the command684to execute through the shell.  This means that the string must be685formatted exactly as it would be when typed at the shell prompt.  This686includes, for example, quoting or backslash escaping filenames with spaces in687them.  If <em>args</em> is a sequence, the first item specifies the command string, and688any additional items will be treated as additional arguments to the shell689itself.  That is to say, <code class="xref py py-class docutils literal notranslate"><span class="pre">Popen</span></code> does the equivalent of:</p>690<div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="n">Popen</span><span class="p">([</span><span class="s1">&#39;/bin/sh&#39;</span><span class="p">,</span> <span class="s1">&#39;-c&#39;</span><span class="p">,</span> <span class="n">args</span><span class="p">[</span><span class="mi">0</span><span class="p">],</span> <span class="n">args</span><span class="p">[</span><span class="mi">1</span><span class="p">],</span> <span class="o">...</span><span class="p">])</span>691</pre></div>692</div>693<p>On Windows with <code class="docutils literal notranslate"><span class="pre">shell=True</span></code>, the <span class="target" id="index-3"></span><code class="xref std std-envvar docutils literal notranslate"><span class="pre">COMSPEC</span></code> environment variable694specifies the default shell.  The only time you need to specify695<code class="docutils literal notranslate"><span class="pre">shell=True</span></code> on Windows is when the command you wish to execute is built696into the shell (e.g. <strong class="command">dir</strong> or <strong class="command">copy</strong>).  You do not need697<code class="docutils literal notranslate"><span class="pre">shell=True</span></code> to run a batch file or console-based executable.</p>698<div class="admonition note">699<p class="admonition-title">Note</p>700<p>Read the <a class="reference internal" href="#security-considerations">Security Considerations</a> section before using <code class="docutils literal notranslate"><span class="pre">shell=True</span></code>.</p>701</div>702<p><em>bufsize</em> will be supplied as the corresponding argument to the703<a class="reference internal" href="functions.html#open" title="open"><code class="xref py py-func docutils literal notranslate"><span class="pre">open()</span></code></a> function when creating the stdin/stdout/stderr pipe704file objects:</p>705<ul class="simple">706<li><p><code class="docutils literal notranslate"><span class="pre">0</span></code> means unbuffered (read and write are one707system call and can return short)</p></li>708<li><p><code class="docutils literal notranslate"><span class="pre">1</span></code> means line buffered709(only usable if <code class="docutils literal notranslate"><span class="pre">text=True</span></code> or <code class="docutils literal notranslate"><span class="pre">universal_newlines=True</span></code>)</p></li>710<li><p>any other positive value means use a buffer of approximately that711size</p></li>712<li><p>negative bufsize (the default) means the system default of713io.DEFAULT_BUFFER_SIZE will be used.</p></li>714</ul>715<div class="versionchanged">716<p><span class="versionmodified changed">Changed in version 3.3.1: </span><em>bufsize</em> now defaults to -1 to enable buffering by default to match the717behavior that most code expects.  In versions prior to Python 3.2.4 and7183.3.1 it incorrectly defaulted to <code class="docutils literal notranslate"><span class="pre">0</span></code> which was unbuffered719and allowed short reads.  This was unintentional and did not match the720behavior of Python 2 as most code expected.</p>721</div>722<p>The <em>executable</em> argument specifies a replacement program to execute.   It723is very seldom needed.  When <code class="docutils literal notranslate"><span class="pre">shell=False</span></code>, <em>executable</em> replaces the724program to execute specified by <em>args</em>.  However, the original <em>args</em> is725still passed to the program.  Most programs treat the program specified726by <em>args</em> as the command name, which can then be different from the program727actually executed.  On POSIX, the <em>args</em> name728becomes the display name for the executable in utilities such as729<strong class="program">ps</strong>.  If <code class="docutils literal notranslate"><span class="pre">shell=True</span></code>, on POSIX the <em>executable</em> argument730specifies a replacement shell for the default <code class="file docutils literal notranslate"><span class="pre">/bin/sh</span></code>.</p>731<div class="versionchanged">732<p><span class="versionmodified changed">Changed in version 3.6: </span><em>executable</em> parameter accepts a <a class="reference internal" href="../glossary.html#term-path-like-object"><span class="xref std std-term">path-like object</span></a> on POSIX.</p>733</div>734<div class="versionchanged">735<p><span class="versionmodified changed">Changed in version 3.8: </span><em>executable</em> parameter accepts a bytes and <a class="reference internal" href="../glossary.html#term-path-like-object"><span class="xref std std-term">path-like object</span></a>736on Windows.</p>737</div>738<div class="versionchanged">739<p><span class="versionmodified changed">Changed in version 3.12: </span>Changed Windows shell search order for <code class="docutils literal notranslate"><span class="pre">shell=True</span></code>. The current740directory and <code class="docutils literal notranslate"><span class="pre">%PATH%</span></code> are replaced with <code class="docutils literal notranslate"><span class="pre">%COMSPEC%</span></code> and741<code class="docutils literal notranslate"><span class="pre">%SystemRoot%\System32\cmd.exe</span></code>. As a result, dropping a742malicious program named <code class="docutils literal notranslate"><span class="pre">cmd.exe</span></code> into a current directory no743longer works.</p>744</div>745<p><em>stdin</em>, <em>stdout</em> and <em>stderr</em> specify the executed program’s standard input,746standard output and standard error file handles, respectively.  Valid values747are <code class="docutils literal notranslate"><span class="pre">None</span></code>, <a class="reference internal" href="#subprocess.PIPE" title="subprocess.PIPE"><code class="xref py py-data docutils literal notranslate"><span class="pre">PIPE</span></code></a>, <a class="reference internal" href="#subprocess.DEVNULL" title="subprocess.DEVNULL"><code class="xref py py-data docutils literal notranslate"><span class="pre">DEVNULL</span></code></a>, an existing file descriptor (a748positive integer), and an existing <a class="reference internal" href="../glossary.html#term-file-object"><span class="xref std std-term">file object</span></a> with a valid file749descriptor.  With the default settings of <code class="docutils literal notranslate"><span class="pre">None</span></code>, no redirection will750occur.  <code class="xref py py-data docutils literal notranslate"><span class="pre">PIPE</span></code> indicates that a new pipe to the child should be751created.  <code class="xref py py-data docutils literal notranslate"><span class="pre">DEVNULL</span></code> indicates that the special file <a class="reference internal" href="os.html#os.devnull" title="os.devnull"><code class="xref py py-data docutils literal notranslate"><span class="pre">os.devnull</span></code></a>752will be used.  Additionally, <em>stderr</em> can be <a class="reference internal" href="#subprocess.STDOUT" title="subprocess.STDOUT"><code class="xref py py-data docutils literal notranslate"><span class="pre">STDOUT</span></code></a>, which indicates753that the stderr data from the applications should be captured into the same754file handle as for <em>stdout</em>.</p>755<p>If <em>preexec_fn</em> is set to a callable object, this object will be called in the756child process just before the child is executed.757(POSIX only)</p>758<div class="admonition warning">759<p class="admonition-title">Warning</p>760<p>The <em>preexec_fn</em> parameter is NOT SAFE to use in the presence of threads761in your application.  The child process could deadlock before exec is762called.</p>763</div>764<div class="admonition note">765<p class="admonition-title">Note</p>766<p>If you need to modify the environment for the child use the <em>env</em>767parameter rather than doing it in a <em>preexec_fn</em>.768The <em>start_new_session</em> and <em>process_group</em> parameters should take the place of769code using <em>preexec_fn</em> to call <a class="reference internal" href="os.html#os.setsid" title="os.setsid"><code class="xref py py-func docutils literal notranslate"><span class="pre">os.setsid()</span></code></a> or <a class="reference internal" href="os.html#os.setpgid" title="os.setpgid"><code class="xref py py-func docutils literal notranslate"><span class="pre">os.setpgid()</span></code></a> in the child.</p>770</div>771<div class="versionchanged">772<p><span class="versionmodified changed">Changed in version 3.8: </span>The <em>preexec_fn</em> parameter is no longer supported in subinterpreters.773The use of the parameter in a subinterpreter raises774<a class="reference internal" href="exceptions.html#RuntimeError" title="RuntimeError"><code class="xref py py-exc docutils literal notranslate"><span class="pre">RuntimeError</span></code></a>. The new restriction may affect applications that775are deployed in mod_wsgi, uWSGI, and other embedded environments.</p>776</div>777<p>If <em>close_fds</em> is true, all file descriptors except <code class="docutils literal notranslate"><span class="pre">0</span></code>, <code class="docutils literal notranslate"><span class="pre">1</span></code> and778<code class="docutils literal notranslate"><span class="pre">2</span></code> will be closed before the child process is executed.  Otherwise779when <em>close_fds</em> is false, file descriptors obey their inheritable flag780as described in <a class="reference internal" href="os.html#fd-inheritance"><span class="std std-ref">Inheritance of File Descriptors</span></a>.</p>781<p>On Windows, if <em>close_fds</em> is true then no handles will be inherited by the782child process unless explicitly passed in the <code class="docutils literal notranslate"><span class="pre">handle_list</span></code> element of783<a class="reference internal" href="#subprocess.STARTUPINFO.lpAttributeList" title="subprocess.STARTUPINFO.lpAttributeList"><code class="xref py py-attr docutils literal notranslate"><span class="pre">STARTUPINFO.lpAttributeList</span></code></a>, or by standard handle redirection.</p>784<div class="versionchanged">785<p><span class="versionmodified changed">Changed in version 3.2: </span>The default for <em>close_fds</em> was changed from <a class="reference internal" href="constants.html#False" title="False"><code class="xref py py-const docutils literal notranslate"><span class="pre">False</span></code></a> to786what is described above.</p>787</div>788<div class="versionchanged">789<p><span class="versionmodified changed">Changed in version 3.7: </span>On Windows the default for <em>close_fds</em> was changed from <a class="reference internal" href="constants.html#False" title="False"><code class="xref py py-const docutils literal notranslate"><span class="pre">False</span></code></a> to790<a class="reference internal" href="constants.html#True" title="True"><code class="xref py py-const docutils literal notranslate"><span class="pre">True</span></code></a> when redirecting the standard handles. It’s now possible to791set <em>close_fds</em> to <code class="xref py py-const docutils literal notranslate"><span class="pre">True</span></code> when redirecting the standard handles.</p>792</div>793<p><em>pass_fds</em> is an optional sequence of file descriptors to keep open794between the parent and child.  Providing any <em>pass_fds</em> forces795<em>close_fds</em> to be <a class="reference internal" href="constants.html#True" title="True"><code class="xref py py-const docutils literal notranslate"><span class="pre">True</span></code></a>.  (POSIX only)</p>796<div class="versionchanged">797<p><span class="versionmodified changed">Changed in version 3.2: </span>The <em>pass_fds</em> parameter was added.</p>798</div>799<p>If <em>cwd</em> is not <code class="docutils literal notranslate"><span class="pre">None</span></code>, the function changes the working directory to800<em>cwd</em> before executing the child.  <em>cwd</em> can be a string, bytes or801<a class="reference internal" href="../glossary.html#term-path-like-object"><span class="xref std std-term">path-like</span></a> object.  On POSIX, the function802looks for <em>executable</em> (or for the first item in <em>args</em>) relative to <em>cwd</em>803if the executable path is a relative path.</p>804<div class="versionchanged">805<p><span class="versionmodified changed">Changed in version 3.6: </span><em>cwd</em> parameter accepts a <a class="reference internal" href="../glossary.html#term-path-like-object"><span class="xref std std-term">path-like object</span></a> on POSIX.</p>806</div>807<div class="versionchanged">808<p><span class="versionmodified changed">Changed in version 3.7: </span><em>cwd</em> parameter accepts a <a class="reference internal" href="../glossary.html#term-path-like-object"><span class="xref std std-term">path-like object</span></a> on Windows.</p>809</div>810<div class="versionchanged">811<p><span class="versionmodified changed">Changed in version 3.8: </span><em>cwd</em> parameter accepts a bytes object on Windows.</p>812</div>813<p>If <em>restore_signals</em> is true (the default) all signals that Python has set to814SIG_IGN are restored to SIG_DFL in the child process before the exec.815Currently this includes the SIGPIPE, SIGXFZ and SIGXFSZ signals.816(POSIX only)</p>817<div class="versionchanged">818<p><span class="versionmodified changed">Changed in version 3.2: </span><em>restore_signals</em> was added.</p>819</div>820<p>If <em>start_new_session</em> is true the <code class="docutils literal notranslate"><span class="pre">setsid()</span></code> system call will be made in the821child process prior to the execution of the subprocess.</p>822<div class="availability docutils container">823<p><a class="reference internal" href="intro.html#availability"><span class="std std-ref">Availability</span></a>: POSIX</p>824</div>825<div class="versionchanged">826<p><span class="versionmodified changed">Changed in version 3.2: </span><em>start_new_session</em> was added.</p>827</div>828<p>If <em>process_group</em> is a non-negative integer, the <code class="docutils literal notranslate"><span class="pre">setpgid(0,</span> <span class="pre">value)</span></code> system call will829be made in the child process prior to the execution of the subprocess.</p>830<div class="availability docutils container">831<p><a class="reference internal" href="intro.html#availability"><span class="std std-ref">Availability</span></a>: POSIX</p>832</div>833<div class="versionchanged">834<p><span class="versionmodified changed">Changed in version 3.11: </span><em>process_group</em> was added.</p>835</div>836<p>If <em>group</em> is not <code class="docutils literal notranslate"><span class="pre">None</span></code>, the setregid() system call will be made in the837child process prior to the execution of the subprocess. If the provided838value is a string, it will be looked up via <a class="reference internal" href="grp.html#grp.getgrnam" title="grp.getgrnam"><code class="xref py py-func docutils literal notranslate"><span class="pre">grp.getgrnam()</span></code></a> and839the value in <code class="docutils literal notranslate"><span class="pre">gr_gid</span></code> will be used. If the value is an integer, it840will be passed verbatim. (POSIX only)</p>841<div class="availability docutils container">842<p><a class="reference internal" href="intro.html#availability"><span class="std std-ref">Availability</span></a>: POSIX</p>843</div>844<div class="versionadded">845<p><span class="versionmodified added">Added in version 3.9.</span></p>846</div>847<p>If <em>extra_groups</em> is not <code class="docutils literal notranslate"><span class="pre">None</span></code>, the setgroups() system call will be848made in the child process prior to the execution of the subprocess.849Strings provided in <em>extra_groups</em> will be looked up via850<a class="reference internal" href="grp.html#grp.getgrnam" title="grp.getgrnam"><code class="xref py py-func docutils literal notranslate"><span class="pre">grp.getgrnam()</span></code></a> and the values in <code class="docutils literal notranslate"><span class="pre">gr_gid</span></code> will be used.851Integer values will be passed verbatim. (POSIX only)</p>852<div class="availability docutils container">853<p><a class="reference internal" href="intro.html#availability"><span class="std std-ref">Availability</span></a>: POSIX</p>854</div>855<div class="versionadded">856<p><span class="versionmodified added">Added in version 3.9.</span></p>857</div>858<p>If <em>user</em> is not <code class="docutils literal notranslate"><span class="pre">None</span></code>, the setreuid() system call will be made in the859child process prior to the execution of the subprocess. If the provided860value is a string, it will be looked up via <a class="reference internal" href="pwd.html#pwd.getpwnam" title="pwd.getpwnam"><code class="xref py py-func docutils literal notranslate"><span class="pre">pwd.getpwnam()</span></code></a> and861the value in <code class="docutils literal notranslate"><span class="pre">pw_uid</span></code> will be used. If the value is an integer, it will862be passed verbatim. (POSIX only)</p>863<div class="availability docutils container">864<p><a class="reference internal" href="intro.html#availability"><span class="std std-ref">Availability</span></a>: POSIX</p>865</div>866<div class="versionadded">867<p><span class="versionmodified added">Added in version 3.9.</span></p>868</div>869<p>If <em>umask</em> is not negative, the umask() system call will be made in the870child process prior to the execution of the subprocess.</p>871<div class="availability docutils container">872<p><a class="reference internal" href="intro.html#availability"><span class="std std-ref">Availability</span></a>: POSIX</p>873</div>874<div class="versionadded">875<p><span class="versionmodified added">Added in version 3.9.</span></p>876</div>877<p>If <em>env</em> is not <code class="docutils literal notranslate"><span class="pre">None</span></code>, it must be a mapping that defines the environment878variables for the new process; these are used instead of the default879behavior of inheriting the current process’ environment. This mapping can be880str to str on any platform or bytes to bytes on POSIX platforms much like881<a class="reference internal" href="os.html#os.environ" title="os.environ"><code class="xref py py-data docutils literal notranslate"><span class="pre">os.environ</span></code></a> or <a class="reference internal" href="os.html#os.environb" title="os.environb"><code class="xref py py-data docutils literal notranslate"><span class="pre">os.environb</span></code></a>.</p>882<div class="admonition note">883<p class="admonition-title">Note</p>884<p>If specified, <em>env</em> must provide any variables required for the program to885execute.  On Windows, in order to run a <a class="reference external" href="https://en.wikipedia.org/wiki/Side-by-Side_Assembly">side-by-side assembly</a> the886specified <em>env</em> <strong>must</strong> include a valid <code class="docutils literal notranslate"><span class="pre">%SystemRoot%</span></code>.</p>887</div>888<p>If <em>encoding</em> or <em>errors</em> are specified, or <em>text</em> is true, the file objects889<em>stdin</em>, <em>stdout</em> and <em>stderr</em> are opened in text mode with the specified890<em>encoding</em> and <em>errors</em>, as described above in <a class="reference internal" href="#frequently-used-arguments"><span class="std std-ref">Frequently Used Arguments</span></a>.891The <em>universal_newlines</em> argument is equivalent  to <em>text</em> and is provided892for backwards compatibility. By default, file objects are opened in binary mode.</p>893<div class="versionadded">894<p><span class="versionmodified added">Added in version 3.6: </span><em>encoding</em> and <em>errors</em> were added.</p>895</div>896<div class="versionadded">897<p><span class="versionmodified added">Added in version 3.7: </span><em>text</em> was added as a more readable alias for <em>universal_newlines</em>.</p>898</div>899<p>If given, <em>startupinfo</em> will be a <a class="reference internal" href="#subprocess.STARTUPINFO" title="subprocess.STARTUPINFO"><code class="xref py py-class docutils literal notranslate"><span class="pre">STARTUPINFO</span></code></a> object, which is900passed to the underlying <code class="docutils literal notranslate"><span class="pre">CreateProcess</span></code> function.</p>901<p>If given, <em>creationflags</em>, can be one or more of the following flags:</p>902<ul class="simple">903<li><p><a class="reference internal" href="#subprocess.CREATE_NEW_CONSOLE" title="subprocess.CREATE_NEW_CONSOLE"><code class="xref py py-data docutils literal notranslate"><span class="pre">CREATE_NEW_CONSOLE</span></code></a></p></li>904<li><p><a class="reference internal" href="#subprocess.CREATE_NEW_PROCESS_GROUP" title="subprocess.CREATE_NEW_PROCESS_GROUP"><code class="xref py py-data docutils literal notranslate"><span class="pre">CREATE_NEW_PROCESS_GROUP</span></code></a></p></li>905<li><p><a class="reference internal" href="#subprocess.ABOVE_NORMAL_PRIORITY_CLASS" title="subprocess.ABOVE_NORMAL_PRIORITY_CLASS"><code class="xref py py-data docutils literal notranslate"><span class="pre">ABOVE_NORMAL_PRIORITY_CLASS</span></code></a></p></li>906<li><p><a class="reference internal" href="#subprocess.BELOW_NORMAL_PRIORITY_CLASS" title="subprocess.BELOW_NORMAL_PRIORITY_CLASS"><code class="xref py py-data docutils literal notranslate"><span class="pre">BELOW_NORMAL_PRIORITY_CLASS</span></code></a></p></li>907<li><p><a class="reference internal" href="#subprocess.HIGH_PRIORITY_CLASS" title="subprocess.HIGH_PRIORITY_CLASS"><code class="xref py py-data docutils literal notranslate"><span class="pre">HIGH_PRIORITY_CLASS</span></code></a></p></li>908<li><p><a class="reference internal" href="#subprocess.IDLE_PRIORITY_CLASS" title="subprocess.IDLE_PRIORITY_CLASS"><code class="xref py py-data docutils literal notranslate"><span class="pre">IDLE_PRIORITY_CLASS</span></code></a></p></li>909<li><p><a class="reference internal" href="#subprocess.NORMAL_PRIORITY_CLASS" title="subprocess.NORMAL_PRIORITY_CLASS"><code class="xref py py-data docutils literal notranslate"><span class="pre">NORMAL_PRIORITY_CLASS</span></code></a></p></li>910<li><p><a class="reference internal" href="#subprocess.REALTIME_PRIORITY_CLASS" title="subprocess.REALTIME_PRIORITY_CLASS"><code class="xref py py-data docutils literal notranslate"><span class="pre">REALTIME_PRIORITY_CLASS</span></code></a></p></li>911<li><p><a class="reference internal" href="#subprocess.CREATE_NO_WINDOW" title="subprocess.CREATE_NO_WINDOW"><code class="xref py py-data docutils literal notranslate"><span class="pre">CREATE_NO_WINDOW</span></code></a></p></li>912<li><p><a class="reference internal" href="#subprocess.DETACHED_PROCESS" title="subprocess.DETACHED_PROCESS"><code class="xref py py-data docutils literal notranslate"><span class="pre">DETACHED_PROCESS</span></code></a></p></li>913<li><p><a class="reference internal" href="#subprocess.CREATE_DEFAULT_ERROR_MODE" title="subprocess.CREATE_DEFAULT_ERROR_MODE"><code class="xref py py-data docutils literal notranslate"><span class="pre">CREATE_DEFAULT_ERROR_MODE</span></code></a></p></li>914<li><p><a class="reference internal" href="#subprocess.CREATE_BREAKAWAY_FROM_JOB" title="subprocess.CREATE_BREAKAWAY_FROM_JOB"><code class="xref py py-data docutils literal notranslate"><span class="pre">CREATE_BREAKAWAY_FROM_JOB</span></code></a></p></li>915</ul>916<p><em>pipesize</em> can be used to change the size of the pipe when917<a class="reference internal" href="#subprocess.PIPE" title="subprocess.PIPE"><code class="xref py py-data docutils literal notranslate"><span class="pre">PIPE</span></code></a> is used for <em>stdin</em>, <em>stdout</em> or <em>stderr</em>. The size of the pipe918is only changed on platforms that support this (only Linux at this time of919writing). Other platforms will ignore this parameter.</p>920<div class="versionchanged">921<p><span class="versionmodified changed">Changed in version 3.10: </span>Added the <em>pipesize</em> parameter.</p>922</div>923<p>Popen objects are supported as context managers via the <a class="reference internal" href="../reference/compound_stmts.html#with"><code class="xref std std-keyword docutils literal notranslate"><span class="pre">with</span></code></a> statement:924on exit, standard file descriptors are closed, and the process is waited for.</p>925<div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="k">with</span> <span class="n">Popen</span><span class="p">([</span><span class="s2">&quot;ifconfig&quot;</span><span class="p">],</span> <span class="n">stdout</span><span class="o">=</span><span class="n">PIPE</span><span class="p">)</span> <span class="k">as</span> <span class="n">proc</span><span class="p">:</span>926    <span class="n">log</span><span class="o">.</span><span class="n">write</span><span class="p">(</span><span class="n">proc</span><span class="o">.</span><span class="n">stdout</span><span class="o">.</span><span class="n">read</span><span class="p">())</span>927</pre></div>928</div>929<p class="audit-hook"><p>Popen and the other functions in this module that use it raise an930<a class="reference internal" href="sys.html#auditing"><span class="std std-ref">auditing event</span></a> <code class="docutils literal notranslate"><span class="pre">subprocess.Popen</span></code> with arguments931<code class="docutils literal notranslate"><span class="pre">executable</span></code>, <code class="docutils literal notranslate"><span class="pre">args</span></code>, <code class="docutils literal notranslate"><span class="pre">cwd</span></code>, and <code class="docutils literal notranslate"><span class="pre">env</span></code>. The value for <code class="docutils literal notranslate"><span class="pre">args</span></code>932may be a single string or a list of strings, depending on platform.</p>933</p>934<div class="versionchanged">935<p><span class="versionmodified changed">Changed in version 3.2: </span>Added context manager support.</p>936</div>937<div class="versionchanged">938<p><span class="versionmodified changed">Changed in version 3.6: </span>Popen destructor now emits a <a class="reference internal" href="exceptions.html#ResourceWarning" title="ResourceWarning"><code class="xref py py-exc docutils literal notranslate"><span class="pre">ResourceWarning</span></code></a> warning if the child939process is still running.</p>940</div>941<div class="versionchanged">942<p><span class="versionmodified changed">Changed in version 3.8: </span>Popen can use <a class="reference internal" href="os.html#os.posix_spawn" title="os.posix_spawn"><code class="xref py py-func docutils literal notranslate"><span class="pre">os.posix_spawn()</span></code></a> in some cases for better943performance. On Windows Subsystem for Linux and QEMU User Emulation,944Popen constructor using <code class="xref py py-func docutils literal notranslate"><span class="pre">os.posix_spawn()</span></code> no longer raise an945exception on errors like missing program, but the child process fails946with a non-zero <a class="reference internal" href="#subprocess.Popen.returncode" title="subprocess.Popen.returncode"><code class="xref py py-attr docutils literal notranslate"><span class="pre">returncode</span></code></a>.</p>947</div>948</dd></dl>949 950</section>951<section id="exceptions">952<h3>Exceptions<a class="headerlink" href="#exceptions" title="Link to this heading">¶</a></h3>953<p>Exceptions raised in the child process, before the new program has started to954execute, will be re-raised in the parent.</p>955<p>The most common exception raised is <a class="reference internal" href="exceptions.html#OSError" title="OSError"><code class="xref py py-exc docutils literal notranslate"><span class="pre">OSError</span></code></a>.  This occurs, for example,956when trying to execute a non-existent file.  Applications should prepare for957<code class="xref py py-exc docutils literal notranslate"><span class="pre">OSError</span></code> exceptions. Note that, when <code class="docutils literal notranslate"><span class="pre">shell=True</span></code>, <code class="xref py py-exc docutils literal notranslate"><span class="pre">OSError</span></code>958will be raised by the child only if the selected shell itself was not found.959To determine if the shell failed to find the requested application, it is960necessary to check the return code or output from the subprocess.</p>961<p>A <a class="reference internal" href="exceptions.html#ValueError" title="ValueError"><code class="xref py py-exc docutils literal notranslate"><span class="pre">ValueError</span></code></a> will be raised if <a class="reference internal" href="#subprocess.Popen" title="subprocess.Popen"><code class="xref py py-class docutils literal notranslate"><span class="pre">Popen</span></code></a> is called with invalid962arguments.</p>963<p><a class="reference internal" href="#subprocess.check_call" title="subprocess.check_call"><code class="xref py py-func docutils literal notranslate"><span class="pre">check_call()</span></code></a> and <a class="reference internal" href="#subprocess.check_output" title="subprocess.check_output"><code class="xref py py-func docutils literal notranslate"><span class="pre">check_output()</span></code></a> will raise964<a class="reference internal" href="#subprocess.CalledProcessError" title="subprocess.CalledProcessError"><code class="xref py py-exc docutils literal notranslate"><span class="pre">CalledProcessError</span></code></a> if the called process returns a non-zero return965code.</p>966<p>All of the functions and methods that accept a <em>timeout</em> parameter, such as967<a class="reference internal" href="#subprocess.run" title="subprocess.run"><code class="xref py py-func docutils literal notranslate"><span class="pre">run()</span></code></a> and <a class="reference internal" href="#subprocess.Popen.communicate" title="subprocess.Popen.communicate"><code class="xref py py-meth docutils literal notranslate"><span class="pre">Popen.communicate()</span></code></a> will raise <a class="reference internal" href="#subprocess.TimeoutExpired" title="subprocess.TimeoutExpired"><code class="xref py py-exc docutils literal notranslate"><span class="pre">TimeoutExpired</span></code></a> if968the timeout expires before the process exits.</p>969<p>Exceptions defined in this module all inherit from <a class="reference internal" href="#subprocess.SubprocessError" title="subprocess.SubprocessError"><code class="xref py py-exc docutils literal notranslate"><span class="pre">SubprocessError</span></code></a>.</p>970<div class="versionadded">971<p><span class="versionmodified added">Added in version 3.3: </span>The <a class="reference internal" href="#subprocess.SubprocessError" title="subprocess.SubprocessError"><code class="xref py py-exc docutils literal notranslate"><span class="pre">SubprocessError</span></code></a> base class was added.</p>972</div>973</section>974</section>975<section id="security-considerations">976<span id="subprocess-security"></span><h2>Security Considerations<a class="headerlink" href="#security-considerations" title="Link to this heading">¶</a></h2>977<p>Unlike some other popen functions, this library will not978implicitly choose to call a system shell.  This means that all characters,979including shell metacharacters, can safely be passed to child processes.980If the shell is invoked explicitly, via <code class="docutils literal notranslate"><span class="pre">shell=True</span></code>, it is the application’s981responsibility to ensure that all whitespace and metacharacters are982quoted appropriately to avoid983<a class="reference external" href="https://en.wikipedia.org/wiki/Shell_injection#Shell_injection">shell injection</a>984vulnerabilities. On <a class="reference internal" href="shlex.html#shlex-quote-warning"><span class="std std-ref">some platforms</span></a>, it is possible985to use <a class="reference internal" href="shlex.html#shlex.quote" title="shlex.quote"><code class="xref py py-func docutils literal notranslate"><span class="pre">shlex.quote()</span></code></a> for this escaping.</p>986<p>On Windows, batch files (<code class="file docutils literal notranslate"><span class="pre">*.bat</span></code> or <code class="file docutils literal notranslate"><span class="pre">*.cmd</span></code>) may be launched by the987operating system in a system shell regardless of the arguments passed to this988library. This could result in arguments being parsed according to shell rules,989but without any escaping added by Python. If you are intentionally launching a990batch file with arguments from untrusted sources, consider passing991<code class="docutils literal notranslate"><span class="pre">shell=True</span></code> to allow Python to escape special characters. See <a class="reference external" href="https://github.com/python/cpython/issues/114539">gh-114539</a>992for additional discussion.</p>993</section>994<section id="popen-objects">995<h2>Popen Objects<a class="headerlink" href="#popen-objects" title="Link to this heading">¶</a></h2>996<p>Instances of the <a class="reference internal" href="#subprocess.Popen" title="subprocess.Popen"><code class="xref py py-class docutils literal notranslate"><span class="pre">Popen</span></code></a> class have the following methods:</p>997<dl class="py method">998<dt class="sig sig-object py" id="subprocess.Popen.poll">999<span class="sig-prename descclassname"><span class="pre">Popen.</span></span><span class="sig-name descname"><span class="pre">poll</span></span><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#subprocess.Popen.poll" title="Link to this definition">¶</a></dt>1000<dd><p>Check if child process has terminated.  Set and return1001<a class="reference internal" href="#subprocess.Popen.returncode" title="subprocess.Popen.returncode"><code class="xref py py-attr docutils literal notranslate"><span class="pre">returncode</span></code></a> attribute. Otherwise, returns <code class="docutils literal notranslate"><span class="pre">None</span></code>.</p>1002</dd></dl>1003 1004<dl class="py method">1005<dt class="sig sig-object py" id="subprocess.Popen.wait">1006<span class="sig-prename descclassname"><span class="pre">Popen.</span></span><span class="sig-name descname"><span class="pre">wait</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">timeout</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">None</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="#subprocess.Popen.wait" title="Link to this definition">¶</a></dt>1007<dd><p>Wait for child process to terminate.  Set and return1008<a class="reference internal" href="#subprocess.Popen.returncode" title="subprocess.Popen.returncode"><code class="xref py py-attr docutils literal notranslate"><span class="pre">returncode</span></code></a> attribute.</p>1009<p>If the process does not terminate after <em>timeout</em> seconds, raise a1010<a class="reference internal" href="#subprocess.TimeoutExpired" title="subprocess.TimeoutExpired"><code class="xref py py-exc docutils literal notranslate"><span class="pre">TimeoutExpired</span></code></a> exception.  It is safe to catch this exception and1011retry the wait.</p>1012<div class="admonition note">1013<p class="admonition-title">Note</p>1014<p>This will deadlock when using <code class="docutils literal notranslate"><span class="pre">stdout=PIPE</span></code> or <code class="docutils literal notranslate"><span class="pre">stderr=PIPE</span></code>1015and the child process generates enough output to a pipe such that1016it blocks waiting for the OS pipe buffer to accept more data.1017Use <a class="reference internal" href="#subprocess.Popen.communicate" title="subprocess.Popen.communicate"><code class="xref py py-meth docutils literal notranslate"><span class="pre">Popen.communicate()</span></code></a> when using pipes to avoid that.</p>1018</div>1019<div class="admonition note">1020<p class="admonition-title">Note</p>1021<p>When <code class="docutils literal notranslate"><span class="pre">timeout</span></code> is not <code class="docutils literal notranslate"><span class="pre">None</span></code> and the platform supports it, an1022efficient event-driven mechanism is used to wait for process termination:</p>1023<ul class="simple">1024<li><p>Linux &gt;= 5.3 uses <a class="reference internal" href="os.html#os.pidfd_open" title="os.pidfd_open"><code class="xref py py-func docutils literal notranslate"><span class="pre">os.pidfd_open()</span></code></a> + <a class="reference internal" href="select.html#select.poll" title="select.poll"><code class="xref py py-func docutils literal notranslate"><span class="pre">select.poll()</span></code></a></p></li>1025<li><p>macOS and other BSD variants use <a class="reference internal" href="select.html#select.kqueue" title="select.kqueue"><code class="xref py py-func docutils literal notranslate"><span class="pre">select.kqueue()</span></code></a> +1026<code class="docutils literal notranslate"><span class="pre">KQ_FILTER_PROC</span></code> + <code class="docutils literal notranslate"><span class="pre">KQ_NOTE_EXIT</span></code></p></li>1027<li><p>Windows uses <code class="docutils literal notranslate"><span class="pre">WaitForSingleObject</span></code></p></li>1028</ul>1029<p>If none of these mechanisms are available, the function falls back to a1030busy loop (non-blocking call and short sleeps).</p>1031</div>1032<div class="admonition note">1033<p class="admonition-title">Note</p>1034<p>Use the <a class="reference internal" href="asyncio.html#module-asyncio" title="asyncio: Asynchronous I/O."><code class="xref py py-mod docutils literal notranslate"><span class="pre">asyncio</span></code></a> module for an asynchronous wait: see1035<a class="reference internal" href="asyncio-subprocess.html#asyncio.create_subprocess_exec" title="asyncio.create_subprocess_exec"><code class="xref py py-class docutils literal notranslate"><span class="pre">asyncio.create_subprocess_exec</span></code></a>.</p>1036</div>1037<div class="versionchanged">1038<p><span class="versionmodified changed">Changed in version 3.3: </span><em>timeout</em> was added.</p>1039</div>1040<div class="versionchanged">1041<p><span class="versionmodified changed">Changed in version 3.15: </span>if <em>timeout</em> is not <code class="docutils literal notranslate"><span class="pre">None</span></code>, use efficient event-driven implementation1042on Linux &gt;= 5.3 and macOS / BSD.</p>1043</div>1044</dd></dl>1045 1046<dl class="py method">1047<dt class="sig sig-object py" id="subprocess.Popen.communicate">1048<span class="sig-prename descclassname"><span class="pre">Popen.</span></span><span class="sig-name descname"><span class="pre">communicate</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">input</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">None</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">timeout</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">None</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="#subprocess.Popen.communicate" title="Link to this definition">¶</a></dt>1049<dd><p>Interact with process: Send data to stdin.  Read data from stdout and stderr,1050until end-of-file is reached.  Wait for process to terminate and set the1051<a class="reference internal" href="#subprocess.Popen.returncode" title="subprocess.Popen.returncode"><code class="xref py py-attr docutils literal notranslate"><span class="pre">returncode</span></code></a> attribute.  The optional <em>input</em> argument should be1052data to be sent to the child process, or <code class="docutils literal notranslate"><span class="pre">None</span></code>, if no data should be sent1053to the child.  If streams were opened in text mode, <em>input</em> must be a string.1054Otherwise, it must be bytes.</p>1055<p><code class="xref py py-meth docutils literal notranslate"><span class="pre">communicate()</span></code> returns a tuple <code class="docutils literal notranslate"><span class="pre">(stdout_data,</span> <span class="pre">stderr_data)</span></code>.1056The data will be strings if streams were opened in text mode; otherwise,1057bytes.</p>1058<p>Note that if you want to send data to the process’s stdin, you need to create1059the Popen object with <code class="docutils literal notranslate"><span class="pre">stdin=PIPE</span></code>.  Similarly, to get anything other than1060<code class="docutils literal notranslate"><span class="pre">None</span></code> in the result tuple, you need to give <code class="docutils literal notranslate"><span class="pre">stdout=PIPE</span></code> and/or1061<code class="docutils literal notranslate"><span class="pre">stderr=PIPE</span></code> too.</p>1062<p>If the process does not terminate after <em>timeout</em> seconds, a1063<a class="reference internal" href="#subprocess.TimeoutExpired" title="subprocess.TimeoutExpired"><code class="xref py py-exc docutils literal notranslate"><span class="pre">TimeoutExpired</span></code></a> exception will be raised.  Catching this exception and1064retrying communication will not lose any output.  Supplying <em>input</em> to a1065subsequent post-timeout <code class="xref py py-meth docutils literal notranslate"><span class="pre">communicate()</span></code> call is in undefined behavior1066and may become an error in the future.</p>1067<p>The child process is not killed if the timeout expires, so in order to1068cleanup properly a well-behaved application should kill the child process and1069finish communication:</p>1070<div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="n">proc</span> <span class="o">=</span> <span class="n">subprocess</span><span class="o">.</span><span class="n">Popen</span><span class="p">(</span><span class="o">...</span><span class="p">)</span>1071<span class="k">try</span><span class="p">:</span>1072    <span class="n">outs</span><span class="p">,</span> <span class="n">errs</span> <span class="o">=</span> <span class="n">proc</span><span class="o">.</span><span class="n">communicate</span><span class="p">(</span><span class="n">timeout</span><span class="o">=</span><span class="mi">15</span><span class="p">)</span>1073<span class="k">except</span> <span class="n">TimeoutExpired</span><span class="p">:</span>1074    <span class="n">proc</span><span class="o">.</span><span class="n">kill</span><span class="p">()</span>1075    <span class="n">outs</span><span class="p">,</span> <span class="n">errs</span> <span class="o">=</span> <span class="n">proc</span><span class="o">.</span><span class="n">communicate</span><span class="p">()</span>1076</pre></div>1077</div>1078<p>After a call to <code class="xref py py-meth docutils literal notranslate"><span class="pre">communicate()</span></code> raises <a class="reference internal" href="#subprocess.TimeoutExpired" title="subprocess.TimeoutExpired"><code class="xref py py-exc docutils literal notranslate"><span class="pre">TimeoutExpired</span></code></a>, do1079not call <a class="reference internal" href="#subprocess.Popen.wait" title="subprocess.Popen.wait"><code class="xref py py-meth docutils literal notranslate"><span class="pre">wait()</span></code></a>. Use an additional <code class="xref py py-meth docutils literal notranslate"><span class="pre">communicate()</span></code>1080call to finish handling pipes and populate the <a class="reference internal" href="#subprocess.Popen.returncode" title="subprocess.Popen.returncode"><code class="xref py py-attr docutils literal notranslate"><span class="pre">returncode</span></code></a>1081attribute.</p>1082<div class="admonition note">1083<p class="admonition-title">Note</p>1084<p>The data read is buffered in memory, so do not use this method if the data1085size is large or unlimited.</p>1086</div>1087<div class="versionchanged">1088<p><span class="versionmodified changed">Changed in version 3.3: </span><em>timeout</em> was added.</p>1089</div>1090</dd></dl>1091 1092<dl class="py method">1093<dt class="sig sig-object py" id="subprocess.Popen.send_signal">1094<span class="sig-prename descclassname"><span class="pre">Popen.</span></span><span class="sig-name descname"><span class="pre">send_signal</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">signal</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="#subprocess.Popen.send_signal" title="Link to this definition">¶</a></dt>1095<dd><p>Sends the signal <em>signal</em> to the child.</p>1096<p>Do nothing if the process completed.</p>1097<div class="admonition note">1098<p class="admonition-title">Note</p>1099<p>On Windows, SIGTERM is an alias for <a class="reference internal" href="#subprocess.Popen.terminate" title="subprocess.Popen.terminate"><code class="xref py py-meth docutils literal notranslate"><span class="pre">terminate()</span></code></a>. CTRL_C_EVENT and1100CTRL_BREAK_EVENT can be sent to processes started with a <em>creationflags</em>1101parameter which includes <code class="docutils literal notranslate"><span class="pre">CREATE_NEW_PROCESS_GROUP</span></code>.</p>1102</div>1103</dd></dl>1104 1105<dl class="py method">1106<dt class="sig sig-object py" id="subprocess.Popen.terminate">1107<span class="sig-prename descclassname"><span class="pre">Popen.</span></span><span class="sig-name descname"><span class="pre">terminate</span></span><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#subprocess.Popen.terminate" title="Link to this definition">¶</a></dt>1108<dd><p>Stop the child. On POSIX OSs the method sends <a class="reference internal" href="signal.html#signal.SIGTERM" title="signal.SIGTERM"><code class="xref py py-const docutils literal notranslate"><span class="pre">SIGTERM</span></code></a> to the1109child. On Windows the Win32 API function <code class="xref c c-func docutils literal notranslate"><span class="pre">TerminateProcess()</span></code> is called1110to stop the child.</p>1111</dd></dl>1112 1113<dl class="py method">1114<dt class="sig sig-object py" id="subprocess.Popen.kill">1115<span class="sig-prename descclassname"><span class="pre">Popen.</span></span><span class="sig-name descname"><span class="pre">kill</span></span><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#subprocess.Popen.kill" title="Link to this definition">¶</a></dt>1116<dd><p>Kills the child. On POSIX OSs the function sends SIGKILL to the child.1117On Windows <code class="xref py py-meth docutils literal notranslate"><span class="pre">kill()</span></code> is an alias for <a class="reference internal" href="#subprocess.Popen.terminate" title="subprocess.Popen.terminate"><code class="xref py py-meth docutils literal notranslate"><span class="pre">terminate()</span></code></a>.</p>1118</dd></dl>1119 1120<p>The following attributes are also set by the class for you to access.1121Reassigning them to new values is unsupported:</p>1122<dl class="py attribute">1123<dt class="sig sig-object py" id="subprocess.Popen.args">1124<span class="sig-prename descclassname"><span class="pre">Popen.</span></span><span class="sig-name descname"><span class="pre">args</span></span><a class="headerlink" href="#subprocess.Popen.args" title="Link to this definition">¶</a></dt>1125<dd><p>The <em>args</em> argument as it was passed to <a class="reference internal" href="#subprocess.Popen" title="subprocess.Popen"><code class="xref py py-class docutils literal notranslate"><span class="pre">Popen</span></code></a> – a1126sequence of program arguments or else a single string.</p>1127<div class="versionadded">1128<p><span class="versionmodified added">Added in version 3.3.</span></p>1129</div>1130</dd></dl>1131 1132<dl class="py attribute">1133<dt class="sig sig-object py" id="subprocess.Popen.stdin">1134<span class="sig-prename descclassname"><span class="pre">Popen.</span></span><span class="sig-name descname"><span class="pre">stdin</span></span><a class="headerlink" href="#subprocess.Popen.stdin" title="Link to this definition">¶</a></dt>1135<dd><p>If the <em>stdin</em> argument was <a class="reference internal" href="#subprocess.PIPE" title="subprocess.PIPE"><code class="xref py py-data docutils literal notranslate"><span class="pre">PIPE</span></code></a>, this attribute is a writeable1136stream object as returned by <a class="reference internal" href="functions.html#open" title="open"><code class="xref py py-func docutils literal notranslate"><span class="pre">open()</span></code></a>. If the <em>encoding</em> or <em>errors</em>1137arguments were specified or the <em>text</em> or <em>universal_newlines</em> argument1138was <code class="docutils literal notranslate"><span class="pre">True</span></code>, the stream is a text stream, otherwise it is a byte stream.1139If the <em>stdin</em> argument was not <code class="xref py py-data docutils literal notranslate"><span class="pre">PIPE</span></code>, this attribute is <code class="docutils literal notranslate"><span class="pre">None</span></code>.</p>1140</dd></dl>1141 1142<dl class="py attribute">1143<dt class="sig sig-object py" id="subprocess.Popen.stdout">1144<span class="sig-prename descclassname"><span class="pre">Popen.</span></span><span class="sig-name descname"><span class="pre">stdout</span></span><a class="headerlink" href="#subprocess.Popen.stdout" title="Link to this definition">¶</a></dt>1145<dd><p>If the <em>stdout</em> argument was <a class="reference internal" href="#subprocess.PIPE" title="subprocess.PIPE"><code class="xref py py-data docutils literal notranslate"><span class="pre">PIPE</span></code></a>, this attribute is a readable1146stream object as returned by <a class="reference internal" href="functions.html#open" title="open"><code class="xref py py-func docutils literal notranslate"><span class="pre">open()</span></code></a>. Reading from the stream provides1147output from the child process. If the <em>encoding</em> or <em>errors</em> arguments were1148specified or the <em>text</em> or <em>universal_newlines</em> argument was <code class="docutils literal notranslate"><span class="pre">True</span></code>, the1149stream is a text stream, otherwise it is a byte stream. If the <em>stdout</em>1150argument was not <code class="xref py py-data docutils literal notranslate"><span class="pre">PIPE</span></code>, this attribute is <code class="docutils literal notranslate"><span class="pre">None</span></code>.</p>1151</dd></dl>1152 1153<dl class="py attribute">1154<dt class="sig sig-object py" id="subprocess.Popen.stderr">1155<span class="sig-prename descclassname"><span class="pre">Popen.</span></span><span class="sig-name descname"><span class="pre">stderr</span></span><a class="headerlink" href="#subprocess.Popen.stderr" title="Link to this definition">¶</a></dt>1156<dd><p>If the <em>stderr</em> argument was <a class="reference internal" href="#subprocess.PIPE" title="subprocess.PIPE"><code class="xref py py-data docutils literal notranslate"><span class="pre">PIPE</span></code></a>, this attribute is a readable1157stream object as returned by <a class="reference internal" href="functions.html#open" title="open"><code class="xref py py-func docutils literal notranslate"><span class="pre">open()</span></code></a>. Reading from the stream provides1158error output from the child process. If the <em>encoding</em> or <em>errors</em> arguments1159were specified or the <em>text</em> or <em>universal_newlines</em> argument was <code class="docutils literal notranslate"><span class="pre">True</span></code>, the1160stream is a text stream, otherwise it is a byte stream. If the <em>stderr</em> argument1161was not <code class="xref py py-data docutils literal notranslate"><span class="pre">PIPE</span></code>, this attribute is <code class="docutils literal notranslate"><span class="pre">None</span></code>.</p>1162</dd></dl>1163 1164<div class="admonition warning">1165<p class="admonition-title">Warning</p>1166<p>Use <a class="reference internal" href="#subprocess.Popen.communicate" title="subprocess.Popen.communicate"><code class="xref py py-meth docutils literal notranslate"><span class="pre">communicate()</span></code></a> rather than <a class="reference internal" href="#subprocess.Popen.stdin" title="subprocess.Popen.stdin"><code class="xref py py-attr docutils literal notranslate"><span class="pre">.stdin.write</span></code></a>,1167<a class="reference internal" href="#subprocess.Popen.stdout" title="subprocess.Popen.stdout"><code class="xref py py-attr docutils literal notranslate"><span class="pre">.stdout.read</span></code></a> or <a class="reference internal" href="#subprocess.Popen.stderr" title="subprocess.Popen.stderr"><code class="xref py py-attr docutils literal notranslate"><span class="pre">.stderr.read</span></code></a> to avoid1168deadlocks due to any of the other OS pipe buffers filling up and blocking the1169child process.</p>1170</div>1171<dl class="py attribute">1172<dt class="sig sig-object py" id="subprocess.Popen.pid">1173<span class="sig-prename descclassname"><span class="pre">Popen.</span></span><span class="sig-name descname"><span class="pre">pid</span></span><a class="headerlink" href="#subprocess.Popen.pid" title="Link to this definition">¶</a></dt>1174<dd><p>The process ID of the child process.</p>1175<p>Note that if you set the <em>shell</em> argument to <code class="docutils literal notranslate"><span class="pre">True</span></code>, this is the process ID1176of the spawned shell.</p>1177</dd></dl>1178 1179<dl class="py attribute">1180<dt class="sig sig-object py" id="subprocess.Popen.returncode">1181<span class="sig-prename descclassname"><span class="pre">Popen.</span></span><span class="sig-name descname"><span class="pre">returncode</span></span><a class="headerlink" href="#subprocess.Popen.returncode" title="Link to this definition">¶</a></dt>1182<dd><p>The child return code. Initially <code class="docutils literal notranslate"><span class="pre">None</span></code>, <a class="reference internal" href="#subprocess.Popen.returncode" title="subprocess.Popen.returncode"><code class="xref py py-attr docutils literal notranslate"><span class="pre">returncode</span></code></a> is set by1183a call to the <a class="reference internal" href="#subprocess.Popen.poll" title="subprocess.Popen.poll"><code class="xref py py-meth docutils literal notranslate"><span class="pre">poll()</span></code></a>, <a class="reference internal" href="#subprocess.Popen.wait" title="subprocess.Popen.wait"><code class="xref py py-meth docutils literal notranslate"><span class="pre">wait()</span></code></a>, or <a class="reference internal" href="#subprocess.Popen.communicate" title="subprocess.Popen.communicate"><code class="xref py py-meth docutils literal notranslate"><span class="pre">communicate()</span></code></a> methods1184if they detect that the process has terminated.</p>1185<p>A <code class="docutils literal notranslate"><span class="pre">None</span></code> value indicates that the process hadn’t yet terminated at the1186time of the last method call.</p>1187<p>A negative value <code class="docutils literal notranslate"><span class="pre">-N</span></code> indicates that the child was terminated by signal1188<code class="docutils literal notranslate"><span class="pre">N</span></code> (POSIX only).</p>1189</dd></dl>1190 1191</section>1192<section id="windows-popen-helpers">1193<h2>Windows Popen Helpers<a class="headerlink" href="#windows-popen-helpers" title="Link to this heading">¶</a></h2>1194<p>The <a class="reference internal" href="#subprocess.STARTUPINFO" title="subprocess.STARTUPINFO"><code class="xref py py-class docutils literal notranslate"><span class="pre">STARTUPINFO</span></code></a> class and following constants are only available1195on Windows.</p>1196<dl class="py class">1197<dt class="sig sig-object py" id="subprocess.STARTUPINFO">1198<em class="property"><span class="k"><span class="pre">class</span></span><span class="w"> </span></em><span class="sig-prename descclassname"><span class="pre">subprocess.</span></span><span class="sig-name descname"><span class="pre">STARTUPINFO</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="keyword-only-separator o"><abbr title="Keyword-only parameters separator (PEP 3102)"><span class="pre">*</span></abbr></span></em>, <em class="sig-param"><span class="n"><span class="pre">dwFlags</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">0</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">hStdInput</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">None</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">hStdOutput</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">None</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">hStdError</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">None</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">wShowWindow</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">0</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">lpAttributeList</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">None</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="#subprocess.STARTUPINFO" title="Link to this definition">¶</a></dt>1199<dd><p>Partial support of the Windows1200<a class="reference external" href="https://msdn.microsoft.com/en-us/library/ms686331(v=vs.85).aspx">STARTUPINFO</a>

Showing the first 1,200 of 2039 lines. Download the file for the rest.