parthtamu/rag-code-assistant
0
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="argparse — Parser for command-line options, arguments and subcommands" />8<meta property="og:type" content="website" />9<meta property="og:url" content="https://docs.python.org/3/library/argparse.html" />10<meta property="og:site_name" content="Python documentation" />11<meta property="og:description" content="Source code: Lib/argparse.py Tutorial: This page contains the API reference information. For a more gentle introduction to Python command-line parsing, have a look at the argparse tutorial. The arg..." />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_argparse_3f064f33.png" />15<meta property="og:image:alt" content="Source code: Lib/argparse.py Tutorial: This page contains the API reference information. For a more gentle introduction to Python command-line parsing, have a look at the argparse tutorial. The arg..." />16<meta name="description" content="Source code: Lib/argparse.py Tutorial: This page contains the API reference information. For a more gentle introduction to Python command-line parsing, have a look at the argparse tutorial. The arg..." />17<meta name="twitter:card" content="summary_large_image" />18<meta name="theme-color" content="#3776ab">19 20 <title>argparse — Parser for command-line options, arguments and subcommands — 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="Argparse Tutorial" href="../howto/argparse.html" />43 <link rel="prev" title="Command-line interface libraries" href="cmdlinelibs.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/argparse.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">argparse</span></code> — Parser for command-line options, arguments and subcommands</a><ul>108<li><a class="reference internal" href="#argumentparser-objects">ArgumentParser objects</a><ul>109<li><a class="reference internal" href="#prog">prog</a></li>110<li><a class="reference internal" href="#usage">usage</a></li>111<li><a class="reference internal" href="#description">description</a></li>112<li><a class="reference internal" href="#epilog">epilog</a></li>113<li><a class="reference internal" href="#parents">parents</a></li>114<li><a class="reference internal" href="#formatter-class">formatter_class</a></li>115<li><a class="reference internal" href="#prefix-chars">prefix_chars</a></li>116<li><a class="reference internal" href="#fromfile-prefix-chars">fromfile_prefix_chars</a></li>117<li><a class="reference internal" href="#argument-default">argument_default</a></li>118<li><a class="reference internal" href="#allow-abbrev">allow_abbrev</a></li>119<li><a class="reference internal" href="#conflict-handler">conflict_handler</a></li>120<li><a class="reference internal" href="#add-help">add_help</a></li>121<li><a class="reference internal" href="#exit-on-error">exit_on_error</a></li>122<li><a class="reference internal" href="#suggest-on-error">suggest_on_error</a></li>123<li><a class="reference internal" href="#color">color</a></li>124</ul>125</li>126<li><a class="reference internal" href="#the-add-argument-method">The add_argument() method</a><ul>127<li><a class="reference internal" href="#name-or-flags">name or flags</a></li>128<li><a class="reference internal" href="#action">action</a></li>129<li><a class="reference internal" href="#nargs">nargs</a></li>130<li><a class="reference internal" href="#const">const</a></li>131<li><a class="reference internal" href="#default">default</a></li>132<li><a class="reference internal" href="#type">type</a></li>133<li><a class="reference internal" href="#choices">choices</a></li>134<li><a class="reference internal" href="#required">required</a></li>135<li><a class="reference internal" href="#help">help</a></li>136<li><a class="reference internal" href="#metavar">metavar</a></li>137<li><a class="reference internal" href="#dest">dest</a></li>138<li><a class="reference internal" href="#deprecated">deprecated</a></li>139<li><a class="reference internal" href="#action-classes">Action classes</a></li>140</ul>141</li>142<li><a class="reference internal" href="#the-parse-args-method">The parse_args() method</a><ul>143<li><a class="reference internal" href="#option-value-syntax">Option value syntax</a></li>144<li><a class="reference internal" href="#invalid-arguments">Invalid arguments</a></li>145<li><a class="reference internal" href="#arguments-containing">Arguments containing <code class="docutils literal notranslate"><span class="pre">-</span></code></a></li>146<li><a class="reference internal" href="#argument-abbreviations-prefix-matching">Argument abbreviations (prefix matching)</a></li>147<li><a class="reference internal" href="#beyond-sys-argv">Beyond <code class="docutils literal notranslate"><span class="pre">sys.argv</span></code></a></li>148<li><a class="reference internal" href="#the-namespace-object">The Namespace object</a></li>149</ul>150</li>151<li><a class="reference internal" href="#other-utilities">Other utilities</a><ul>152<li><a class="reference internal" href="#subcommands">Subcommands</a></li>153<li><a class="reference internal" href="#filetype-objects">FileType objects</a></li>154<li><a class="reference internal" href="#argument-groups">Argument groups</a></li>155<li><a class="reference internal" href="#mutual-exclusion">Mutual exclusion</a></li>156<li><a class="reference internal" href="#parser-defaults">Parser defaults</a></li>157<li><a class="reference internal" href="#printing-help">Printing help</a></li>158<li><a class="reference internal" href="#partial-parsing">Partial parsing</a></li>159<li><a class="reference internal" href="#customizing-file-parsing">Customizing file parsing</a></li>160<li><a class="reference internal" href="#exiting-methods">Exiting methods</a></li>161<li><a class="reference internal" href="#intermixed-parsing">Intermixed parsing</a></li>162<li><a class="reference internal" href="#registering-custom-types-or-actions">Registering custom types or actions</a></li>163</ul>164</li>165<li><a class="reference internal" href="#exceptions">Exceptions</a></li>166</ul>167</li>168</ul>169 170 </div>171 <div>172 <h4>Previous topic</h4>173 <p class="topless"><a href="cmdlinelibs.html"174 title="previous chapter">Command-line interface libraries</a></p>175 </div>176 <div>177 <h4>Next topic</h4>178 <p class="topless"><a href="../howto/argparse.html"179 title="next chapter">Argparse Tutorial</a></p>180 </div>181 <script>182 document.addEventListener('DOMContentLoaded', () => {183 const title = document.querySelector('meta[property="og:title"]').content;184 const elements = document.querySelectorAll('.improvepage');185 const pageurl = window.location.href.split('?')[0];186 elements.forEach(element => {187 const url = new URL(element.href.split('?')[0].replace("-nojs", ""));188 url.searchParams.set('pagetitle', title);189 url.searchParams.set('pageurl', pageurl);190 url.searchParams.set('pagesource', "library/argparse.rst");191 element.href = url.toString();192 });193 });194 </script>195 <div role="note" aria-label="source link">196 <h3>This page</h3>197 <ul class="this-page-menu">198 <li><a href="../bugs.html">Report a bug</a></li>199 <li><a class="improvepage" href="../improve-page-nojs.html">Improve this page</a></li>200 <li>201 <a href="https://github.com/python/cpython/blob/main/Doc/library/argparse.rst?plain=1"202 rel="nofollow">Show source203 </a>204 </li>205 206 </ul>207 </div>208 </nav>209 </div>210</div>211 212 213 <div class="related" role="navigation" aria-label="Related">214 <h3>Navigation</h3>215 <ul>216 <li class="right" style="margin-right: 10px">217 <a href="../genindex.html" title="General Index"218 accesskey="I">index</a></li>219 <li class="right" >220 <a href="../py-modindex.html" title="Python Module Index"221 >modules</a> |</li>222 <li class="right" >223 <a href="../howto/argparse.html" title="Argparse Tutorial"224 accesskey="N">next</a> |</li>225 <li class="right" >226 <a href="cmdlinelibs.html" title="Command-line interface libraries"227 accesskey="P">previous</a> |</li>228 229 <li><img src="../_static/py.svg" alt="Python logo" style="vertical-align: middle; margin-top: -1px"></li>230 <li><a href="https://www.python.org/">Python</a> »</li>231 <li class="switchers">232 <div class="language_switcher_placeholder"></div>233 <div class="version_switcher_placeholder"></div>234 </li>235 <li>236 237 </li>238 <li id="cpython-language-and-version">239 <a href="../index.html">3.15.0a6 Documentation</a> »240 </li>241 242 <li class="nav-item nav-item-1"><a href="index.html" >The Python Standard Library</a> »</li>243 <li class="nav-item nav-item-2"><a href="cmdlinelibs.html" accesskey="U">Command-line interface libraries</a> »</li>244 <li class="nav-item nav-item-this"><a href=""><code class="xref py py-mod docutils literal notranslate"><span class="pre">argparse</span></code> — Parser for command-line options, arguments and subcommands</a></li>245 <li class="right">246 247 248 <div class="inline-search" role="search">249 <form class="inline-search" action="../search.html" method="get">250 <input placeholder="Quick search" aria-label="Quick search" type="search" name="q" id="search-box">251 <input type="submit" value="Go">252 </form>253 </div>254 |255 </li>256 <li class="right">257<label class="theme-selector-label">258 Theme259 <select class="theme-selector" oninput="activateTheme(this.value)">260 <option value="auto" selected>Auto</option>261 <option value="light">Light</option>262 <option value="dark">Dark</option>263 </select>264</label> |</li>265 266 </ul>267 </div> 268 269 <div class="document">270 <div class="documentwrapper">271 <div class="bodywrapper">272 <div class="body" role="main">273 274 <section id="module-argparse">275<span id="argparse-parser-for-command-line-options-arguments-and-subcommands"></span><h1><code class="xref py py-mod docutils literal notranslate"><span class="pre">argparse</span></code> — Parser for command-line options, arguments and subcommands<a class="headerlink" href="#module-argparse" title="Link to this heading">¶</a></h1>276<div class="versionadded">277<p><span class="versionmodified added">Added in version 3.2.</span></p>278</div>279<p><strong>Source code:</strong> <a class="extlink-source reference external" href="https://github.com/python/cpython/tree/main/Lib/argparse.py">Lib/argparse.py</a></p>280<div class="admonition note">281<p class="admonition-title">Note</p>282<p>While <code class="xref py py-mod docutils literal notranslate"><span class="pre">argparse</span></code> is the default recommended standard library module283for implementing basic command line applications, authors with more284exacting requirements for exactly how their command line applications285behave may find it doesn’t provide the necessary level of control.286Refer to <a class="reference internal" href="optparse.html#choosing-an-argument-parser"><span class="std std-ref">Choosing an argument parsing library</span></a> for alternatives to287consider when <code class="docutils literal notranslate"><span class="pre">argparse</span></code> doesn’t support behaviors that the application288requires (such as entirely disabling support for interspersed options and289positional arguments, or accepting option parameter values that start290with <code class="docutils literal notranslate"><span class="pre">-</span></code> even when they correspond to another defined option).</p>291</div>292<hr class="docutils" />293<aside class="sidebar">294<p class="sidebar-title">Tutorial</p>295<p>This page contains the API reference information. For a more gentle296introduction to Python command-line parsing, have a look at the297<a class="reference internal" href="../howto/argparse.html#argparse-tutorial"><span class="std std-ref">argparse tutorial</span></a>.</p>298</aside>299<p>The <code class="xref py py-mod docutils literal notranslate"><span class="pre">argparse</span></code> module makes it easy to write user-friendly command-line300interfaces. The program defines what arguments it requires, and <code class="xref py py-mod docutils literal notranslate"><span class="pre">argparse</span></code>301will figure out how to parse those out of <a class="reference internal" href="sys.html#sys.argv" title="sys.argv"><code class="xref py py-data docutils literal notranslate"><span class="pre">sys.argv</span></code></a>. The <code class="xref py py-mod docutils literal notranslate"><span class="pre">argparse</span></code>302module also automatically generates help and usage messages. The module303will also issue errors when users give the program invalid arguments.</p>304<p>The <code class="xref py py-mod docutils literal notranslate"><span class="pre">argparse</span></code> module’s support for command-line interfaces is built305around an instance of <a class="reference internal" href="#argparse.ArgumentParser" title="argparse.ArgumentParser"><code class="xref py py-class docutils literal notranslate"><span class="pre">argparse.ArgumentParser</span></code></a>. It is a container for306argument specifications and has options that apply to the parser as whole:</p>307<div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="n">parser</span> <span class="o">=</span> <span class="n">argparse</span><span class="o">.</span><span class="n">ArgumentParser</span><span class="p">(</span>308 <span class="n">prog</span><span class="o">=</span><span class="s1">'ProgramName'</span><span class="p">,</span>309 <span class="n">description</span><span class="o">=</span><span class="s1">'What the program does'</span><span class="p">,</span>310 <span class="n">epilog</span><span class="o">=</span><span class="s1">'Text at the bottom of help'</span><span class="p">)</span>311</pre></div>312</div>313<p>The <a class="reference internal" href="#argparse.ArgumentParser.add_argument" title="argparse.ArgumentParser.add_argument"><code class="xref py py-meth docutils literal notranslate"><span class="pre">ArgumentParser.add_argument()</span></code></a> method attaches individual argument314specifications to the parser. It supports positional arguments, options that315accept values, and on/off flags:</p>316<div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="n">parser</span><span class="o">.</span><span class="n">add_argument</span><span class="p">(</span><span class="s1">'filename'</span><span class="p">)</span> <span class="c1"># positional argument</span>317<span class="n">parser</span><span class="o">.</span><span class="n">add_argument</span><span class="p">(</span><span class="s1">'-c'</span><span class="p">,</span> <span class="s1">'--count'</span><span class="p">)</span> <span class="c1"># option that takes a value</span>318<span class="n">parser</span><span class="o">.</span><span class="n">add_argument</span><span class="p">(</span><span class="s1">'-v'</span><span class="p">,</span> <span class="s1">'--verbose'</span><span class="p">,</span>319 <span class="n">action</span><span class="o">=</span><span class="s1">'store_true'</span><span class="p">)</span> <span class="c1"># on/off flag</span>320</pre></div>321</div>322<p>The <a class="reference internal" href="#argparse.ArgumentParser.parse_args" title="argparse.ArgumentParser.parse_args"><code class="xref py py-meth docutils literal notranslate"><span class="pre">ArgumentParser.parse_args()</span></code></a> method runs the parser and places323the extracted data in a <a class="reference internal" href="#argparse.Namespace" title="argparse.Namespace"><code class="xref py py-class docutils literal notranslate"><span class="pre">argparse.Namespace</span></code></a> object:</p>324<div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="n">args</span> <span class="o">=</span> <span class="n">parser</span><span class="o">.</span><span class="n">parse_args</span><span class="p">()</span>325<span class="nb">print</span><span class="p">(</span><span class="n">args</span><span class="o">.</span><span class="n">filename</span><span class="p">,</span> <span class="n">args</span><span class="o">.</span><span class="n">count</span><span class="p">,</span> <span class="n">args</span><span class="o">.</span><span class="n">verbose</span><span class="p">)</span>326</pre></div>327</div>328<div class="admonition note">329<p class="admonition-title">Note</p>330<p>If you’re looking for a guide about how to upgrade <a class="reference internal" href="optparse.html#module-optparse" title="optparse: Command-line option parsing library."><code class="xref py py-mod docutils literal notranslate"><span class="pre">optparse</span></code></a> code331to <code class="xref py py-mod docutils literal notranslate"><span class="pre">argparse</span></code>, see <a class="reference internal" href="../howto/argparse-optparse.html#upgrading-optparse-code"><span class="std std-ref">Upgrading Optparse Code</span></a>.</p>332</div>333<section id="argumentparser-objects">334<h2>ArgumentParser objects<a class="headerlink" href="#argumentparser-objects" title="Link to this heading">¶</a></h2>335<dl class="py class">336<dt class="sig sig-object py" id="argparse.ArgumentParser">337<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">argparse.</span></span><span class="sig-name descname"><span class="pre">ArgumentParser</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">prog</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">usage</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">description</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">epilog</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">parents</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="n"><span class="pre">formatter_class</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">argparse.HelpFormatter</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">prefix_chars</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="n"><span class="pre">fromfile_prefix_chars</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">argument_default</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">conflict_handler</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">'error'</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">add_help</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">allow_abbrev</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">exit_on_error</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="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">suggest_on_error</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">color</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">True</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="#argparse.ArgumentParser" title="Link to this definition">¶</a></dt>338<dd><p>Create a new <code class="xref py py-class docutils literal notranslate"><span class="pre">ArgumentParser</span></code> object. All parameters should be passed339as keyword arguments. Each parameter has its own more detailed description340below, but in short they are:</p>341<ul class="simple">342<li><p><a class="reference internal" href="#prog">prog</a> - The name of the program (default: generated from the <code class="docutils literal notranslate"><span class="pre">__main__</span></code>343module attributes and <code class="docutils literal notranslate"><span class="pre">sys.argv[0]</span></code>)</p></li>344<li><p><a class="reference internal" href="#usage">usage</a> - The string describing the program usage (default: generated from345arguments added to parser)</p></li>346<li><p><a class="reference internal" href="#description">description</a> - Text to display before the argument help347(by default, no text)</p></li>348<li><p><a class="reference internal" href="#epilog">epilog</a> - Text to display after the argument help (by default, no text)</p></li>349<li><p><a class="reference internal" href="#parents">parents</a> - A list of <code class="xref py py-class docutils literal notranslate"><span class="pre">ArgumentParser</span></code> objects whose arguments should350also be included</p></li>351<li><p><a class="reference internal" href="#formatter-class">formatter_class</a> - A class for customizing the help output</p></li>352<li><p><a class="reference internal" href="#prefix-chars">prefix_chars</a> - The set of characters that prefix optional arguments353(default: ‘-‘)</p></li>354<li><p><a class="reference internal" href="#fromfile-prefix-chars">fromfile_prefix_chars</a> - The set of characters that prefix files from355which additional arguments should be read (default: <code class="docutils literal notranslate"><span class="pre">None</span></code>)</p></li>356<li><p><a class="reference internal" href="#argument-default">argument_default</a> - The global default value for arguments357(default: <code class="docutils literal notranslate"><span class="pre">None</span></code>)</p></li>358<li><p><a class="reference internal" href="#conflict-handler">conflict_handler</a> - The strategy for resolving conflicting optionals359(usually unnecessary)</p></li>360<li><p><a class="reference internal" href="#add-help">add_help</a> - Add a <code class="docutils literal notranslate"><span class="pre">-h/--help</span></code> option to the parser (default: <code class="docutils literal notranslate"><span class="pre">True</span></code>)</p></li>361<li><p><a class="reference internal" href="#allow-abbrev">allow_abbrev</a> - Allows long options to be abbreviated if the362abbreviation is unambiguous (default: <code class="docutils literal notranslate"><span class="pre">True</span></code>)</p></li>363<li><p><a class="reference internal" href="#exit-on-error">exit_on_error</a> - Determines whether or not <code class="xref py py-class docutils literal notranslate"><span class="pre">ArgumentParser</span></code> exits with364error info when an error occurs. (default: <code class="docutils literal notranslate"><span class="pre">True</span></code>)</p></li>365<li><p><a class="reference internal" href="#suggest-on-error">suggest_on_error</a> - Enables suggestions for mistyped argument choices366and subparser names (default: <code class="docutils literal notranslate"><span class="pre">True</span></code>)</p></li>367<li><p><a class="reference internal" href="#color">color</a> - Allow color output (default: <code class="docutils literal notranslate"><span class="pre">True</span></code>)</p></li>368</ul>369<div class="versionchanged">370<p><span class="versionmodified changed">Changed in version 3.5: </span><em>allow_abbrev</em> parameter was added.</p>371</div>372<div class="versionchanged">373<p><span class="versionmodified changed">Changed in version 3.8: </span>In previous versions, <em>allow_abbrev</em> also disabled grouping of short374flags such as <code class="docutils literal notranslate"><span class="pre">-vv</span></code> to mean <code class="docutils literal notranslate"><span class="pre">-v</span> <span class="pre">-v</span></code>.</p>375</div>376<div class="versionchanged">377<p><span class="versionmodified changed">Changed in version 3.9: </span><em>exit_on_error</em> parameter was added.</p>378</div>379<div class="versionchanged">380<p><span class="versionmodified changed">Changed in version 3.14: </span><em>suggest_on_error</em> and <em>color</em> parameters were added.</p>381</div>382<div class="versionchanged">383<p><span class="versionmodified changed">Changed in version 3.15: </span><em>suggest_on_error</em> default changed to <code class="docutils literal notranslate"><span class="pre">True</span></code>.</p>384</div>385</dd></dl>386 387<p>The following sections describe how each of these are used.</p>388<section id="prog">389<span id="id1"></span><h3>prog<a class="headerlink" href="#prog" title="Link to this heading">¶</a></h3>390<p>By default, <a class="reference internal" href="#argparse.ArgumentParser" title="argparse.ArgumentParser"><code class="xref py py-class docutils literal notranslate"><span class="pre">ArgumentParser</span></code></a> calculates the name of the program391to display in help messages depending on the way the Python interpreter was run:</p>392<ul class="simple">393<li><p>The <a class="reference internal" href="os.path.html#os.path.basename" title="os.path.basename"><code class="xref py py-func docutils literal notranslate"><span class="pre">base</span> <span class="pre">name</span></code></a> of <code class="docutils literal notranslate"><span class="pre">sys.argv[0]</span></code> if a file was394passed as argument.</p></li>395<li><p>The Python interpreter name followed by <code class="docutils literal notranslate"><span class="pre">sys.argv[0]</span></code> if a directory or396a zipfile was passed as argument.</p></li>397<li><p>The Python interpreter name followed by <code class="docutils literal notranslate"><span class="pre">-m</span></code> followed by the398module or package name if the <a class="reference internal" href="../using/cmdline.html#cmdoption-m"><code class="xref std std-option docutils literal notranslate"><span class="pre">-m</span></code></a> option was used.</p></li>399</ul>400<p>This default is almost always desirable because it will make the help messages401match the string that was used to invoke the program on the command line.402However, to change this default behavior, another value can be supplied using403the <code class="docutils literal notranslate"><span class="pre">prog=</span></code> argument to <a class="reference internal" href="#argparse.ArgumentParser" title="argparse.ArgumentParser"><code class="xref py py-class docutils literal notranslate"><span class="pre">ArgumentParser</span></code></a>:</p>404<div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="gp">>>> </span><span class="n">parser</span> <span class="o">=</span> <span class="n">argparse</span><span class="o">.</span><span class="n">ArgumentParser</span><span class="p">(</span><span class="n">prog</span><span class="o">=</span><span class="s1">'myprogram'</span><span class="p">)</span>405<span class="gp">>>> </span><span class="n">parser</span><span class="o">.</span><span class="n">print_help</span><span class="p">()</span>406<span class="go">usage: myprogram [-h]</span>407 408<span class="go">options:</span>409<span class="go"> -h, --help show this help message and exit</span>410</pre></div>411</div>412<p>Note that the program name, whether determined from <code class="docutils literal notranslate"><span class="pre">sys.argv[0]</span></code>,413from the <code class="docutils literal notranslate"><span class="pre">__main__</span></code> module attributes or from the414<code class="docutils literal notranslate"><span class="pre">prog=</span></code> argument, is available to help messages using the <code class="docutils literal notranslate"><span class="pre">%(prog)s</span></code> format415specifier.</p>416<div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="gp">>>> </span><span class="n">parser</span> <span class="o">=</span> <span class="n">argparse</span><span class="o">.</span><span class="n">ArgumentParser</span><span class="p">(</span><span class="n">prog</span><span class="o">=</span><span class="s1">'myprogram'</span><span class="p">)</span>417<span class="gp">>>> </span><span class="n">parser</span><span class="o">.</span><span class="n">add_argument</span><span class="p">(</span><span class="s1">'--foo'</span><span class="p">,</span> <span class="n">help</span><span class="o">=</span><span class="s1">'foo of the </span><span class="si">%(prog)s</span><span class="s1"> program'</span><span class="p">)</span>418<span class="gp">>>> </span><span class="n">parser</span><span class="o">.</span><span class="n">print_help</span><span class="p">()</span>419<span class="go">usage: myprogram [-h] [--foo FOO]</span>420 421<span class="go">options:</span>422<span class="go"> -h, --help show this help message and exit</span>423<span class="go"> --foo FOO foo of the myprogram program</span>424</pre></div>425</div>426<div class="versionchanged">427<p><span class="versionmodified changed">Changed in version 3.14: </span>The default <code class="docutils literal notranslate"><span class="pre">prog</span></code> value now reflects how <code class="docutils literal notranslate"><span class="pre">__main__</span></code> was actually executed,428rather than always being <code class="docutils literal notranslate"><span class="pre">os.path.basename(sys.argv[0])</span></code>.</p>429</div>430</section>431<section id="usage">432<h3>usage<a class="headerlink" href="#usage" title="Link to this heading">¶</a></h3>433<p>By default, <a class="reference internal" href="#argparse.ArgumentParser" title="argparse.ArgumentParser"><code class="xref py py-class docutils literal notranslate"><span class="pre">ArgumentParser</span></code></a> calculates the usage message from the434arguments it contains. The default message can be overridden with the435<code class="docutils literal notranslate"><span class="pre">usage=</span></code> keyword argument:</p>436<div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="gp">>>> </span><span class="n">parser</span> <span class="o">=</span> <span class="n">argparse</span><span class="o">.</span><span class="n">ArgumentParser</span><span class="p">(</span><span class="n">prog</span><span class="o">=</span><span class="s1">'PROG'</span><span class="p">,</span> <span class="n">usage</span><span class="o">=</span><span class="s1">'</span><span class="si">%(prog)s</span><span class="s1"> [options]'</span><span class="p">)</span>437<span class="gp">>>> </span><span class="n">parser</span><span class="o">.</span><span class="n">add_argument</span><span class="p">(</span><span class="s1">'--foo'</span><span class="p">,</span> <span class="n">nargs</span><span class="o">=</span><span class="s1">'?'</span><span class="p">,</span> <span class="n">help</span><span class="o">=</span><span class="s1">'foo help'</span><span class="p">)</span>438<span class="gp">>>> </span><span class="n">parser</span><span class="o">.</span><span class="n">add_argument</span><span class="p">(</span><span class="s1">'bar'</span><span class="p">,</span> <span class="n">nargs</span><span class="o">=</span><span class="s1">'+'</span><span class="p">,</span> <span class="n">help</span><span class="o">=</span><span class="s1">'bar help'</span><span class="p">)</span>439<span class="gp">>>> </span><span class="n">parser</span><span class="o">.</span><span class="n">print_help</span><span class="p">()</span>440<span class="go">usage: PROG [options]</span>441 442<span class="go">positional arguments:</span>443<span class="go"> bar bar help</span>444 445<span class="go">options:</span>446<span class="go"> -h, --help show this help message and exit</span>447<span class="go"> --foo [FOO] foo help</span>448</pre></div>449</div>450<p>The <code class="docutils literal notranslate"><span class="pre">%(prog)s</span></code> format specifier is available to fill in the program name in451your usage messages.</p>452<p>When a custom usage message is specified for the main parser, you may also want to453consider passing the <code class="docutils literal notranslate"><span class="pre">prog</span></code> argument to <a class="reference internal" href="#argparse.ArgumentParser.add_subparsers" title="argparse.ArgumentParser.add_subparsers"><code class="xref py py-meth docutils literal notranslate"><span class="pre">add_subparsers()</span></code></a>454or the <code class="docutils literal notranslate"><span class="pre">prog</span></code> and the <code class="docutils literal notranslate"><span class="pre">usage</span></code> arguments to455<a class="reference internal" href="#argparse._SubParsersAction.add_parser" title="argparse._SubParsersAction.add_parser"><code class="xref py py-meth docutils literal notranslate"><span class="pre">add_parser()</span></code></a>, to ensure consistent command prefixes and456usage information across subparsers.</p>457</section>458<section id="description">459<span id="id2"></span><h3>description<a class="headerlink" href="#description" title="Link to this heading">¶</a></h3>460<p>Most calls to the <a class="reference internal" href="#argparse.ArgumentParser" title="argparse.ArgumentParser"><code class="xref py py-class docutils literal notranslate"><span class="pre">ArgumentParser</span></code></a> constructor will use the461<code class="docutils literal notranslate"><span class="pre">description=</span></code> keyword argument. This argument gives a brief description of462what the program does and how it works. In help messages, the description is463displayed between the command-line usage string and the help messages for the464various arguments.</p>465<p>By default, the description will be line-wrapped so that it fits within the466given space. To change this behavior, see the <a class="reference internal" href="#formatter-class">formatter_class</a> argument.</p>467</section>468<section id="epilog">469<h3>epilog<a class="headerlink" href="#epilog" title="Link to this heading">¶</a></h3>470<p>Some programs like to display additional description of the program after the471description of the arguments. Such text can be specified using the <code class="docutils literal notranslate"><span class="pre">epilog=</span></code>472argument to <a class="reference internal" href="#argparse.ArgumentParser" title="argparse.ArgumentParser"><code class="xref py py-class docutils literal notranslate"><span class="pre">ArgumentParser</span></code></a>:</p>473<div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="gp">>>> </span><span class="n">parser</span> <span class="o">=</span> <span class="n">argparse</span><span class="o">.</span><span class="n">ArgumentParser</span><span class="p">(</span>474<span class="gp">... </span> <span class="n">description</span><span class="o">=</span><span class="s1">'A foo that bars'</span><span class="p">,</span>475<span class="gp">... </span> <span class="n">epilog</span><span class="o">=</span><span class="s2">"And that's how you'd foo a bar"</span><span class="p">)</span>476<span class="gp">>>> </span><span class="n">parser</span><span class="o">.</span><span class="n">print_help</span><span class="p">()</span>477<span class="go">usage: argparse.py [-h]</span>478 479<span class="go">A foo that bars</span>480 481<span class="go">options:</span>482<span class="go"> -h, --help show this help message and exit</span>483 484<span class="go">And that's how you'd foo a bar</span>485</pre></div>486</div>487<p>As with the <a class="reference internal" href="#description">description</a> argument, the <code class="docutils literal notranslate"><span class="pre">epilog=</span></code> text is by default488line-wrapped, but this behavior can be adjusted with the <a class="reference internal" href="#formatter-class">formatter_class</a>489argument to <a class="reference internal" href="#argparse.ArgumentParser" title="argparse.ArgumentParser"><code class="xref py py-class docutils literal notranslate"><span class="pre">ArgumentParser</span></code></a>.</p>490</section>491<section id="parents">492<h3>parents<a class="headerlink" href="#parents" title="Link to this heading">¶</a></h3>493<p>Sometimes, several parsers share a common set of arguments. Rather than494repeating the definitions of these arguments, a single parser with all the495shared arguments and passed to <code class="docutils literal notranslate"><span class="pre">parents=</span></code> argument to <a class="reference internal" href="#argparse.ArgumentParser" title="argparse.ArgumentParser"><code class="xref py py-class docutils literal notranslate"><span class="pre">ArgumentParser</span></code></a>496can be used. The <code class="docutils literal notranslate"><span class="pre">parents=</span></code> argument takes a list of <code class="xref py py-class docutils literal notranslate"><span class="pre">ArgumentParser</span></code>497objects, collects all the positional and optional actions from them, and adds498these actions to the <code class="xref py py-class docutils literal notranslate"><span class="pre">ArgumentParser</span></code> object being constructed:</p>499<div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="gp">>>> </span><span class="n">parent_parser</span> <span class="o">=</span> <span class="n">argparse</span><span class="o">.</span><span class="n">ArgumentParser</span><span class="p">(</span><span class="n">add_help</span><span class="o">=</span><span class="kc">False</span><span class="p">)</span>500<span class="gp">>>> </span><span class="n">parent_parser</span><span class="o">.</span><span class="n">add_argument</span><span class="p">(</span><span class="s1">'--parent'</span><span class="p">,</span> <span class="nb">type</span><span class="o">=</span><span class="nb">int</span><span class="p">)</span>501 502<span class="gp">>>> </span><span class="n">foo_parser</span> <span class="o">=</span> <span class="n">argparse</span><span class="o">.</span><span class="n">ArgumentParser</span><span class="p">(</span><span class="n">parents</span><span class="o">=</span><span class="p">[</span><span class="n">parent_parser</span><span class="p">])</span>503<span class="gp">>>> </span><span class="n">foo_parser</span><span class="o">.</span><span class="n">add_argument</span><span class="p">(</span><span class="s1">'foo'</span><span class="p">)</span>504<span class="gp">>>> </span><span class="n">foo_parser</span><span class="o">.</span><span class="n">parse_args</span><span class="p">([</span><span class="s1">'--parent'</span><span class="p">,</span> <span class="s1">'2'</span><span class="p">,</span> <span class="s1">'XXX'</span><span class="p">])</span>505<span class="go">Namespace(foo='XXX', parent=2)</span>506 507<span class="gp">>>> </span><span class="n">bar_parser</span> <span class="o">=</span> <span class="n">argparse</span><span class="o">.</span><span class="n">ArgumentParser</span><span class="p">(</span><span class="n">parents</span><span class="o">=</span><span class="p">[</span><span class="n">parent_parser</span><span class="p">])</span>508<span class="gp">>>> </span><span class="n">bar_parser</span><span class="o">.</span><span class="n">add_argument</span><span class="p">(</span><span class="s1">'--bar'</span><span class="p">)</span>509<span class="gp">>>> </span><span class="n">bar_parser</span><span class="o">.</span><span class="n">parse_args</span><span class="p">([</span><span class="s1">'--bar'</span><span class="p">,</span> <span class="s1">'YYY'</span><span class="p">])</span>510<span class="go">Namespace(bar='YYY', parent=None)</span>511</pre></div>512</div>513<p>Note that most parent parsers will specify <code class="docutils literal notranslate"><span class="pre">add_help=False</span></code>. Otherwise, the514<a class="reference internal" href="#argparse.ArgumentParser" title="argparse.ArgumentParser"><code class="xref py py-class docutils literal notranslate"><span class="pre">ArgumentParser</span></code></a> will see two <code class="docutils literal notranslate"><span class="pre">-h/--help</span></code> options (one in the parent515and one in the child) and raise an error.</p>516<div class="admonition note">517<p class="admonition-title">Note</p>518<p>You must fully initialize the parsers before passing them via <code class="docutils literal notranslate"><span class="pre">parents=</span></code>.519If you change the parent parsers after the child parser, those changes will520not be reflected in the child.</p>521</div>522</section>523<section id="formatter-class">524<span id="id3"></span><h3>formatter_class<a class="headerlink" href="#formatter-class" title="Link to this heading">¶</a></h3>525<p><a class="reference internal" href="#argparse.ArgumentParser" title="argparse.ArgumentParser"><code class="xref py py-class docutils literal notranslate"><span class="pre">ArgumentParser</span></code></a> objects allow the help formatting to be customized by526specifying an alternate formatting class. Currently, there are four such527classes:</p>528<dl class="py class">529<dt class="sig sig-object py" id="argparse.RawDescriptionHelpFormatter">530<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">argparse.</span></span><span class="sig-name descname"><span class="pre">RawDescriptionHelpFormatter</span></span><a class="headerlink" href="#argparse.RawDescriptionHelpFormatter" title="Link to this definition">¶</a></dt>531<dt class="sig sig-object py" id="argparse.RawTextHelpFormatter">532<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">argparse.</span></span><span class="sig-name descname"><span class="pre">RawTextHelpFormatter</span></span><a class="headerlink" href="#argparse.RawTextHelpFormatter" title="Link to this definition">¶</a></dt>533<dt class="sig sig-object py" id="argparse.ArgumentDefaultsHelpFormatter">534<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">argparse.</span></span><span class="sig-name descname"><span class="pre">ArgumentDefaultsHelpFormatter</span></span><a class="headerlink" href="#argparse.ArgumentDefaultsHelpFormatter" title="Link to this definition">¶</a></dt>535<dt class="sig sig-object py" id="argparse.MetavarTypeHelpFormatter">536<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">argparse.</span></span><span class="sig-name descname"><span class="pre">MetavarTypeHelpFormatter</span></span><a class="headerlink" href="#argparse.MetavarTypeHelpFormatter" title="Link to this definition">¶</a></dt>537<dd></dd></dl>538 539<p><a class="reference internal" href="#argparse.RawDescriptionHelpFormatter" title="argparse.RawDescriptionHelpFormatter"><code class="xref py py-class docutils literal notranslate"><span class="pre">RawDescriptionHelpFormatter</span></code></a> and <a class="reference internal" href="#argparse.RawTextHelpFormatter" title="argparse.RawTextHelpFormatter"><code class="xref py py-class docutils literal notranslate"><span class="pre">RawTextHelpFormatter</span></code></a> give540more control over how textual descriptions are displayed.541By default, <a class="reference internal" href="#argparse.ArgumentParser" title="argparse.ArgumentParser"><code class="xref py py-class docutils literal notranslate"><span class="pre">ArgumentParser</span></code></a> objects line-wrap the <a class="reference internal" href="#description">description</a> and542<a class="reference internal" href="#epilog">epilog</a> texts in command-line help messages:</p>543<div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="gp">>>> </span><span class="n">parser</span> <span class="o">=</span> <span class="n">argparse</span><span class="o">.</span><span class="n">ArgumentParser</span><span class="p">(</span>544<span class="gp">... </span> <span class="n">prog</span><span class="o">=</span><span class="s1">'PROG'</span><span class="p">,</span>545<span class="gp">... </span> <span class="n">description</span><span class="o">=</span><span class="s1">'''this description</span>546<span class="gp">... </span><span class="s1"> was indented weird</span>547<span class="gp">... </span><span class="s1"> but that is okay'''</span><span class="p">,</span>548<span class="gp">... </span> <span class="n">epilog</span><span class="o">=</span><span class="s1">'''</span>549<span class="gp">... </span><span class="s1"> likewise for this epilog whose whitespace will</span>550<span class="gp">... </span><span class="s1"> be cleaned up and whose words will be wrapped</span>551<span class="gp">... </span><span class="s1"> across a couple lines'''</span><span class="p">)</span>552<span class="gp">>>> </span><span class="n">parser</span><span class="o">.</span><span class="n">print_help</span><span class="p">()</span>553<span class="go">usage: PROG [-h]</span>554 555<span class="go">this description was indented weird but that is okay</span>556 557<span class="go">options:</span>558<span class="go"> -h, --help show this help message and exit</span>559 560<span class="go">likewise for this epilog whose whitespace will be cleaned up and whose words</span>561<span class="go">will be wrapped across a couple lines</span>562</pre></div>563</div>564<p>Passing <a class="reference internal" href="#argparse.RawDescriptionHelpFormatter" title="argparse.RawDescriptionHelpFormatter"><code class="xref py py-class docutils literal notranslate"><span class="pre">RawDescriptionHelpFormatter</span></code></a> as <code class="docutils literal notranslate"><span class="pre">formatter_class=</span></code>565indicates that <a class="reference internal" href="#description">description</a> and <a class="reference internal" href="#epilog">epilog</a> are already correctly formatted and566should not be line-wrapped:</p>567<div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="gp">>>> </span><span class="n">parser</span> <span class="o">=</span> <span class="n">argparse</span><span class="o">.</span><span class="n">ArgumentParser</span><span class="p">(</span>568<span class="gp">... </span> <span class="n">prog</span><span class="o">=</span><span class="s1">'PROG'</span><span class="p">,</span>569<span class="gp">... </span> <span class="n">formatter_class</span><span class="o">=</span><span class="n">argparse</span><span class="o">.</span><span class="n">RawDescriptionHelpFormatter</span><span class="p">,</span>570<span class="gp">... </span> <span class="n">description</span><span class="o">=</span><span class="n">textwrap</span><span class="o">.</span><span class="n">dedent</span><span class="p">(</span><span class="s1">'''</span><span class="se">\</span>571<span class="gp">... </span><span class="s1"> Please do not mess up this text!</span>572<span class="gp">... </span><span class="s1"> --------------------------------</span>573<span class="gp">... </span><span class="s1"> I have indented it</span>574<span class="gp">... </span><span class="s1"> exactly the way</span>575<span class="gp">... </span><span class="s1"> I want it</span>576<span class="gp">... </span><span class="s1"> '''</span><span class="p">))</span>577<span class="gp">>>> </span><span class="n">parser</span><span class="o">.</span><span class="n">print_help</span><span class="p">()</span>578<span class="go">usage: PROG [-h]</span>579 580<span class="go">Please do not mess up this text!</span>581<span class="go">--------------------------------</span>582<span class="go"> I have indented it</span>583<span class="go"> exactly the way</span>584<span class="go"> I want it</span>585 586<span class="go">options:</span>587<span class="go"> -h, --help show this help message and exit</span>588</pre></div>589</div>590<p><a class="reference internal" href="#argparse.RawTextHelpFormatter" title="argparse.RawTextHelpFormatter"><code class="xref py py-class docutils literal notranslate"><span class="pre">RawTextHelpFormatter</span></code></a> maintains whitespace for all sorts of help text,591including argument descriptions. However, multiple newlines are replaced with592one. If you wish to preserve multiple blank lines, add spaces between the593newlines.</p>594<p><a class="reference internal" href="#argparse.ArgumentDefaultsHelpFormatter" title="argparse.ArgumentDefaultsHelpFormatter"><code class="xref py py-class docutils literal notranslate"><span class="pre">ArgumentDefaultsHelpFormatter</span></code></a> automatically adds information about595default values to each of the argument help messages:</p>596<div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="gp">>>> </span><span class="n">parser</span> <span class="o">=</span> <span class="n">argparse</span><span class="o">.</span><span class="n">ArgumentParser</span><span class="p">(</span>597<span class="gp">... </span> <span class="n">prog</span><span class="o">=</span><span class="s1">'PROG'</span><span class="p">,</span>598<span class="gp">... </span> <span class="n">formatter_class</span><span class="o">=</span><span class="n">argparse</span><span class="o">.</span><span class="n">ArgumentDefaultsHelpFormatter</span><span class="p">)</span>599<span class="gp">>>> </span><span class="n">parser</span><span class="o">.</span><span class="n">add_argument</span><span class="p">(</span><span class="s1">'--foo'</span><span class="p">,</span> <span class="nb">type</span><span class="o">=</span><span class="nb">int</span><span class="p">,</span> <span class="n">default</span><span class="o">=</span><span class="mi">42</span><span class="p">,</span> <span class="n">help</span><span class="o">=</span><span class="s1">'FOO!'</span><span class="p">)</span>600<span class="gp">>>> </span><span class="n">parser</span><span class="o">.</span><span class="n">add_argument</span><span class="p">(</span><span class="s1">'bar'</span><span class="p">,</span> <span class="n">nargs</span><span class="o">=</span><span class="s1">'*'</span><span class="p">,</span> <span class="n">default</span><span class="o">=</span><span class="p">[</span><span class="mi">1</span><span class="p">,</span> <span class="mi">2</span><span class="p">,</span> <span class="mi">3</span><span class="p">],</span> <span class="n">help</span><span class="o">=</span><span class="s1">'BAR!'</span><span class="p">)</span>601<span class="gp">>>> </span><span class="n">parser</span><span class="o">.</span><span class="n">print_help</span><span class="p">()</span>602<span class="go">usage: PROG [-h] [--foo FOO] [bar ...]</span>603 604<span class="go">positional arguments:</span>605<span class="go"> bar BAR! (default: [1, 2, 3])</span>606 607<span class="go">options:</span>608<span class="go"> -h, --help show this help message and exit</span>609<span class="go"> --foo FOO FOO! (default: 42)</span>610</pre></div>611</div>612<p><a class="reference internal" href="#argparse.MetavarTypeHelpFormatter" title="argparse.MetavarTypeHelpFormatter"><code class="xref py py-class docutils literal notranslate"><span class="pre">MetavarTypeHelpFormatter</span></code></a> uses the name of the <a class="reference internal" href="#type">type</a> argument for each613argument as the display name for its values (rather than using the <a class="reference internal" href="#dest">dest</a>614as the regular formatter does):</p>615<div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="gp">>>> </span><span class="n">parser</span> <span class="o">=</span> <span class="n">argparse</span><span class="o">.</span><span class="n">ArgumentParser</span><span class="p">(</span>616<span class="gp">... </span> <span class="n">prog</span><span class="o">=</span><span class="s1">'PROG'</span><span class="p">,</span>617<span class="gp">... </span> <span class="n">formatter_class</span><span class="o">=</span><span class="n">argparse</span><span class="o">.</span><span class="n">MetavarTypeHelpFormatter</span><span class="p">)</span>618<span class="gp">>>> </span><span class="n">parser</span><span class="o">.</span><span class="n">add_argument</span><span class="p">(</span><span class="s1">'--foo'</span><span class="p">,</span> <span class="nb">type</span><span class="o">=</span><span class="nb">int</span><span class="p">)</span>619<span class="gp">>>> </span><span class="n">parser</span><span class="o">.</span><span class="n">add_argument</span><span class="p">(</span><span class="s1">'bar'</span><span class="p">,</span> <span class="nb">type</span><span class="o">=</span><span class="nb">float</span><span class="p">)</span>620<span class="gp">>>> </span><span class="n">parser</span><span class="o">.</span><span class="n">print_help</span><span class="p">()</span>621<span class="go">usage: PROG [-h] [--foo int] float</span>622 623<span class="go">positional arguments:</span>624<span class="go"> float</span>625 626<span class="go">options:</span>627<span class="go"> -h, --help show this help message and exit</span>628<span class="go"> --foo int</span>629</pre></div>630</div>631</section>632<section id="prefix-chars">633<h3>prefix_chars<a class="headerlink" href="#prefix-chars" title="Link to this heading">¶</a></h3>634<p>Most command-line options will use <code class="docutils literal notranslate"><span class="pre">-</span></code> as the prefix, e.g. <code class="docutils literal notranslate"><span class="pre">-f/--foo</span></code>.635Parsers that need to support different or additional prefix636characters, e.g. for options637like <code class="docutils literal notranslate"><span class="pre">+f</span></code> or <code class="docutils literal notranslate"><span class="pre">/foo</span></code>, may specify them using the <code class="docutils literal notranslate"><span class="pre">prefix_chars=</span></code> argument638to the <a class="reference internal" href="#argparse.ArgumentParser" title="argparse.ArgumentParser"><code class="xref py py-class docutils literal notranslate"><span class="pre">ArgumentParser</span></code></a> constructor:</p>639<div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="gp">>>> </span><span class="n">parser</span> <span class="o">=</span> <span class="n">argparse</span><span class="o">.</span><span class="n">ArgumentParser</span><span class="p">(</span><span class="n">prog</span><span class="o">=</span><span class="s1">'PROG'</span><span class="p">,</span> <span class="n">prefix_chars</span><span class="o">=</span><span class="s1">'-+'</span><span class="p">)</span>640<span class="gp">>>> </span><span class="n">parser</span><span class="o">.</span><span class="n">add_argument</span><span class="p">(</span><span class="s1">'+f'</span><span class="p">)</span>641<span class="gp">>>> </span><span class="n">parser</span><span class="o">.</span><span class="n">add_argument</span><span class="p">(</span><span class="s1">'++bar'</span><span class="p">)</span>642<span class="gp">>>> </span><span class="n">parser</span><span class="o">.</span><span class="n">parse_args</span><span class="p">(</span><span class="s1">'+f X ++bar Y'</span><span class="o">.</span><span class="n">split</span><span class="p">())</span>643<span class="go">Namespace(bar='Y', f='X')</span>644</pre></div>645</div>646<p>The <code class="docutils literal notranslate"><span class="pre">prefix_chars=</span></code> argument defaults to <code class="docutils literal notranslate"><span class="pre">'-'</span></code>. Supplying a set of647characters that does not include <code class="docutils literal notranslate"><span class="pre">-</span></code> will cause <code class="docutils literal notranslate"><span class="pre">-f/--foo</span></code> options to be648disallowed.</p>649</section>650<section id="fromfile-prefix-chars">651<h3>fromfile_prefix_chars<a class="headerlink" href="#fromfile-prefix-chars" title="Link to this heading">¶</a></h3>652<p>Sometimes, when dealing with a particularly long argument list, it653may make sense to keep the list of arguments in a file rather than typing it out654at the command line. If the <code class="docutils literal notranslate"><span class="pre">fromfile_prefix_chars=</span></code> argument is given to the655<a class="reference internal" href="#argparse.ArgumentParser" title="argparse.ArgumentParser"><code class="xref py py-class docutils literal notranslate"><span class="pre">ArgumentParser</span></code></a> constructor, then arguments that start with any of the656specified characters will be treated as files, and will be replaced by the657arguments they contain. For example:</p>658<div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="gp">>>> </span><span class="k">with</span> <span class="nb">open</span><span class="p">(</span><span class="s1">'args.txt'</span><span class="p">,</span> <span class="s1">'w'</span><span class="p">,</span> <span class="n">encoding</span><span class="o">=</span><span class="n">sys</span><span class="o">.</span><span class="n">getfilesystemencoding</span><span class="p">())</span> <span class="k">as</span> <span class="n">fp</span><span class="p">:</span>659<span class="gp">... </span> <span class="n">fp</span><span class="o">.</span><span class="n">write</span><span class="p">(</span><span class="s1">'-f</span><span class="se">\n</span><span class="s1">bar'</span><span class="p">)</span>660<span class="gp">...</span>661<span class="gp">>>> </span><span class="n">parser</span> <span class="o">=</span> <span class="n">argparse</span><span class="o">.</span><span class="n">ArgumentParser</span><span class="p">(</span><span class="n">fromfile_prefix_chars</span><span class="o">=</span><span class="s1">'@'</span><span class="p">)</span>662<span class="gp">>>> </span><span class="n">parser</span><span class="o">.</span><span class="n">add_argument</span><span class="p">(</span><span class="s1">'-f'</span><span class="p">)</span>663<span class="gp">>>> </span><span class="n">parser</span><span class="o">.</span><span class="n">parse_args</span><span class="p">([</span><span class="s1">'-f'</span><span class="p">,</span> <span class="s1">'foo'</span><span class="p">,</span> <span class="s1">'@args.txt'</span><span class="p">])</span>664<span class="go">Namespace(f='bar')</span>665</pre></div>666</div>667<p>Arguments read from a file must be one per line by default (but see also668<a class="reference internal" href="#argparse.ArgumentParser.convert_arg_line_to_args" title="argparse.ArgumentParser.convert_arg_line_to_args"><code class="xref py py-meth docutils literal notranslate"><span class="pre">convert_arg_line_to_args()</span></code></a>) and are treated as if they669were in the same place as the original file referencing argument on the command670line. So in the example above, the expression <code class="docutils literal notranslate"><span class="pre">['-f',</span> <span class="pre">'foo',</span> <span class="pre">'@args.txt']</span></code>671is considered equivalent to the expression <code class="docutils literal notranslate"><span class="pre">['-f',</span> <span class="pre">'foo',</span> <span class="pre">'-f',</span> <span class="pre">'bar']</span></code>.</p>672<div class="admonition note">673<p class="admonition-title">Note</p>674<p>Empty lines are treated as empty strings (<code class="docutils literal notranslate"><span class="pre">''</span></code>), which are allowed as values but675not as arguments. Empty lines that are read as arguments will result in an676“unrecognized arguments” error.</p>677</div>678<p><a class="reference internal" href="#argparse.ArgumentParser" title="argparse.ArgumentParser"><code class="xref py py-class docutils literal notranslate"><span class="pre">ArgumentParser</span></code></a> uses <a class="reference internal" href="../glossary.html#term-filesystem-encoding-and-error-handler"><span class="xref std std-term">filesystem encoding and error handler</span></a>679to read the file containing arguments.</p>680<p>The <code class="docutils literal notranslate"><span class="pre">fromfile_prefix_chars=</span></code> argument defaults to <code class="docutils literal notranslate"><span class="pre">None</span></code>, meaning that681arguments will never be treated as file references.</p>682<div class="versionchanged">683<p><span class="versionmodified changed">Changed in version 3.12: </span><a class="reference internal" href="#argparse.ArgumentParser" title="argparse.ArgumentParser"><code class="xref py py-class docutils literal notranslate"><span class="pre">ArgumentParser</span></code></a> changed encoding and errors to read arguments files684from default (e.g. <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>685and <code class="docutils literal notranslate"><span class="pre">"strict"</span></code>) to the <a class="reference internal" href="../glossary.html#term-filesystem-encoding-and-error-handler"><span class="xref std std-term">filesystem encoding and error handler</span></a>.686Arguments file should be encoded in UTF-8 instead of ANSI Codepage on Windows.</p>687</div>688</section>689<section id="argument-default">690<h3>argument_default<a class="headerlink" href="#argument-default" title="Link to this heading">¶</a></h3>691<p>Generally, argument defaults are specified either by passing a default to692<a class="reference internal" href="#argparse.ArgumentParser.add_argument" title="argparse.ArgumentParser.add_argument"><code class="xref py py-meth docutils literal notranslate"><span class="pre">add_argument()</span></code></a> or by calling the693<a class="reference internal" href="#argparse.ArgumentParser.set_defaults" title="argparse.ArgumentParser.set_defaults"><code class="xref py py-meth docutils literal notranslate"><span class="pre">set_defaults()</span></code></a> methods with a specific set of name-value694pairs. Sometimes however, it may be useful to specify a single parser-wide695default for arguments. This can be accomplished by passing the696<code class="docutils literal notranslate"><span class="pre">argument_default=</span></code> keyword argument to <a class="reference internal" href="#argparse.ArgumentParser" title="argparse.ArgumentParser"><code class="xref py py-class docutils literal notranslate"><span class="pre">ArgumentParser</span></code></a>. For example,697to globally suppress attribute creation on <a class="reference internal" href="#argparse.ArgumentParser.parse_args" title="argparse.ArgumentParser.parse_args"><code class="xref py py-meth docutils literal notranslate"><span class="pre">parse_args()</span></code></a>698calls, we supply <code class="docutils literal notranslate"><span class="pre">argument_default=SUPPRESS</span></code>:</p>699<div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="gp">>>> </span><span class="n">parser</span> <span class="o">=</span> <span class="n">argparse</span><span class="o">.</span><span class="n">ArgumentParser</span><span class="p">(</span><span class="n">argument_default</span><span class="o">=</span><span class="n">argparse</span><span class="o">.</span><span class="n">SUPPRESS</span><span class="p">)</span>700<span class="gp">>>> </span><span class="n">parser</span><span class="o">.</span><span class="n">add_argument</span><span class="p">(</span><span class="s1">'--foo'</span><span class="p">)</span>701<span class="gp">>>> </span><span class="n">parser</span><span class="o">.</span><span class="n">add_argument</span><span class="p">(</span><span class="s1">'bar'</span><span class="p">,</span> <span class="n">nargs</span><span class="o">=</span><span class="s1">'?'</span><span class="p">)</span>702<span class="gp">>>> </span><span class="n">parser</span><span class="o">.</span><span class="n">parse_args</span><span class="p">([</span><span class="s1">'--foo'</span><span class="p">,</span> <span class="s1">'1'</span><span class="p">,</span> <span class="s1">'BAR'</span><span class="p">])</span>703<span class="go">Namespace(bar='BAR', foo='1')</span>704<span class="gp">>>> </span><span class="n">parser</span><span class="o">.</span><span class="n">parse_args</span><span class="p">([])</span>705<span class="go">Namespace()</span>706</pre></div>707</div>708</section>709<section id="allow-abbrev">710<span id="id4"></span><h3>allow_abbrev<a class="headerlink" href="#allow-abbrev" title="Link to this heading">¶</a></h3>711<p>Normally, when you pass an argument list to the712<a class="reference internal" href="#argparse.ArgumentParser.parse_args" title="argparse.ArgumentParser.parse_args"><code class="xref py py-meth docutils literal notranslate"><span class="pre">parse_args()</span></code></a> method of an <a class="reference internal" href="#argparse.ArgumentParser" title="argparse.ArgumentParser"><code class="xref py py-class docutils literal notranslate"><span class="pre">ArgumentParser</span></code></a>,713it <a class="reference internal" href="#prefix-matching"><span class="std std-ref">recognizes abbreviations</span></a> of long options.</p>714<p>This feature can be disabled by setting <code class="docutils literal notranslate"><span class="pre">allow_abbrev</span></code> to <code class="docutils literal notranslate"><span class="pre">False</span></code>:</p>715<div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="gp">>>> </span><span class="n">parser</span> <span class="o">=</span> <span class="n">argparse</span><span class="o">.</span><span class="n">ArgumentParser</span><span class="p">(</span><span class="n">prog</span><span class="o">=</span><span class="s1">'PROG'</span><span class="p">,</span> <span class="n">allow_abbrev</span><span class="o">=</span><span class="kc">False</span><span class="p">)</span>716<span class="gp">>>> </span><span class="n">parser</span><span class="o">.</span><span class="n">add_argument</span><span class="p">(</span><span class="s1">'--foobar'</span><span class="p">,</span> <span class="n">action</span><span class="o">=</span><span class="s1">'store_true'</span><span class="p">)</span>717<span class="gp">>>> </span><span class="n">parser</span><span class="o">.</span><span class="n">add_argument</span><span class="p">(</span><span class="s1">'--foonley'</span><span class="p">,</span> <span class="n">action</span><span class="o">=</span><span class="s1">'store_false'</span><span class="p">)</span>718<span class="gp">>>> </span><span class="n">parser</span><span class="o">.</span><span class="n">parse_args</span><span class="p">([</span><span class="s1">'--foon'</span><span class="p">])</span>719<span class="go">usage: PROG [-h] [--foobar] [--foonley]</span>720<span class="go">PROG: error: unrecognized arguments: --foon</span>721</pre></div>722</div>723<div class="versionadded">724<p><span class="versionmodified added">Added in version 3.5.</span></p>725</div>726</section>727<section id="conflict-handler">728<h3>conflict_handler<a class="headerlink" href="#conflict-handler" title="Link to this heading">¶</a></h3>729<p><a class="reference internal" href="#argparse.ArgumentParser" title="argparse.ArgumentParser"><code class="xref py py-class docutils literal notranslate"><span class="pre">ArgumentParser</span></code></a> objects do not allow two actions with the same option730string. By default, <code class="xref py py-class docutils literal notranslate"><span class="pre">ArgumentParser</span></code> objects raise an exception if an731attempt is made to create an argument with an option string that is already in732use:</p>733<div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="gp">>>> </span><span class="n">parser</span> <span class="o">=</span> <span class="n">argparse</span><span class="o">.</span><span class="n">ArgumentParser</span><span class="p">(</span><span class="n">prog</span><span class="o">=</span><span class="s1">'PROG'</span><span class="p">)</span>734<span class="gp">>>> </span><span class="n">parser</span><span class="o">.</span><span class="n">add_argument</span><span class="p">(</span><span class="s1">'-f'</span><span class="p">,</span> <span class="s1">'--foo'</span><span class="p">,</span> <span class="n">help</span><span class="o">=</span><span class="s1">'old foo help'</span><span class="p">)</span>735<span class="gp">>>> </span><span class="n">parser</span><span class="o">.</span><span class="n">add_argument</span><span class="p">(</span><span class="s1">'--foo'</span><span class="p">,</span> <span class="n">help</span><span class="o">=</span><span class="s1">'new foo help'</span><span class="p">)</span>736<span class="gt">Traceback (most recent call last):</span>737<span class="gr"> ..</span>738<span class="gr">ArgumentError</span>: <span class="n">argument --foo: conflicting option string(s): --foo</span>739</pre></div>740</div>741<p>Sometimes (e.g. when using <a class="reference internal" href="#parents">parents</a>) it may be useful to simply override any742older arguments with the same option string. To get this behavior, the value743<code class="docutils literal notranslate"><span class="pre">'resolve'</span></code> can be supplied to the <code class="docutils literal notranslate"><span class="pre">conflict_handler=</span></code> argument of744<a class="reference internal" href="#argparse.ArgumentParser" title="argparse.ArgumentParser"><code class="xref py py-class docutils literal notranslate"><span class="pre">ArgumentParser</span></code></a>:</p>745<div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="gp">>>> </span><span class="n">parser</span> <span class="o">=</span> <span class="n">argparse</span><span class="o">.</span><span class="n">ArgumentParser</span><span class="p">(</span><span class="n">prog</span><span class="o">=</span><span class="s1">'PROG'</span><span class="p">,</span> <span class="n">conflict_handler</span><span class="o">=</span><span class="s1">'resolve'</span><span class="p">)</span>746<span class="gp">>>> </span><span class="n">parser</span><span class="o">.</span><span class="n">add_argument</span><span class="p">(</span><span class="s1">'-f'</span><span class="p">,</span> <span class="s1">'--foo'</span><span class="p">,</span> <span class="n">help</span><span class="o">=</span><span class="s1">'old foo help'</span><span class="p">)</span>747<span class="gp">>>> </span><span class="n">parser</span><span class="o">.</span><span class="n">add_argument</span><span class="p">(</span><span class="s1">'--foo'</span><span class="p">,</span> <span class="n">help</span><span class="o">=</span><span class="s1">'new foo help'</span><span class="p">)</span>748<span class="gp">>>> </span><span class="n">parser</span><span class="o">.</span><span class="n">print_help</span><span class="p">()</span>749<span class="go">usage: PROG [-h] [-f FOO] [--foo FOO]</span>750 751<span class="go">options:</span>752<span class="go"> -h, --help show this help message and exit</span>753<span class="go"> -f FOO old foo help</span>754<span class="go"> --foo FOO new foo help</span>755</pre></div>756</div>757<p>Note that <a class="reference internal" href="#argparse.ArgumentParser" title="argparse.ArgumentParser"><code class="xref py py-class docutils literal notranslate"><span class="pre">ArgumentParser</span></code></a> objects only remove an action if all of its758option strings are overridden. So, in the example above, the old <code class="docutils literal notranslate"><span class="pre">-f/--foo</span></code>759action is retained as the <code class="docutils literal notranslate"><span class="pre">-f</span></code> action, because only the <code class="docutils literal notranslate"><span class="pre">--foo</span></code> option760string was overridden.</p>761</section>762<section id="add-help">763<h3>add_help<a class="headerlink" href="#add-help" title="Link to this heading">¶</a></h3>764<p>By default, <a class="reference internal" href="#argparse.ArgumentParser" title="argparse.ArgumentParser"><code class="xref py py-class docutils literal notranslate"><span class="pre">ArgumentParser</span></code></a> objects add an option which simply displays765the parser’s help message. If <code class="docutils literal notranslate"><span class="pre">-h</span></code> or <code class="docutils literal notranslate"><span class="pre">--help</span></code> is supplied at the command766line, the <code class="xref py py-class docutils literal notranslate"><span class="pre">ArgumentParser</span></code> help will be printed.</p>767<p>Occasionally, it may be useful to disable the addition of this help option.768This can be achieved by passing <code class="docutils literal notranslate"><span class="pre">False</span></code> as the <code class="docutils literal notranslate"><span class="pre">add_help=</span></code> argument to769<a class="reference internal" href="#argparse.ArgumentParser" title="argparse.ArgumentParser"><code class="xref py py-class docutils literal notranslate"><span class="pre">ArgumentParser</span></code></a>:</p>770<div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="gp">>>> </span><span class="n">parser</span> <span class="o">=</span> <span class="n">argparse</span><span class="o">.</span><span class="n">ArgumentParser</span><span class="p">(</span><span class="n">prog</span><span class="o">=</span><span class="s1">'PROG'</span><span class="p">,</span> <span class="n">add_help</span><span class="o">=</span><span class="kc">False</span><span class="p">)</span>771<span class="gp">>>> </span><span class="n">parser</span><span class="o">.</span><span class="n">add_argument</span><span class="p">(</span><span class="s1">'--foo'</span><span class="p">,</span> <span class="n">help</span><span class="o">=</span><span class="s1">'foo help'</span><span class="p">)</span>772<span class="gp">>>> </span><span class="n">parser</span><span class="o">.</span><span class="n">print_help</span><span class="p">()</span>773<span class="go">usage: PROG [--foo FOO]</span>774 775<span class="go">options:</span>776<span class="go"> --foo FOO foo help</span>777</pre></div>778</div>779<p>The help option is typically <code class="docutils literal notranslate"><span class="pre">-h/--help</span></code>. The exception to this is780if the <code class="docutils literal notranslate"><span class="pre">prefix_chars=</span></code> is specified and does not include <code class="docutils literal notranslate"><span class="pre">-</span></code>, in781which case <code class="docutils literal notranslate"><span class="pre">-h</span></code> and <code class="docutils literal notranslate"><span class="pre">--help</span></code> are not valid options. In782this case, the first character in <code class="docutils literal notranslate"><span class="pre">prefix_chars</span></code> is used to prefix783the help options:</p>784<div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="gp">>>> </span><span class="n">parser</span> <span class="o">=</span> <span class="n">argparse</span><span class="o">.</span><span class="n">ArgumentParser</span><span class="p">(</span><span class="n">prog</span><span class="o">=</span><span class="s1">'PROG'</span><span class="p">,</span> <span class="n">prefix_chars</span><span class="o">=</span><span class="s1">'+/'</span><span class="p">)</span>785<span class="gp">>>> </span><span class="n">parser</span><span class="o">.</span><span class="n">print_help</span><span class="p">()</span>786<span class="go">usage: PROG [+h]</span>787 788<span class="go">options:</span>789<span class="go"> +h, ++help show this help message and exit</span>790</pre></div>791</div>792</section>793<section id="exit-on-error">794<h3>exit_on_error<a class="headerlink" href="#exit-on-error" title="Link to this heading">¶</a></h3>795<p>Normally, when you pass an invalid argument list to the <a class="reference internal" href="#argparse.ArgumentParser.parse_args" title="argparse.ArgumentParser.parse_args"><code class="xref py py-meth docutils literal notranslate"><span class="pre">parse_args()</span></code></a>796method of an <a class="reference internal" href="#argparse.ArgumentParser" title="argparse.ArgumentParser"><code class="xref py py-class docutils literal notranslate"><span class="pre">ArgumentParser</span></code></a>, it will print a <em>message</em> to <a class="reference internal" href="sys.html#sys.stderr" title="sys.stderr"><code class="xref py py-data docutils literal notranslate"><span class="pre">sys.stderr</span></code></a> and exit with a status797code of 2.</p>798<p>If the user would like to catch errors manually, the feature can be enabled by setting799<code class="docutils literal notranslate"><span class="pre">exit_on_error</span></code> to <code class="docutils literal notranslate"><span class="pre">False</span></code>:</p>800<div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="gp">>>> </span><span class="n">parser</span> <span class="o">=</span> <span class="n">argparse</span><span class="o">.</span><span class="n">ArgumentParser</span><span class="p">(</span><span class="n">exit_on_error</span><span class="o">=</span><span class="kc">False</span><span class="p">)</span>801<span class="gp">>>> </span><span class="n">parser</span><span class="o">.</span><span class="n">add_argument</span><span class="p">(</span><span class="s1">'--integers'</span><span class="p">,</span> <span class="nb">type</span><span class="o">=</span><span class="nb">int</span><span class="p">)</span>802<span class="go">_StoreAction(option_strings=['--integers'], dest='integers', nargs=None, const=None, default=None, type=<class 'int'>, choices=None, help=None, metavar=None)</span>803<span class="gp">>>> </span><span class="k">try</span><span class="p">:</span>804<span class="gp">... </span> <span class="n">parser</span><span class="o">.</span><span class="n">parse_args</span><span class="p">(</span><span class="s1">'--integers a'</span><span class="o">.</span><span class="n">split</span><span class="p">())</span>805<span class="gp">... </span><span class="k">except</span> <span class="n">argparse</span><span class="o">.</span><span class="n">ArgumentError</span><span class="p">:</span>806<span class="gp">... </span> <span class="nb">print</span><span class="p">(</span><span class="s1">'Catching an argumentError'</span><span class="p">)</span>807<span class="gp">...</span>808<span class="go">Catching an argumentError</span>809</pre></div>810</div>811<div class="versionadded">812<p><span class="versionmodified added">Added in version 3.9.</span></p>813</div>814</section>815<section id="suggest-on-error">816<h3>suggest_on_error<a class="headerlink" href="#suggest-on-error" title="Link to this heading">¶</a></h3>817<p>By default, when a user passes an invalid argument choice or subparser name,818<a class="reference internal" href="#argparse.ArgumentParser" title="argparse.ArgumentParser"><code class="xref py py-class docutils literal notranslate"><span class="pre">ArgumentParser</span></code></a> will exit with error info and provide suggestions for819mistyped arguments. The error message will list the permissible argument820choices (if specified) or subparser names, along with a “maybe you meant”821suggestion if a close match is found. Note that this only applies for arguments822when the choices specified are strings:</p>823<div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="gp">>>> </span><span class="n">parser</span> <span class="o">=</span> <span class="n">argparse</span><span class="o">.</span><span class="n">ArgumentParser</span><span class="p">(</span><span class="n">suggest_on_error</span><span class="o">=</span><span class="kc">True</span><span class="p">)</span>824<span class="gp">>>> </span><span class="n">parser</span><span class="o">.</span><span class="n">add_argument</span><span class="p">(</span><span class="s1">'--action'</span><span class="p">,</span> <span class="n">choices</span><span class="o">=</span><span class="p">[</span><span class="s1">'debug'</span><span class="p">,</span> <span class="s1">'dryrun'</span><span class="p">])</span>825<span class="gp">>>> </span><span class="n">parser</span><span class="o">.</span><span class="n">parse_args</span><span class="p">([</span><span class="s1">'--action'</span><span class="p">,</span> <span class="s1">'debugg'</span><span class="p">])</span>826<span class="go">usage: tester.py [-h] [--action {debug,dryrun}]</span>827<span class="go">tester.py: error: argument --action: invalid choice: 'debugg', maybe you meant 'debug'? (choose from debug, dryrun)</span>828</pre></div>829</div>830<p>You can disable suggestions by setting <code class="docutils literal notranslate"><span class="pre">suggest_on_error</span></code> to <code class="docutils literal notranslate"><span class="pre">False</span></code>.</p>831<div class="versionadded">832<p><span class="versionmodified added">Added in version 3.14.</span></p>833</div>834<div class="versionchanged">835<p><span class="versionmodified changed">Changed in version 3.15: </span>Changed default value of <code class="docutils literal notranslate"><span class="pre">suggest_on_error</span></code> from <code class="docutils literal notranslate"><span class="pre">False</span></code> to <code class="docutils literal notranslate"><span class="pre">True</span></code>.</p>836</div>837</section>838<section id="color">839<h3>color<a class="headerlink" href="#color" title="Link to this heading">¶</a></h3>840<p>By default, the help message is printed in color using <a class="reference external" href="https://en.wikipedia.org/wiki/ANSI_escape_code">ANSI escape sequences</a>.841If you want plain text help messages, you can disable this <a class="reference internal" href="../using/cmdline.html#using-on-controlling-color"><span class="std std-ref">in your local842environment</span></a>, or in the argument parser itself843by setting <code class="docutils literal notranslate"><span class="pre">color</span></code> to <code class="docutils literal notranslate"><span class="pre">False</span></code>:</p>844<div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="gp">>>> </span><span class="n">parser</span> <span class="o">=</span> <span class="n">argparse</span><span class="o">.</span><span class="n">ArgumentParser</span><span class="p">(</span><span class="n">description</span><span class="o">=</span><span class="s1">'Process some integers.'</span><span class="p">,</span>845<span class="gp">... </span> <span class="n">color</span><span class="o">=</span><span class="kc">False</span><span class="p">)</span>846<span class="gp">>>> </span><span class="n">parser</span><span class="o">.</span><span class="n">add_argument</span><span class="p">(</span><span class="s1">'--action'</span><span class="p">,</span> <span class="n">choices</span><span class="o">=</span><span class="p">[</span><span class="s1">'sum'</span><span class="p">,</span> <span class="s1">'max'</span><span class="p">])</span>847<span class="gp">>>> </span><span class="n">parser</span><span class="o">.</span><span class="n">add_argument</span><span class="p">(</span><span class="s1">'integers'</span><span class="p">,</span> <span class="n">metavar</span><span class="o">=</span><span class="s1">'N'</span><span class="p">,</span> <span class="nb">type</span><span class="o">=</span><span class="nb">int</span><span class="p">,</span> <span class="n">nargs</span><span class="o">=</span><span class="s1">'+'</span><span class="p">,</span>848<span class="gp">... </span> <span class="n">help</span><span class="o">=</span><span class="s1">'an integer for the accumulator'</span><span class="p">)</span>849<span class="gp">>>> </span><span class="n">parser</span><span class="o">.</span><span class="n">parse_args</span><span class="p">([</span><span class="s1">'--help'</span><span class="p">])</span>850</pre></div>851</div>852<p>Note that when <code class="docutils literal notranslate"><span class="pre">color=True</span></code>, colored output depends on both environment853variables and terminal capabilities. However, if <code class="docutils literal notranslate"><span class="pre">color=False</span></code>, colored854output is always disabled, even if environment variables like <code class="docutils literal notranslate"><span class="pre">FORCE_COLOR</span></code>855are set.</p>856<div class="versionadded">857<p><span class="versionmodified added">Added in version 3.14.</span></p>858</div>859<p>To highlight inline code in your description or epilog text, you can use860backticks:</p>861<div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="gp">>>> </span><span class="n">parser</span> <span class="o">=</span> <span class="n">argparse</span><span class="o">.</span><span class="n">ArgumentParser</span><span class="p">(</span>862<span class="gp">... </span> <span class="n">formatter_class</span><span class="o">=</span><span class="n">argparse</span><span class="o">.</span><span class="n">RawDescriptionHelpFormatter</span><span class="p">,</span>863<span class="gp">... </span> <span class="n">epilog</span><span class="o">=</span><span class="s1">'''Examples:</span>864<span class="gp">... </span><span class="s1"> `python -m myapp --verbose`</span>865<span class="gp">... </span><span class="s1"> `python -m myapp --config settings.json`</span>866<span class="gp">... </span><span class="s1">'''</span><span class="p">)</span>867</pre></div>868</div>869<p>When colors are enabled, the text inside backticks will be displayed in a870distinct color to help examples stand out. When colors are disabled, backticks871are preserved as-is, which is readable in plain text.</p>872<div class="admonition note">873<p class="admonition-title">Note</p>874<p>Backtick markup only applies to description and epilog text. It does not875apply to individual argument <code class="docutils literal notranslate"><span class="pre">help</span></code> strings.</p>876</div>877<div class="versionadded">878<p><span class="versionmodified added">Added in version 3.15.</span></p>879</div>880</section>881</section>882<section id="the-add-argument-method">883<h2>The add_argument() method<a class="headerlink" href="#the-add-argument-method" title="Link to this heading">¶</a></h2>884<dl class="py method">885<dt class="sig sig-object py" id="argparse.ArgumentParser.add_argument">886<span class="sig-prename descclassname"><span class="pre">ArgumentParser.</span></span><span class="sig-name descname"><span class="pre">add_argument</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">name</span> <span class="pre">or</span> <span class="pre">flags...</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">*</span></span></em><span class="optional">[</span>, <em class="sig-param"><span class="n"><span class="pre">action</span></span></em><span class="optional">]</span><span class="optional">[</span>, <em class="sig-param"><span class="n"><span class="pre">nargs</span></span></em><span class="optional">]</span><span class="optional">[</span>, <em class="sig-param"><span class="n"><span class="pre">const</span></span></em><span class="optional">]</span><span class="optional">[</span>, <em class="sig-param"><span class="n"><span class="pre">default</span></span></em><span class="optional">]</span><span class="optional">[</span>, <em class="sig-param"><span class="n"><span class="pre">type</span></span></em><span class="optional">]</span><span class="optional">[</span>, <em class="sig-param"><span class="n"><span class="pre">choices</span></span></em><span class="optional">]</span><span class="optional">[</span>, <em class="sig-param"><span class="n"><span class="pre">required</span></span></em><span class="optional">]</span><span class="optional">[</span>, <em class="sig-param"><span class="n"><span class="pre">help</span></span></em><span class="optional">]</span><span class="optional">[</span>, <em class="sig-param"><span class="n"><span class="pre">metavar</span></span></em><span class="optional">]</span><span class="optional">[</span>, <em class="sig-param"><span class="n"><span class="pre">dest</span></span></em><span class="optional">]</span><span class="optional">[</span>, <em class="sig-param"><span class="n"><span class="pre">deprecated</span></span></em><span class="optional">]</span><span class="sig-paren">)</span><a class="headerlink" href="#argparse.ArgumentParser.add_argument" title="Link to this definition">¶</a></dt>887<dd><p>Define how a single command-line argument should be parsed. Each parameter888has its own more detailed description below, but in short they are:</p>889<ul class="simple">890<li><p><a class="reference internal" href="#name-or-flags">name or flags</a> - Either a name or a list of option strings, e.g. <code class="docutils literal notranslate"><span class="pre">'foo'</span></code>891or <code class="docutils literal notranslate"><span class="pre">'-f',</span> <span class="pre">'--foo'</span></code>.</p></li>892<li><p><a class="reference internal" href="#action">action</a> - The basic type of action to be taken when this argument is893encountered at the command line.</p></li>894<li><p><a class="reference internal" href="#nargs">nargs</a> - The number of command-line arguments that should be consumed.</p></li>895<li><p><a class="reference internal" href="#const">const</a> - A constant value required by some <a class="reference internal" href="#action">action</a> and <a class="reference internal" href="#nargs">nargs</a> selections.</p></li>896<li><p><a class="reference internal" href="#default">default</a> - The value produced if the argument is absent from the897command line and if it is absent from the namespace object.</p></li>898<li><p><a class="reference internal" href="#type">type</a> - The type to which the command-line argument should be converted.</p></li>899<li><p><a class="reference internal" href="#choices">choices</a> - A sequence of the allowable values for the argument.</p></li>900<li><p><a class="reference internal" href="#required">required</a> - Whether or not the command-line option may be omitted901(optionals only).</p></li>902<li><p><a class="reference internal" href="#help">help</a> - A brief description of what the argument does.</p></li>903<li><p><a class="reference internal" href="#metavar">metavar</a> - A name for the argument in usage messages.</p></li>904<li><p><a class="reference internal" href="#dest">dest</a> - The name of the attribute to be added to the object returned by905<a class="reference internal" href="#argparse.ArgumentParser.parse_args" title="argparse.ArgumentParser.parse_args"><code class="xref py py-meth docutils literal notranslate"><span class="pre">parse_args()</span></code></a>.</p></li>906<li><p><a class="reference internal" href="#deprecated">deprecated</a> - Whether or not use of the argument is deprecated.</p></li>907</ul>908<p>The method returns an <a class="reference internal" href="#argparse.Action" title="argparse.Action"><code class="xref py py-class docutils literal notranslate"><span class="pre">Action</span></code></a> object representing the argument.</p>909</dd></dl>910 911<p>The following sections describe how each of these are used.</p>912<section id="name-or-flags">913<span id="id5"></span><h3>name or flags<a class="headerlink" href="#name-or-flags" title="Link to this heading">¶</a></h3>914<p>The <a class="reference internal" href="#argparse.ArgumentParser.add_argument" title="argparse.ArgumentParser.add_argument"><code class="xref py py-meth docutils literal notranslate"><span class="pre">add_argument()</span></code></a> method must know whether an optional915argument, like <code class="docutils literal notranslate"><span class="pre">-f</span></code> or <code class="docutils literal notranslate"><span class="pre">--foo</span></code>, or a positional argument, like a list of916filenames, is expected. The first arguments passed to917<code class="xref py py-meth docutils literal notranslate"><span class="pre">add_argument()</span></code> must therefore be either a series of918flags, or a simple argument name.</p>919<p>For example, an optional argument could be created like:</p>920<div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="gp">>>> </span><span class="n">parser</span><span class="o">.</span><span class="n">add_argument</span><span class="p">(</span><span class="s1">'-f'</span><span class="p">,</span> <span class="s1">'--foo'</span><span class="p">)</span>921</pre></div>922</div>923<p>while a positional argument could be created like:</p>924<div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="gp">>>> </span><span class="n">parser</span><span class="o">.</span><span class="n">add_argument</span><span class="p">(</span><span class="s1">'bar'</span><span class="p">)</span>925</pre></div>926</div>927<p>When <a class="reference internal" href="#argparse.ArgumentParser.parse_args" title="argparse.ArgumentParser.parse_args"><code class="xref py py-meth docutils literal notranslate"><span class="pre">parse_args()</span></code></a> is called, optional arguments will be928identified by the <code class="docutils literal notranslate"><span class="pre">-</span></code> prefix, and the remaining arguments will be assumed to929be positional:</p>930<div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="gp">>>> </span><span class="n">parser</span> <span class="o">=</span> <span class="n">argparse</span><span class="o">.</span><span class="n">ArgumentParser</span><span class="p">(</span><span class="n">prog</span><span class="o">=</span><span class="s1">'PROG'</span><span class="p">)</span>931<span class="gp">>>> </span><span class="n">parser</span><span class="o">.</span><span class="n">add_argument</span><span class="p">(</span><span class="s1">'-f'</span><span class="p">,</span> <span class="s1">'--foo'</span><span class="p">)</span>932<span class="gp">>>> </span><span class="n">parser</span><span class="o">.</span><span class="n">add_argument</span><span class="p">(</span><span class="s1">'bar'</span><span class="p">)</span>933<span class="gp">>>> </span><span class="n">parser</span><span class="o">.</span><span class="n">parse_args</span><span class="p">([</span><span class="s1">'BAR'</span><span class="p">])</span>934<span class="go">Namespace(bar='BAR', foo=None)</span>935<span class="gp">>>> </span><span class="n">parser</span><span class="o">.</span><span class="n">parse_args</span><span class="p">([</span><span class="s1">'BAR'</span><span class="p">,</span> <span class="s1">'--foo'</span><span class="p">,</span> <span class="s1">'FOO'</span><span class="p">])</span>936<span class="go">Namespace(bar='BAR', foo='FOO')</span>937<span class="gp">>>> </span><span class="n">parser</span><span class="o">.</span><span class="n">parse_args</span><span class="p">([</span><span class="s1">'--foo'</span><span class="p">,</span> <span class="s1">'FOO'</span><span class="p">])</span>938<span class="go">usage: PROG [-h] [-f FOO] bar</span>939<span class="go">PROG: error: the following arguments are required: bar</span>940</pre></div>941</div>942<p>By default, <code class="xref py py-mod docutils literal notranslate"><span class="pre">argparse</span></code> automatically handles the internal naming and943display names of arguments, simplifying the process without requiring944additional configuration.945As such, you do not need to specify the <a class="reference internal" href="#dest">dest</a> and <a class="reference internal" href="#metavar">metavar</a> parameters.946For optional arguments, the <a class="reference internal" href="#dest">dest</a> parameter defaults to the argument name, with947underscores <code class="docutils literal notranslate"><span class="pre">_</span></code> replacing hyphens <code class="docutils literal notranslate"><span class="pre">-</span></code>. The <a class="reference internal" href="#metavar">metavar</a> parameter defaults to948the upper-cased name. For example:</p>949<div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="gp">>>> </span><span class="n">parser</span> <span class="o">=</span> <span class="n">argparse</span><span class="o">.</span><span class="n">ArgumentParser</span><span class="p">(</span><span class="n">prog</span><span class="o">=</span><span class="s1">'PROG'</span><span class="p">)</span>950<span class="gp">>>> </span><span class="n">parser</span><span class="o">.</span><span class="n">add_argument</span><span class="p">(</span><span class="s1">'--foo-bar'</span><span class="p">)</span>951<span class="gp">>>> </span><span class="n">parser</span><span class="o">.</span><span class="n">parse_args</span><span class="p">([</span><span class="s1">'--foo-bar'</span><span class="p">,</span> <span class="s1">'FOO-BAR'</span><span class="p">])</span>952<span class="go">Namespace(foo_bar='FOO-BAR')</span>953<span class="gp">>>> </span><span class="n">parser</span><span class="o">.</span><span class="n">print_help</span><span class="p">()</span>954<span class="go">usage: [-h] [--foo-bar FOO-BAR]</span>955 956<span class="go">optional arguments:</span>957<span class="go"> -h, --help show this help message and exit</span>958<span class="go"> --foo-bar FOO-BAR</span>959</pre></div>960</div>961</section>962<section id="action">963<span id="id6"></span><h3>action<a class="headerlink" href="#action" title="Link to this heading">¶</a></h3>964<p><a class="reference internal" href="#argparse.ArgumentParser" title="argparse.ArgumentParser"><code class="xref py py-class docutils literal notranslate"><span class="pre">ArgumentParser</span></code></a> objects associate command-line arguments with actions. These965actions can do just about anything with the command-line arguments associated with966them, though most actions simply add an attribute to the object returned by967<a class="reference internal" href="#argparse.ArgumentParser.parse_args" title="argparse.ArgumentParser.parse_args"><code class="xref py py-meth docutils literal notranslate"><span class="pre">parse_args()</span></code></a>. The <code class="docutils literal notranslate"><span class="pre">action</span></code> keyword argument specifies968how the command-line arguments should be handled. The supplied actions are:</p>969<ul>970<li><p><code class="docutils literal notranslate"><span class="pre">'store'</span></code> - This just stores the argument’s value. This is the default971action.</p></li>972<li><p><code class="docutils literal notranslate"><span class="pre">'store_const'</span></code> - This stores the value specified by the <a class="reference internal" href="#const">const</a> keyword973argument; note that the <a class="reference internal" href="#const">const</a> keyword argument defaults to <code class="docutils literal notranslate"><span class="pre">None</span></code>. The974<code class="docutils literal notranslate"><span class="pre">'store_const'</span></code> action is most commonly used with optional arguments that975specify some sort of flag. For example:</p>976<div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="gp">>>> </span><span class="n">parser</span> <span class="o">=</span> <span class="n">argparse</span><span class="o">.</span><span class="n">ArgumentParser</span><span class="p">()</span>977<span class="gp">>>> </span><span class="n">parser</span><span class="o">.</span><span class="n">add_argument</span><span class="p">(</span><span class="s1">'--foo'</span><span class="p">,</span> <span class="n">action</span><span class="o">=</span><span class="s1">'store_const'</span><span class="p">,</span> <span class="n">const</span><span class="o">=</span><span class="mi">42</span><span class="p">)</span>978<span class="gp">>>> </span><span class="n">parser</span><span class="o">.</span><span class="n">parse_args</span><span class="p">([</span><span class="s1">'--foo'</span><span class="p">])</span>979<span class="go">Namespace(foo=42)</span>980</pre></div>981</div>982</li>983<li><p><code class="docutils literal notranslate"><span class="pre">'store_true'</span></code> and <code class="docutils literal notranslate"><span class="pre">'store_false'</span></code> - These are special cases of984<code class="docutils literal notranslate"><span class="pre">'store_const'</span></code> that respectively store the values <code class="docutils literal notranslate"><span class="pre">True</span></code> and <code class="docutils literal notranslate"><span class="pre">False</span></code>985with default values of <code class="docutils literal notranslate"><span class="pre">False</span></code> and986<code class="docutils literal notranslate"><span class="pre">True</span></code>:</p>987<div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="gp">>>> </span><span class="n">parser</span> <span class="o">=</span> <span class="n">argparse</span><span class="o">.</span><span class="n">ArgumentParser</span><span class="p">()</span>988<span class="gp">>>> </span><span class="n">parser</span><span class="o">.</span><span class="n">add_argument</span><span class="p">(</span><span class="s1">'--foo'</span><span class="p">,</span> <span class="n">action</span><span class="o">=</span><span class="s1">'store_true'</span><span class="p">)</span>989<span class="gp">>>> </span><span class="n">parser</span><span class="o">.</span><span class="n">add_argument</span><span class="p">(</span><span class="s1">'--bar'</span><span class="p">,</span> <span class="n">action</span><span class="o">=</span><span class="s1">'store_false'</span><span class="p">)</span>990<span class="gp">>>> </span><span class="n">parser</span><span class="o">.</span><span class="n">add_argument</span><span class="p">(</span><span class="s1">'--baz'</span><span class="p">,</span> <span class="n">action</span><span class="o">=</span><span class="s1">'store_false'</span><span class="p">)</span>991<span class="gp">>>> </span><span class="n">parser</span><span class="o">.</span><span class="n">parse_args</span><span class="p">(</span><span class="s1">'--foo --bar'</span><span class="o">.</span><span class="n">split</span><span class="p">())</span>992<span class="go">Namespace(foo=True, bar=False, baz=True)</span>993</pre></div>994</div>995</li>996<li><p><code class="docutils literal notranslate"><span class="pre">'append'</span></code> - This appends each argument value to a list.997It is useful for allowing an option to be specified multiple times.998If the default value is a non-empty list, the parsed value will start999with the default list’s elements and any values from the command line1000will be appended after those default values. Example usage:</p>1001<div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="gp">>>> </span><span class="n">parser</span> <span class="o">=</span> <span class="n">argparse</span><span class="o">.</span><span class="n">ArgumentParser</span><span class="p">()</span>1002<span class="gp">>>> </span><span class="n">parser</span><span class="o">.</span><span class="n">add_argument</span><span class="p">(</span><span class="s1">'--foo'</span><span class="p">,</span> <span class="n">action</span><span class="o">=</span><span class="s1">'append'</span><span class="p">,</span> <span class="n">default</span><span class="o">=</span><span class="p">[</span><span class="s1">'0'</span><span class="p">])</span>1003<span class="gp">>>> </span><span class="n">parser</span><span class="o">.</span><span class="n">parse_args</span><span class="p">(</span><span class="s1">'--foo 1 --foo 2'</span><span class="o">.</span><span class="n">split</span><span class="p">())</span>1004<span class="go">Namespace(foo=['0', '1', '2'])</span>1005</pre></div>1006</div>1007</li>1008<li><p><code class="docutils literal notranslate"><span class="pre">'append_const'</span></code> - This appends the value specified by1009the <a class="reference internal" href="#const">const</a> keyword argument to a list; note that the <a class="reference internal" href="#const">const</a> keyword1010argument defaults to <code class="docutils literal notranslate"><span class="pre">None</span></code>. The <code class="docutils literal notranslate"><span class="pre">'append_const'</span></code> action is typically1011useful when multiple arguments need to store constants to the same list. For1012example:</p>1013<div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="gp">>>> </span><span class="n">parser</span> <span class="o">=</span> <span class="n">argparse</span><span class="o">.</span><span class="n">ArgumentParser</span><span class="p">()</span>1014<span class="gp">>>> </span><span class="n">parser</span><span class="o">.</span><span class="n">add_argument</span><span class="p">(</span><span class="s1">'--str'</span><span class="p">,</span> <span class="n">dest</span><span class="o">=</span><span class="s1">'types'</span><span class="p">,</span> <span class="n">action</span><span class="o">=</span><span class="s1">'append_const'</span><span class="p">,</span> <span class="n">const</span><span class="o">=</span><span class="nb">str</span><span class="p">)</span>1015<span class="gp">>>> </span><span class="n">parser</span><span class="o">.</span><span class="n">add_argument</span><span class="p">(</span><span class="s1">'--int'</span><span class="p">,</span> <span class="n">dest</span><span class="o">=</span><span class="s1">'types'</span><span class="p">,</span> <span class="n">action</span><span class="o">=</span><span class="s1">'append_const'</span><span class="p">,</span> <span class="n">const</span><span class="o">=</span><span class="nb">int</span><span class="p">)</span>1016<span class="gp">>>> </span><span class="n">parser</span><span class="o">.</span><span class="n">parse_args</span><span class="p">(</span><span class="s1">'--str --int'</span><span class="o">.</span><span class="n">split</span><span class="p">())</span>1017<span class="go">Namespace(types=[<class 'str'>, <class 'int'>])</span>1018</pre></div>1019</div>1020</li>1021<li><p><code class="docutils literal notranslate"><span class="pre">'extend'</span></code> - This appends each item from a multi-value1022argument to a list.1023The <code class="docutils literal notranslate"><span class="pre">'extend'</span></code> action is typically used with the <a class="reference internal" href="#nargs">nargs</a> keyword argument1024value <code class="docutils literal notranslate"><span class="pre">'+'</span></code> or <code class="docutils literal notranslate"><span class="pre">'*'</span></code>.1025Note that when <a class="reference internal" href="#nargs">nargs</a> is <code class="docutils literal notranslate"><span class="pre">None</span></code> (the default) or <code class="docutils literal notranslate"><span class="pre">'?'</span></code>, each1026character of the argument string will be appended to the list.1027Example usage:</p>1028<div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="gp">>>> </span><span class="n">parser</span> <span class="o">=</span> <span class="n">argparse</span><span class="o">.</span><span class="n">ArgumentParser</span><span class="p">()</span>1029<span class="gp">>>> </span><span class="n">parser</span><span class="o">.</span><span class="n">add_argument</span><span class="p">(</span><span class="s2">"--foo"</span><span class="p">,</span> <span class="n">action</span><span class="o">=</span><span class="s2">"extend"</span><span class="p">,</span> <span class="n">nargs</span><span class="o">=</span><span class="s2">"+"</span><span class="p">,</span> <span class="nb">type</span><span class="o">=</span><span class="nb">str</span><span class="p">)</span>1030<span class="gp">>>> </span><span class="n">parser</span><span class="o">.</span><span class="n">parse_args</span><span class="p">([</span><span class="s2">"--foo"</span><span class="p">,</span> <span class="s2">"f1"</span><span class="p">,</span> <span class="s2">"--foo"</span><span class="p">,</span> <span class="s2">"f2"</span><span class="p">,</span> <span class="s2">"f3"</span><span class="p">,</span> <span class="s2">"f4"</span><span class="p">])</span>1031<span class="go">Namespace(foo=['f1', 'f2', 'f3', 'f4'])</span>1032</pre></div>1033</div>1034<div class="versionadded">1035<p><span class="versionmodified added">Added in version 3.8.</span></p>1036</div>1037</li>1038<li><p><code class="docutils literal notranslate"><span class="pre">'count'</span></code> - This counts the number of times an argument occurs. For1039example, this is useful for increasing verbosity levels:</p>1040<div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="gp">>>> </span><span class="n">parser</span> <span class="o">=</span> <span class="n">argparse</span><span class="o">.</span><span class="n">ArgumentParser</span><span class="p">()</span>1041<span class="gp">>>> </span><span class="n">parser</span><span class="o">.</span><span class="n">add_argument</span><span class="p">(</span><span class="s1">'--verbose'</span><span class="p">,</span> <span class="s1">'-v'</span><span class="p">,</span> <span class="n">action</span><span class="o">=</span><span class="s1">'count'</span><span class="p">,</span> <span class="n">default</span><span class="o">=</span><span class="mi">0</span><span class="p">)</span>1042<span class="gp">>>> </span><span class="n">parser</span><span class="o">.</span><span class="n">parse_args</span><span class="p">([</span><span class="s1">'-vvv'</span><span class="p">])</span>1043<span class="go">Namespace(verbose=3)</span>1044</pre></div>1045</div>1046<p>Note, the <em>default</em> will be <code class="docutils literal notranslate"><span class="pre">None</span></code> unless explicitly set to <em>0</em>.</p>1047</li>1048<li><p><code class="docutils literal notranslate"><span class="pre">'help'</span></code> - This prints a complete help message for all the options in the1049current parser and then exits. By default a help action is automatically1050added to the parser. See <a class="reference internal" href="#argparse.ArgumentParser" title="argparse.ArgumentParser"><code class="xref py py-class docutils literal notranslate"><span class="pre">ArgumentParser</span></code></a> for details of how the1051output is created.</p></li>1052<li><p><code class="docutils literal notranslate"><span class="pre">'version'</span></code> - This expects a <code class="docutils literal notranslate"><span class="pre">version=</span></code> keyword argument in the1053<a class="reference internal" href="#argparse.ArgumentParser.add_argument" title="argparse.ArgumentParser.add_argument"><code class="xref py py-meth docutils literal notranslate"><span class="pre">add_argument()</span></code></a> call, and prints version information1054and exits when invoked:</p>1055<div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="gp">>>> </span><span class="kn">import</span><span class="w"> </span><span class="nn">argparse</span>1056<span class="gp">>>> </span><span class="n">parser</span> <span class="o">=</span> <span class="n">argparse</span><span class="o">.</span><span class="n">ArgumentParser</span><span class="p">(</span><span class="n">prog</span><span class="o">=</span><span class="s1">'PROG'</span><span class="p">)</span>1057<span class="gp">>>> </span><span class="n">parser</span><span class="o">.</span><span class="n">add_argument</span><span class="p">(</span><span class="s1">'--version'</span><span class="p">,</span> <span class="n">action</span><span class="o">=</span><span class="s1">'version'</span><span class="p">,</span> <span class="n">version</span><span class="o">=</span><span class="s1">'</span><span class="si">%(prog)s</span><span class="s1"> 2.0'</span><span class="p">)</span>1058<span class="gp">>>> </span><span class="n">parser</span><span class="o">.</span><span class="n">parse_args</span><span class="p">([</span><span class="s1">'--version'</span><span class="p">])</span>1059<span class="go">PROG 2.0</span>1060</pre></div>1061</div>1062</li>1063</ul>1064<p>You may also specify an arbitrary action by passing an <a class="reference internal" href="#argparse.Action" title="argparse.Action"><code class="xref py py-class docutils literal notranslate"><span class="pre">Action</span></code></a> subclass1065(e.g. <a class="reference internal" href="#argparse.BooleanOptionalAction" title="argparse.BooleanOptionalAction"><code class="xref py py-class docutils literal notranslate"><span class="pre">BooleanOptionalAction</span></code></a>) or other object that implements the same1066interface. Only actions that consume command-line arguments (e.g. <code class="docutils literal notranslate"><span class="pre">'store'</span></code>,1067<code class="docutils literal notranslate"><span class="pre">'append'</span></code>, <code class="docutils literal notranslate"><span class="pre">'extend'</span></code>, or custom actions with non-zero <code class="docutils literal notranslate"><span class="pre">nargs</span></code>) can be used1068with positional arguments.</p>1069<p>The recommended way to create a custom action is to extend <a class="reference internal" href="#argparse.Action" title="argparse.Action"><code class="xref py py-class docutils literal notranslate"><span class="pre">Action</span></code></a>,1070overriding the <code class="xref py py-meth docutils literal notranslate"><span class="pre">__call__()</span></code> method and optionally the <code class="xref py py-meth docutils literal notranslate"><span class="pre">__init__()</span></code> and1071<code class="xref py py-meth docutils literal notranslate"><span class="pre">format_usage()</span></code> methods. You can also register custom actions using the1072<a class="reference internal" href="#argparse.ArgumentParser.register" title="argparse.ArgumentParser.register"><code class="xref py py-meth docutils literal notranslate"><span class="pre">register()</span></code></a> method and reference them by their registered name.</p>1073<p>An example of a custom action:</p>1074<div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="gp">>>> </span><span class="k">class</span><span class="w"> </span><span class="nc">FooAction</span><span class="p">(</span><span class="n">argparse</span><span class="o">.</span><span class="n">Action</span><span class="p">):</span>1075<span class="gp">... </span> <span class="k">def</span><span class="w"> </span><span class="fm">__init__</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="n">option_strings</span><span class="p">,</span> <span class="n">dest</span><span class="p">,</span> <span class="n">nargs</span><span class="o">=</span><span class="kc">None</span><span class="p">,</span> <span class="o">**</span><span class="n">kwargs</span><span class="p">):</span>1076<span class="gp">... </span> <span class="k">if</span> <span class="n">nargs</span> <span class="ow">is</span> <span class="ow">not</span> <span class="kc">None</span><span class="p">:</span>1077<span class="gp">... </span> <span class="k">raise</span> <span class="ne">ValueError</span><span class="p">(</span><span class="s2">"nargs not allowed"</span><span class="p">)</span>1078<span class="gp">... </span> <span class="nb">super</span><span class="p">()</span><span class="o">.</span><span class="fm">__init__</span><span class="p">(</span><span class="n">option_strings</span><span class="p">,</span> <span class="n">dest</span><span class="p">,</span> <span class="o">**</span><span class="n">kwargs</span><span class="p">)</span>1079<span class="gp">... </span> <span class="k">def</span><span class="w"> </span><span class="fm">__call__</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="n">parser</span><span class="p">,</span> <span class="n">namespace</span><span class="p">,</span> <span class="n">values</span><span class="p">,</span> <span class="n">option_string</span><span class="o">=</span><span class="kc">None</span><span class="p">):</span>1080<span class="gp">... </span> <span class="nb">print</span><span class="p">(</span><span class="s1">'</span><span class="si">%r</span><span class="s1"> </span><span class="si">%r</span><span class="s1"> </span><span class="si">%r</span><span class="s1">'</span> <span class="o">%</span> <span class="p">(</span><span class="n">namespace</span><span class="p">,</span> <span class="n">values</span><span class="p">,</span> <span class="n">option_string</span><span class="p">))</span>1081<span class="gp">... </span> <span class="nb">setattr</span><span class="p">(</span><span class="n">namespace</span><span class="p">,</span> <span class="bp">self</span><span class="o">.</span><span class="n">dest</span><span class="p">,</span> <span class="n">values</span><span class="p">)</span>1082<span class="gp">...</span>1083<span class="gp">>>> </span><span class="n">parser</span> <span class="o">=</span> <span class="n">argparse</span><span class="o">.</span><span class="n">ArgumentParser</span><span class="p">()</span>1084<span class="gp">>>> </span><span class="n">parser</span><span class="o">.</span><span class="n">add_argument</span><span class="p">(</span><span class="s1">'--foo'</span><span class="p">,</span> <span class="n">action</span><span class="o">=</span><span class="n">FooAction</span><span class="p">)</span>1085<span class="gp">>>> </span><span class="n">parser</span><span class="o">.</span><span class="n">add_argument</span><span class="p">(</span><span class="s1">'bar'</span><span class="p">,</span> <span class="n">action</span><span class="o">=</span><span class="n">FooAction</span><span class="p">)</span>1086<span class="gp">>>> </span><span class="n">args</span> <span class="o">=</span> <span class="n">parser</span><span class="o">.</span><span class="n">parse_args</span><span class="p">(</span><span class="s1">'1 --foo 2'</span><span class="o">.</span><span class="n">split</span><span class="p">())</span>1087<span class="go">Namespace(bar=None, foo=None) '1' None</span>1088<span class="go">Namespace(bar='1', foo=None) '2' '--foo'</span>1089<span class="gp">>>> </span><span class="n">args</span>1090<span class="go">Namespace(bar='1', foo='2')</span>1091</pre></div>1092</div>1093<p>For more details, see <a class="reference internal" href="#argparse.Action" title="argparse.Action"><code class="xref py py-class docutils literal notranslate"><span class="pre">Action</span></code></a>.</p>1094</section>1095<section id="nargs">1096<span id="id7"></span><h3>nargs<a class="headerlink" href="#nargs" title="Link to this heading">¶</a></h3>1097<p><a class="reference internal" href="#argparse.ArgumentParser" title="argparse.ArgumentParser"><code class="xref py py-class docutils literal notranslate"><span class="pre">ArgumentParser</span></code></a> objects usually associate a single command-line argument with a1098single action to be taken. The <code class="docutils literal notranslate"><span class="pre">nargs</span></code> keyword argument associates a1099different number of command-line arguments with a single action.1100See also <a class="reference internal" href="../howto/argparse.html#specifying-ambiguous-arguments"><span class="std std-ref">Specifying ambiguous arguments</span></a>. The supported values are:</p>1101<ul>1102<li><p><code class="docutils literal notranslate"><span class="pre">N</span></code> (an integer). <code class="docutils literal notranslate"><span class="pre">N</span></code> arguments from the command line will be gathered1103together into a list. For example:</p>1104<div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="gp">>>> </span><span class="n">parser</span> <span class="o">=</span> <span class="n">argparse</span><span class="o">.</span><span class="n">ArgumentParser</span><span class="p">()</span>1105<span class="gp">>>> </span><span class="n">parser</span><span class="o">.</span><span class="n">add_argument</span><span class="p">(</span><span class="s1">'--foo'</span><span class="p">,</span> <span class="n">nargs</span><span class="o">=</span><span class="mi">2</span><span class="p">)</span>1106<span class="gp">>>> </span><span class="n">parser</span><span class="o">.</span><span class="n">add_argument</span><span class="p">(</span><span class="s1">'bar'</span><span class="p">,</span> <span class="n">nargs</span><span class="o">=</span><span class="mi">1</span><span class="p">)</span>1107<span class="gp">>>> </span><span class="n">parser</span><span class="o">.</span><span class="n">parse_args</span><span class="p">(</span><span class="s1">'c --foo a b'</span><span class="o">.</span><span class="n">split</span><span class="p">())</span>1108<span class="go">Namespace(bar=['c'], foo=['a', 'b'])</span>1109</pre></div>1110</div>1111<p>Note that <code class="docutils literal notranslate"><span class="pre">nargs=1</span></code> produces a list of one item. This is different from1112the default, in which the item is produced by itself.</p>1113</li>1114</ul>1115<ul id="index-0">1116<li><p><code class="docutils literal notranslate"><span class="pre">'?'</span></code>. One argument will be consumed from the command line if possible, and1117produced as a single item. If no command-line argument is present, the value from1118<a class="reference internal" href="#default">default</a> will be produced. Note that for optional arguments, there is an1119additional case - the option string is present but not followed by a1120command-line argument. In this case the value from <a class="reference internal" href="#const">const</a> will be produced. Some1121examples to illustrate this:</p>1122<div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="gp">>>> </span><span class="n">parser</span> <span class="o">=</span> <span class="n">argparse</span><span class="o">.</span><span class="n">ArgumentParser</span><span class="p">()</span>1123<span class="gp">>>> </span><span class="n">parser</span><span class="o">.</span><span class="n">add_argument</span><span class="p">(</span><span class="s1">'--foo'</span><span class="p">,</span> <span class="n">nargs</span><span class="o">=</span><span class="s1">'?'</span><span class="p">,</span> <span class="n">const</span><span class="o">=</span><span class="s1">'c'</span><span class="p">,</span> <span class="n">default</span><span class="o">=</span><span class="s1">'d'</span><span class="p">)</span>1124<span class="gp">>>> </span><span class="n">parser</span><span class="o">.</span><span class="n">add_argument</span><span class="p">(</span><span class="s1">'bar'</span><span class="p">,</span> <span class="n">nargs</span><span class="o">=</span><span class="s1">'?'</span><span class="p">,</span> <span class="n">default</span><span class="o">=</span><span class="s1">'d'</span><span class="p">)</span>1125<span class="gp">>>> </span><span class="n">parser</span><span class="o">.</span><span class="n">parse_args</span><span class="p">([</span><span class="s1">'XX'</span><span class="p">,</span> <span class="s1">'--foo'</span><span class="p">,</span> <span class="s1">'YY'</span><span class="p">])</span>1126<span class="go">Namespace(bar='XX', foo='YY')</span>1127<span class="gp">>>> </span><span class="n">parser</span><span class="o">.</span><span class="n">parse_args</span><span class="p">([</span><span class="s1">'XX'</span><span class="p">,</span> <span class="s1">'--foo'</span><span class="p">])</span>1128<span class="go">Namespace(bar='XX', foo='c')</span>1129<span class="gp">>>> </span><span class="n">parser</span><span class="o">.</span><span class="n">parse_args</span><span class="p">([])</span>1130<span class="go">Namespace(bar='d', foo='d')</span>1131</pre></div>1132</div>1133<p>One of the more common uses of <code class="docutils literal notranslate"><span class="pre">nargs='?'</span></code> is to allow optional input and1134output files:</p>1135<div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="gp">>>> </span><span class="n">parser</span> <span class="o">=</span> <span class="n">argparse</span><span class="o">.</span><span class="n">ArgumentParser</span><span class="p">()</span>1136<span class="gp">>>> </span><span class="n">parser</span><span class="o">.</span><span class="n">add_argument</span><span class="p">(</span><span class="s1">'infile'</span><span class="p">,</span> <span class="n">nargs</span><span class="o">=</span><span class="s1">'?'</span><span class="p">)</span>1137<span class="gp">>>> </span><span class="n">parser</span><span class="o">.</span><span class="n">add_argument</span><span class="p">(</span><span class="s1">'outfile'</span><span class="p">,</span> <span class="n">nargs</span><span class="o">=</span><span class="s1">'?'</span><span class="p">)</span>1138<span class="gp">>>> </span><span class="n">parser</span><span class="o">.</span><span class="n">parse_args</span><span class="p">([</span><span class="s1">'input.txt'</span><span class="p">,</span> <span class="s1">'output.txt'</span><span class="p">])</span>1139<span class="go">Namespace(infile='input.txt', outfile='output.txt')</span>1140<span class="gp">>>> </span><span class="n">parser</span><span class="o">.</span><span class="n">parse_args</span><span class="p">([</span><span class="s1">'input.txt'</span><span class="p">])</span>1141<span class="go">Namespace(infile='input.txt', outfile=None)</span>1142<span class="gp">>>> </span><span class="n">parser</span><span class="o">.</span><span class="n">parse_args</span><span class="p">([])</span>1143<span class="go">Namespace(infile=None, outfile=None)</span>1144</pre></div>1145</div>1146</li>1147</ul>1148<ul id="index-1">1149<li><p><code class="docutils literal notranslate"><span class="pre">'*'</span></code>. All command-line arguments present are gathered into a list. Note that1150it generally doesn’t make much sense to have more than one positional argument1151with <code class="docutils literal notranslate"><span class="pre">nargs='*'</span></code>, but multiple optional arguments with <code class="docutils literal notranslate"><span class="pre">nargs='*'</span></code> is1152possible. For example:</p>1153<div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="gp">>>> </span><span class="n">parser</span> <span class="o">=</span> <span class="n">argparse</span><span class="o">.</span><span class="n">ArgumentParser</span><span class="p">()</span>1154<span class="gp">>>> </span><span class="n">parser</span><span class="o">.</span><span class="n">add_argument</span><span class="p">(</span><span class="s1">'--foo'</span><span class="p">,</span> <span class="n">nargs</span><span class="o">=</span><span class="s1">'*'</span><span class="p">)</span>1155<span class="gp">>>> </span><span class="n">parser</span><span class="o">.</span><span class="n">add_argument</span><span class="p">(</span><span class="s1">'--bar'</span><span class="p">,</span> <span class="n">nargs</span><span class="o">=</span><span class="s1">'*'</span><span class="p">)</span>1156<span class="gp">>>> </span><span class="n">parser</span><span class="o">.</span><span class="n">add_argument</span><span class="p">(</span><span class="s1">'baz'</span><span class="p">,</span> <span class="n">nargs</span><span class="o">=</span><span class="s1">'*'</span><span class="p">)</span>1157<span class="gp">>>> </span><span class="n">parser</span><span class="o">.</span><span class="n">parse_args</span><span class="p">(</span><span class="s1">'a b --foo x y --bar 1 2'</span><span class="o">.</span><span class="n">split</span><span class="p">())</span>1158<span class="go">Namespace(bar=['1', '2'], baz=['a', 'b'], foo=['x', 'y'])</span>1159</pre></div>1160</div>1161</li>1162</ul>1163<ul id="index-2">1164<li><p><code class="docutils literal notranslate"><span class="pre">'+'</span></code>. Just like <code class="docutils literal notranslate"><span class="pre">'*'</span></code>, all command-line arguments present are gathered into a1165list. Additionally, an error message will be generated if there wasn’t at1166least one command-line argument present. For example:</p>1167<div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="gp">>>> </span><span class="n">parser</span> <span class="o">=</span> <span class="n">argparse</span><span class="o">.</span><span class="n">ArgumentParser</span><span class="p">(</span><span class="n">prog</span><span class="o">=</span><span class="s1">'PROG'</span><span class="p">)</span>1168<span class="gp">>>> </span><span class="n">parser</span><span class="o">.</span><span class="n">add_argument</span><span class="p">(</span><span class="s1">'foo'</span><span class="p">,</span> <span class="n">nargs</span><span class="o">=</span><span class="s1">'+'</span><span class="p">)</span>1169<span class="gp">>>> </span><span class="n">parser</span><span class="o">.</span><span class="n">parse_args</span><span class="p">([</span><span class="s1">'a'</span><span class="p">,</span> <span class="s1">'b'</span><span class="p">])</span>1170<span class="go">Namespace(foo=['a', 'b'])</span>1171<span class="gp">>>> </span><span class="n">parser</span><span class="o">.</span><span class="n">parse_args</span><span class="p">([])</span>1172<span class="go">usage: PROG [-h] foo [foo ...]</span>1173<span class="go">PROG: error: the following arguments are required: foo</span>1174</pre></div>1175</div>1176</li>1177</ul>1178<p>If the <code class="docutils literal notranslate"><span class="pre">nargs</span></code> keyword argument is not provided, the number of arguments consumed1179is determined by the <a class="reference internal" href="#action">action</a>. Generally this means a single command-line argument1180will be consumed and a single item (not a list) will be produced.1181Actions that do not consume command-line arguments (e.g.1182<code class="docutils literal notranslate"><span class="pre">'store_const'</span></code>) set <code class="docutils literal notranslate"><span class="pre">nargs=0</span></code>.</p>1183</section>1184<section id="const">1185<span id="id8"></span><h3>const<a class="headerlink" href="#const" title="Link to this heading">¶</a></h3>1186<p>The <code class="docutils literal notranslate"><span class="pre">const</span></code> argument of <a class="reference internal" href="#argparse.ArgumentParser.add_argument" title="argparse.ArgumentParser.add_argument"><code class="xref py py-meth docutils literal notranslate"><span class="pre">add_argument()</span></code></a> is used to hold1187constant values that are not read from the command line but are required for1188the various <a class="reference internal" href="#argparse.ArgumentParser" title="argparse.ArgumentParser"><code class="xref py py-class docutils literal notranslate"><span class="pre">ArgumentParser</span></code></a> actions. The two most common uses of it are:</p>1189<ul class="simple">1190<li><p>When <a class="reference internal" href="#argparse.ArgumentParser.add_argument" title="argparse.ArgumentParser.add_argument"><code class="xref py py-meth docutils literal notranslate"><span class="pre">add_argument()</span></code></a> is called with1191<code class="docutils literal notranslate"><span class="pre">action='store_const'</span></code> or <code class="docutils literal notranslate"><span class="pre">action='append_const'</span></code>. These actions add the1192<code class="docutils literal notranslate"><span class="pre">const</span></code> value to one of the attributes of the object returned by1193<a class="reference internal" href="#argparse.ArgumentParser.parse_args" title="argparse.ArgumentParser.parse_args"><code class="xref py py-meth docutils literal notranslate"><span class="pre">parse_args()</span></code></a>. See the <a class="reference internal" href="#action">action</a> description for examples.1194If <code class="docutils literal notranslate"><span class="pre">const</span></code> is not provided to <code class="xref py py-meth docutils literal notranslate"><span class="pre">add_argument()</span></code>, it will1195receive a default value of <code class="docutils literal notranslate"><span class="pre">None</span></code>.</p></li>1196<li><p>When <a class="reference internal" href="#argparse.ArgumentParser.add_argument" title="argparse.ArgumentParser.add_argument"><code class="xref py py-meth docutils literal notranslate"><span class="pre">add_argument()</span></code></a> is called with option strings1197(like <code class="docutils literal notranslate"><span class="pre">-f</span></code> or <code class="docutils literal notranslate"><span class="pre">--foo</span></code>) and <code class="docutils literal notranslate"><span class="pre">nargs='?'</span></code>. This creates an optional1198argument that can be followed by zero or one command-line arguments.1199When parsing the command line, if the option string is encountered with no1200command-line argument following it, the value from <code class="docutils literal notranslate"><span class="pre">const</span></code> will be used.