Spaces:

parthtamu
/

rag-code-assistant

Sleeping

File size: 328,514 Bytes

dcac338

<!DOCTYPE html>

<html lang="en" data-content_root="../">
  <head>
    <meta charset="utf-8" />
    <meta name="viewport" content="width=device-width, initial-scale=1.0" /><meta name="viewport" content="width=device-width, initial-scale=1" />
<meta property="og:title" content="argparse — Parser for command-line options, arguments and subcommands" />
<meta property="og:type" content="website" />
<meta property="og:url" content="https://docs.python.org/3/library/argparse.html" />
<meta property="og:site_name" content="Python documentation" />
<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..." />
<meta property="og:image:width" content="1146" />
<meta property="og:image:height" content="600" />
<meta property="og:image" content="https://docs.python.org/3.15/_images/social_previews/summary_library_argparse_3f064f33.png" />
<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..." />
<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..." />
<meta name="twitter:card" content="summary_large_image" />
<meta name="theme-color" content="#3776ab">

    <title>argparse — Parser for command-line options, arguments and subcommands &#8212; Python 3.15.0a6 documentation</title><meta name="viewport" content="width=device-width, initial-scale=1.0">
    
    <link rel="stylesheet" type="text/css" href="../_static/pygments.css?v=b86133f3" />
    <link rel="stylesheet" type="text/css" href="../_static/classic.css?v=234b1a7c" />
    <link rel="stylesheet" type="text/css" href="../_static/pydoctheme.css?v=89a2f22a" />
    <link rel="stylesheet" type="text/css" href="../_static/profiling-sampling-visualization.css?v=0c2600ae" />
    <link id="pygments_dark_css" media="(prefers-color-scheme: dark)" rel="stylesheet" type="text/css" href="../_static/pygments_dark.css?v=5349f25f" />
    
    <script src="../_static/documentation_options.js?v=6b7c9ff5"></script>
    <script src="../_static/doctools.js?v=9bcbadda"></script>
    <script src="../_static/sphinx_highlight.js?v=dc90522c"></script>
    <script src="../_static/profiling-sampling-visualization.js?v=9811ed04"></script>
    
    <script src="../_static/sidebar.js"></script>
    
    <link rel="search" type="application/opensearchdescription+xml"
          title="Search within Python 3.15.0a6 documentation"
          href="../_static/opensearch.xml"/>
    <link rel="author" title="About these documents" href="../about.html" />
    <link rel="index" title="Index" href="../genindex.html" />
    <link rel="search" title="Search" href="../search.html" />
    <link rel="copyright" title="Copyright" href="../copyright.html" />
    <link rel="next" title="Argparse Tutorial" href="../howto/argparse.html" />
    <link rel="prev" title="Command-line interface libraries" href="cmdlinelibs.html" />
    
      
      <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>
      
      <link rel="canonical" href="https://docs.python.org/3/library/argparse.html">
      
    

    
    <style>
      @media only screen {
        table.full-width-table {
            width: 100%;
        }
      }
    </style>
<link rel="stylesheet" href="../_static/pydoctheme_dark.css" media="(prefers-color-scheme: dark)" id="pydoctheme_dark_css">
    <link rel="shortcut icon" type="image/png" href="../_static/py.svg">
            <script type="text/javascript" src="../_static/copybutton.js"></script>
            <script type="text/javascript" src="../_static/menu.js"></script>
            <script type="text/javascript" src="../_static/search-focus.js"></script>
            <script type="text/javascript" src="../_static/themetoggle.js"></script> 
            <script type="text/javascript" src="../_static/rtd_switcher.js"></script>
            <meta name="readthedocs-addons-api-version" content="1">

  </head>
<body>
<div class="mobile-nav">
    <input type="checkbox" id="menuToggler" class="toggler__input" aria-controls="navigation"
           aria-pressed="false" aria-expanded="false" role="button" aria-label="Menu">
    <nav class="nav-content" role="navigation">
        <label for="menuToggler" class="toggler__label">
            <span></span>
        </label>
        <span class="nav-items-wrapper">
            <a href="https://www.python.org/" class="nav-logo">
                <img src="../_static/py.svg" alt="Python logo">
            </a>
            <span class="version_switcher_placeholder"></span>
            <form role="search" class="search" action="../search.html" method="get">
                <svg xmlns="http://www.w3.org/2000/svg" width="20" height="20" viewBox="0 0 24 24" class="search-icon">
                    <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>
                </svg>
                <input placeholder="Quick search" aria-label="Quick search" type="search" name="q">
                <input type="submit" value="Go">
            </form>
        </span>
    </nav>
    <div class="menu-wrapper">
        <nav class="menu" role="navigation" aria-label="main navigation">
            <div class="language_switcher_placeholder"></div>
            
<label class="theme-selector-label">
    Theme
    <select class="theme-selector" oninput="activateTheme(this.value)">
        <option value="auto" selected>Auto</option>
        <option value="light">Light</option>
        <option value="dark">Dark</option>
    </select>
</label>
  <div>
    <h3><a href="../contents.html">Table of Contents</a></h3>
    <ul>
<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>
<li><a class="reference internal" href="#argumentparser-objects">ArgumentParser objects</a><ul>
<li><a class="reference internal" href="#prog">prog</a></li>
<li><a class="reference internal" href="#usage">usage</a></li>
<li><a class="reference internal" href="#description">description</a></li>
<li><a class="reference internal" href="#epilog">epilog</a></li>
<li><a class="reference internal" href="#parents">parents</a></li>
<li><a class="reference internal" href="#formatter-class">formatter_class</a></li>
<li><a class="reference internal" href="#prefix-chars">prefix_chars</a></li>
<li><a class="reference internal" href="#fromfile-prefix-chars">fromfile_prefix_chars</a></li>
<li><a class="reference internal" href="#argument-default">argument_default</a></li>
<li><a class="reference internal" href="#allow-abbrev">allow_abbrev</a></li>
<li><a class="reference internal" href="#conflict-handler">conflict_handler</a></li>
<li><a class="reference internal" href="#add-help">add_help</a></li>
<li><a class="reference internal" href="#exit-on-error">exit_on_error</a></li>
<li><a class="reference internal" href="#suggest-on-error">suggest_on_error</a></li>
<li><a class="reference internal" href="#color">color</a></li>
</ul>
</li>
<li><a class="reference internal" href="#the-add-argument-method">The add_argument() method</a><ul>
<li><a class="reference internal" href="#name-or-flags">name or flags</a></li>
<li><a class="reference internal" href="#action">action</a></li>
<li><a class="reference internal" href="#nargs">nargs</a></li>
<li><a class="reference internal" href="#const">const</a></li>
<li><a class="reference internal" href="#default">default</a></li>
<li><a class="reference internal" href="#type">type</a></li>
<li><a class="reference internal" href="#choices">choices</a></li>
<li><a class="reference internal" href="#required">required</a></li>
<li><a class="reference internal" href="#help">help</a></li>
<li><a class="reference internal" href="#metavar">metavar</a></li>
<li><a class="reference internal" href="#dest">dest</a></li>
<li><a class="reference internal" href="#deprecated">deprecated</a></li>
<li><a class="reference internal" href="#action-classes">Action classes</a></li>
</ul>
</li>
<li><a class="reference internal" href="#the-parse-args-method">The parse_args() method</a><ul>
<li><a class="reference internal" href="#option-value-syntax">Option value syntax</a></li>
<li><a class="reference internal" href="#invalid-arguments">Invalid arguments</a></li>
<li><a class="reference internal" href="#arguments-containing">Arguments containing <code class="docutils literal notranslate"><span class="pre">-</span></code></a></li>
<li><a class="reference internal" href="#argument-abbreviations-prefix-matching">Argument abbreviations (prefix matching)</a></li>
<li><a class="reference internal" href="#beyond-sys-argv">Beyond <code class="docutils literal notranslate"><span class="pre">sys.argv</span></code></a></li>
<li><a class="reference internal" href="#the-namespace-object">The Namespace object</a></li>
</ul>
</li>
<li><a class="reference internal" href="#other-utilities">Other utilities</a><ul>
<li><a class="reference internal" href="#subcommands">Subcommands</a></li>
<li><a class="reference internal" href="#filetype-objects">FileType objects</a></li>
<li><a class="reference internal" href="#argument-groups">Argument groups</a></li>
<li><a class="reference internal" href="#mutual-exclusion">Mutual exclusion</a></li>
<li><a class="reference internal" href="#parser-defaults">Parser defaults</a></li>
<li><a class="reference internal" href="#printing-help">Printing help</a></li>
<li><a class="reference internal" href="#partial-parsing">Partial parsing</a></li>
<li><a class="reference internal" href="#customizing-file-parsing">Customizing file parsing</a></li>
<li><a class="reference internal" href="#exiting-methods">Exiting methods</a></li>
<li><a class="reference internal" href="#intermixed-parsing">Intermixed parsing</a></li>
<li><a class="reference internal" href="#registering-custom-types-or-actions">Registering custom types or actions</a></li>
</ul>
</li>
<li><a class="reference internal" href="#exceptions">Exceptions</a></li>
</ul>
</li>
</ul>

  </div>
  <div>
    <h4>Previous topic</h4>
    <p class="topless"><a href="cmdlinelibs.html"
                          title="previous chapter">Command-line interface libraries</a></p>
  </div>
  <div>
    <h4>Next topic</h4>
    <p class="topless"><a href="../howto/argparse.html"
                          title="next chapter">Argparse Tutorial</a></p>
  </div>
  <script>
    document.addEventListener('DOMContentLoaded', () => {
        const title = document.querySelector('meta[property="og:title"]').content;
        const elements = document.querySelectorAll('.improvepage');
        const pageurl = window.location.href.split('?')[0];
        elements.forEach(element => {
            const url = new URL(element.href.split('?')[0].replace("-nojs", ""));
            url.searchParams.set('pagetitle', title);
            url.searchParams.set('pageurl', pageurl);
            url.searchParams.set('pagesource', "library/argparse.rst");
            element.href = url.toString();
        });
    });
  </script>
  <div role="note" aria-label="source link">
    <h3>This page</h3>
    <ul class="this-page-menu">
      <li><a href="../bugs.html">Report a bug</a></li>
      <li><a class="improvepage" href="../improve-page-nojs.html">Improve this page</a></li>
      <li>
        <a href="https://github.com/python/cpython/blob/main/Doc/library/argparse.rst?plain=1"
            rel="nofollow">Show source
        </a>
      </li>
      
    </ul>
  </div>
        </nav>
    </div>
</div>

  
    <div class="related" role="navigation" aria-label="Related">
      <h3>Navigation</h3>
      <ul>
        <li class="right" style="margin-right: 10px">
          <a href="../genindex.html" title="General Index"
             accesskey="I">index</a></li>
        <li class="right" >
          <a href="../py-modindex.html" title="Python Module Index"
             >modules</a> |</li>
        <li class="right" >
          <a href="../howto/argparse.html" title="Argparse Tutorial"
             accesskey="N">next</a> |</li>
        <li class="right" >
          <a href="cmdlinelibs.html" title="Command-line interface libraries"
             accesskey="P">previous</a> |</li>

          <li><img src="../_static/py.svg" alt="Python logo" style="vertical-align: middle; margin-top: -1px"></li>
          <li><a href="https://www.python.org/">Python</a> &#187;</li>
          <li class="switchers">
            <div class="language_switcher_placeholder"></div>
            <div class="version_switcher_placeholder"></div>
          </li>
          <li>
              
          </li>
    <li id="cpython-language-and-version">
      <a href="../index.html">3.15.0a6 Documentation</a> &#187;
    </li>

          <li class="nav-item nav-item-1"><a href="index.html" >The Python Standard Library</a> &#187;</li>
          <li class="nav-item nav-item-2"><a href="cmdlinelibs.html" accesskey="U">Command-line interface libraries</a> &#187;</li>
        <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>
                <li class="right">
                    

    <div class="inline-search" role="search">
        <form class="inline-search" action="../search.html" method="get">
          <input placeholder="Quick search" aria-label="Quick search" type="search" name="q" id="search-box">
          <input type="submit" value="Go">
        </form>
    </div>
                     |
                </li>
            <li class="right">
<label class="theme-selector-label">
    Theme
    <select class="theme-selector" oninput="activateTheme(this.value)">
        <option value="auto" selected>Auto</option>
        <option value="light">Light</option>
        <option value="dark">Dark</option>
    </select>
</label> |</li>
            
      </ul>
    </div>    

    <div class="document">
      <div class="documentwrapper">
        <div class="bodywrapper">
          <div class="body" role="main">
            
  <section id="module-argparse">
<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>
<div class="versionadded">
<p><span class="versionmodified added">Added in version 3.2.</span></p>
</div>
<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>
<div class="admonition note">
<p class="admonition-title">Note</p>
<p>While <code class="xref py py-mod docutils literal notranslate"><span class="pre">argparse</span></code> is the default recommended standard library module
for implementing basic command line applications, authors with more
exacting requirements for exactly how their command line applications
behave may find it doesn’t provide the necessary level of control.
Refer 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 to
consider when <code class="docutils literal notranslate"><span class="pre">argparse</span></code> doesn’t support behaviors that the application
requires (such as entirely disabling support for interspersed options and
positional arguments, or accepting option parameter values that start
with <code class="docutils literal notranslate"><span class="pre">-</span></code> even when they correspond to another defined option).</p>
</div>
<hr class="docutils" />
<aside class="sidebar">
<p class="sidebar-title">Tutorial</p>
<p>This page contains the API reference information. For a more gentle
introduction to Python command-line parsing, have a look at the
<a class="reference internal" href="../howto/argparse.html#argparse-tutorial"><span class="std std-ref">argparse tutorial</span></a>.</p>
</aside>
<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-line
interfaces. The program defines what arguments it requires, and <code class="xref py py-mod docutils literal notranslate"><span class="pre">argparse</span></code>
will 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>
module also automatically generates help and usage messages.  The module
will also issue errors when users give the program invalid arguments.</p>
<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 built
around 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 for
argument specifications and has options that apply to the parser as whole:</p>
<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>
                    <span class="n">prog</span><span class="o">=</span><span class="s1">&#39;ProgramName&#39;</span><span class="p">,</span>
                    <span class="n">description</span><span class="o">=</span><span class="s1">&#39;What the program does&#39;</span><span class="p">,</span>
                    <span class="n">epilog</span><span class="o">=</span><span class="s1">&#39;Text at the bottom of help&#39;</span><span class="p">)</span>
</pre></div>
</div>
<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 argument
specifications to the parser.  It supports positional arguments, options that
accept values, and on/off flags:</p>
<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">&#39;filename&#39;</span><span class="p">)</span>           <span class="c1"># positional argument</span>
<span class="n">parser</span><span class="o">.</span><span class="n">add_argument</span><span class="p">(</span><span class="s1">&#39;-c&#39;</span><span class="p">,</span> <span class="s1">&#39;--count&#39;</span><span class="p">)</span>      <span class="c1"># option that takes a value</span>
<span class="n">parser</span><span class="o">.</span><span class="n">add_argument</span><span class="p">(</span><span class="s1">&#39;-v&#39;</span><span class="p">,</span> <span class="s1">&#39;--verbose&#39;</span><span class="p">,</span>
                    <span class="n">action</span><span class="o">=</span><span class="s1">&#39;store_true&#39;</span><span class="p">)</span>  <span class="c1"># on/off flag</span>
</pre></div>
</div>
<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 places
the 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>
<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>
<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>
</pre></div>
</div>
<div class="admonition note">
<p class="admonition-title">Note</p>
<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> code
to <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>
</div>
<section id="argumentparser-objects">
<h2>ArgumentParser objects<a class="headerlink" href="#argumentparser-objects" title="Link to this heading">¶</a></h2>
<dl class="py class">
<dt class="sig sig-object py" id="argparse.ArgumentParser">
<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>
<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 passed
as keyword arguments. Each parameter has its own more detailed description
below, but in short they are:</p>
<ul class="simple">
<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>
module attributes and <code class="docutils literal notranslate"><span class="pre">sys.argv[0]</span></code>)</p></li>
<li><p><a class="reference internal" href="#usage">usage</a> - The string describing the program usage (default: generated from
arguments added to parser)</p></li>
<li><p><a class="reference internal" href="#description">description</a> - Text to display before the argument help
(by default, no text)</p></li>
<li><p><a class="reference internal" href="#epilog">epilog</a> - Text to display after the argument help (by default, no text)</p></li>
<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 should
also be included</p></li>
<li><p><a class="reference internal" href="#formatter-class">formatter_class</a> - A class for customizing the help output</p></li>
<li><p><a class="reference internal" href="#prefix-chars">prefix_chars</a> - The set of characters that prefix optional arguments
(default: ‘-‘)</p></li>
<li><p><a class="reference internal" href="#fromfile-prefix-chars">fromfile_prefix_chars</a> - The set of characters that prefix files from
which additional arguments should be read (default: <code class="docutils literal notranslate"><span class="pre">None</span></code>)</p></li>
<li><p><a class="reference internal" href="#argument-default">argument_default</a> - The global default value for arguments
(default: <code class="docutils literal notranslate"><span class="pre">None</span></code>)</p></li>
<li><p><a class="reference internal" href="#conflict-handler">conflict_handler</a> - The strategy for resolving conflicting optionals
(usually unnecessary)</p></li>
<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>
<li><p><a class="reference internal" href="#allow-abbrev">allow_abbrev</a> - Allows long options to be abbreviated if the
abbreviation is unambiguous (default: <code class="docutils literal notranslate"><span class="pre">True</span></code>)</p></li>
<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 with
error info when an error occurs. (default: <code class="docutils literal notranslate"><span class="pre">True</span></code>)</p></li>
<li><p><a class="reference internal" href="#suggest-on-error">suggest_on_error</a> - Enables suggestions for mistyped argument choices
and subparser names (default: <code class="docutils literal notranslate"><span class="pre">True</span></code>)</p></li>
<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>
</ul>
<div class="versionchanged">
<p><span class="versionmodified changed">Changed in version 3.5: </span><em>allow_abbrev</em> parameter was added.</p>
</div>
<div class="versionchanged">
<p><span class="versionmodified changed">Changed in version 3.8: </span>In previous versions, <em>allow_abbrev</em> also disabled grouping of short
flags 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>
</div>
<div class="versionchanged">
<p><span class="versionmodified changed">Changed in version 3.9: </span><em>exit_on_error</em> parameter was added.</p>
</div>
<div class="versionchanged">
<p><span class="versionmodified changed">Changed in version 3.14: </span><em>suggest_on_error</em> and <em>color</em> parameters were added.</p>
</div>
<div class="versionchanged">
<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>
</div>
</dd></dl>

<p>The following sections describe how each of these are used.</p>
<section id="prog">
<span id="id1"></span><h3>prog<a class="headerlink" href="#prog" title="Link to this heading">¶</a></h3>
<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 program
to display in help messages depending on the way the Python interpreter was run:</p>
<ul class="simple">
<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 was
passed as argument.</p></li>
<li><p>The Python interpreter name followed by <code class="docutils literal notranslate"><span class="pre">sys.argv[0]</span></code> if a directory or
a zipfile was passed as argument.</p></li>
<li><p>The Python interpreter name followed by <code class="docutils literal notranslate"><span class="pre">-m</span></code> followed by the
module 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>
</ul>
<p>This default is almost always desirable because it will make the help messages
match the string that was used to invoke the program on the command line.
However, to change this default behavior, another value can be supplied using
the <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>
<div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="gp">&gt;&gt;&gt; </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">&#39;myprogram&#39;</span><span class="p">)</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">parser</span><span class="o">.</span><span class="n">print_help</span><span class="p">()</span>
<span class="go">usage: myprogram [-h]</span>

<span class="go">options:</span>
<span class="go"> -h, --help  show this help message and exit</span>
</pre></div>
</div>
<p>Note that the program name, whether determined from <code class="docutils literal notranslate"><span class="pre">sys.argv[0]</span></code>,
from the <code class="docutils literal notranslate"><span class="pre">__main__</span></code> module attributes or from the
<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> format
specifier.</p>
<div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="gp">&gt;&gt;&gt; </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">&#39;myprogram&#39;</span><span class="p">)</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">parser</span><span class="o">.</span><span class="n">add_argument</span><span class="p">(</span><span class="s1">&#39;--foo&#39;</span><span class="p">,</span> <span class="n">help</span><span class="o">=</span><span class="s1">&#39;foo of the </span><span class="si">%(prog)s</span><span class="s1"> program&#39;</span><span class="p">)</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">parser</span><span class="o">.</span><span class="n">print_help</span><span class="p">()</span>
<span class="go">usage: myprogram [-h] [--foo FOO]</span>

<span class="go">options:</span>
<span class="go"> -h, --help  show this help message and exit</span>
<span class="go"> --foo FOO   foo of the myprogram program</span>
</pre></div>
</div>
<div class="versionchanged">
<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,
rather than always being <code class="docutils literal notranslate"><span class="pre">os.path.basename(sys.argv[0])</span></code>.</p>
</div>
</section>
<section id="usage">
<h3>usage<a class="headerlink" href="#usage" title="Link to this heading">¶</a></h3>
<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 the
arguments it contains. The default message can be overridden with the
<code class="docutils literal notranslate"><span class="pre">usage=</span></code> keyword argument:</p>
<div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="gp">&gt;&gt;&gt; </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">&#39;PROG&#39;</span><span class="p">,</span> <span class="n">usage</span><span class="o">=</span><span class="s1">&#39;</span><span class="si">%(prog)s</span><span class="s1"> [options]&#39;</span><span class="p">)</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">parser</span><span class="o">.</span><span class="n">add_argument</span><span class="p">(</span><span class="s1">&#39;--foo&#39;</span><span class="p">,</span> <span class="n">nargs</span><span class="o">=</span><span class="s1">&#39;?&#39;</span><span class="p">,</span> <span class="n">help</span><span class="o">=</span><span class="s1">&#39;foo help&#39;</span><span class="p">)</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">parser</span><span class="o">.</span><span class="n">add_argument</span><span class="p">(</span><span class="s1">&#39;bar&#39;</span><span class="p">,</span> <span class="n">nargs</span><span class="o">=</span><span class="s1">&#39;+&#39;</span><span class="p">,</span> <span class="n">help</span><span class="o">=</span><span class="s1">&#39;bar help&#39;</span><span class="p">)</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">parser</span><span class="o">.</span><span class="n">print_help</span><span class="p">()</span>
<span class="go">usage: PROG [options]</span>

<span class="go">positional arguments:</span>
<span class="go"> bar          bar help</span>

<span class="go">options:</span>
<span class="go"> -h, --help   show this help message and exit</span>
<span class="go"> --foo [FOO]  foo help</span>
</pre></div>
</div>
<p>The <code class="docutils literal notranslate"><span class="pre">%(prog)s</span></code> format specifier is available to fill in the program name in
your usage messages.</p>
<p>When a custom usage message is specified for the main parser, you may also want to
consider 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>
or 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 to
<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 and
usage information across subparsers.</p>
</section>
<section id="description">
<span id="id2"></span><h3>description<a class="headerlink" href="#description" title="Link to this heading">¶</a></h3>
<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 the
<code class="docutils literal notranslate"><span class="pre">description=</span></code> keyword argument.  This argument gives a brief description of
what the program does and how it works.  In help messages, the description is
displayed between the command-line usage string and the help messages for the
various arguments.</p>
<p>By default, the description will be line-wrapped so that it fits within the
given space.  To change this behavior, see the <a class="reference internal" href="#formatter-class">formatter_class</a> argument.</p>
</section>
<section id="epilog">
<h3>epilog<a class="headerlink" href="#epilog" title="Link to this heading">¶</a></h3>
<p>Some programs like to display additional description of the program after the
description of the arguments.  Such text can be specified using the <code class="docutils literal notranslate"><span class="pre">epilog=</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>
<div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="gp">&gt;&gt;&gt; </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="gp">... </span>    <span class="n">description</span><span class="o">=</span><span class="s1">&#39;A foo that bars&#39;</span><span class="p">,</span>
<span class="gp">... </span>    <span class="n">epilog</span><span class="o">=</span><span class="s2">&quot;And that&#39;s how you&#39;d foo a bar&quot;</span><span class="p">)</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">parser</span><span class="o">.</span><span class="n">print_help</span><span class="p">()</span>
<span class="go">usage: argparse.py [-h]</span>

<span class="go">A foo that bars</span>

<span class="go">options:</span>
<span class="go"> -h, --help  show this help message and exit</span>

<span class="go">And that&#39;s how you&#39;d foo a bar</span>
</pre></div>
</div>
<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 default
line-wrapped, but this behavior can be adjusted with the <a class="reference internal" href="#formatter-class">formatter_class</a>
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>
</section>
<section id="parents">
<h3>parents<a class="headerlink" href="#parents" title="Link to this heading">¶</a></h3>
<p>Sometimes, several parsers share a common set of arguments. Rather than
repeating the definitions of these arguments, a single parser with all the
shared 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>
can 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>
objects, collects all the positional and optional actions from them, and adds
these actions to the <code class="xref py py-class docutils literal notranslate"><span class="pre">ArgumentParser</span></code> object being constructed:</p>
<div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="gp">&gt;&gt;&gt; </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>
<span class="gp">&gt;&gt;&gt; </span><span class="n">parent_parser</span><span class="o">.</span><span class="n">add_argument</span><span class="p">(</span><span class="s1">&#39;--parent&#39;</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="gp">&gt;&gt;&gt; </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>
<span class="gp">&gt;&gt;&gt; </span><span class="n">foo_parser</span><span class="o">.</span><span class="n">add_argument</span><span class="p">(</span><span class="s1">&#39;foo&#39;</span><span class="p">)</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">foo_parser</span><span class="o">.</span><span class="n">parse_args</span><span class="p">([</span><span class="s1">&#39;--parent&#39;</span><span class="p">,</span> <span class="s1">&#39;2&#39;</span><span class="p">,</span> <span class="s1">&#39;XXX&#39;</span><span class="p">])</span>
<span class="go">Namespace(foo=&#39;XXX&#39;, parent=2)</span>

<span class="gp">&gt;&gt;&gt; </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>
<span class="gp">&gt;&gt;&gt; </span><span class="n">bar_parser</span><span class="o">.</span><span class="n">add_argument</span><span class="p">(</span><span class="s1">&#39;--bar&#39;</span><span class="p">)</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">bar_parser</span><span class="o">.</span><span class="n">parse_args</span><span class="p">([</span><span class="s1">&#39;--bar&#39;</span><span class="p">,</span> <span class="s1">&#39;YYY&#39;</span><span class="p">])</span>
<span class="go">Namespace(bar=&#39;YYY&#39;, parent=None)</span>
</pre></div>
</div>
<p>Note that most parent parsers will specify <code class="docutils literal notranslate"><span class="pre">add_help=False</span></code>.  Otherwise, 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> will see two <code class="docutils literal notranslate"><span class="pre">-h/--help</span></code> options (one in the parent
and one in the child) and raise an error.</p>
<div class="admonition note">
<p class="admonition-title">Note</p>
<p>You must fully initialize the parsers before passing them via <code class="docutils literal notranslate"><span class="pre">parents=</span></code>.
If you change the parent parsers after the child parser, those changes will
not be reflected in the child.</p>
</div>
</section>
<section id="formatter-class">
<span id="id3"></span><h3>formatter_class<a class="headerlink" href="#formatter-class" title="Link to this heading">¶</a></h3>
<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 by
specifying an alternate formatting class.  Currently, there are four such
classes:</p>
<dl class="py class">
<dt class="sig sig-object py" id="argparse.RawDescriptionHelpFormatter">
<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>
<dt class="sig sig-object py" id="argparse.RawTextHelpFormatter">
<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>
<dt class="sig sig-object py" id="argparse.ArgumentDefaultsHelpFormatter">
<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>
<dt class="sig sig-object py" id="argparse.MetavarTypeHelpFormatter">
<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>
<dd></dd></dl>

<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> give
more control over how textual descriptions are displayed.
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 line-wrap the <a class="reference internal" href="#description">description</a> and
<a class="reference internal" href="#epilog">epilog</a> texts in command-line help messages:</p>
<div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="gp">&gt;&gt;&gt; </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="gp">... </span>    <span class="n">prog</span><span class="o">=</span><span class="s1">&#39;PROG&#39;</span><span class="p">,</span>
<span class="gp">... </span>    <span class="n">description</span><span class="o">=</span><span class="s1">&#39;&#39;&#39;this description</span>
<span class="gp">... </span><span class="s1">        was indented weird</span>
<span class="gp">... </span><span class="s1">            but that is okay&#39;&#39;&#39;</span><span class="p">,</span>
<span class="gp">... </span>    <span class="n">epilog</span><span class="o">=</span><span class="s1">&#39;&#39;&#39;</span>
<span class="gp">... </span><span class="s1">            likewise for this epilog whose whitespace will</span>
<span class="gp">... </span><span class="s1">        be cleaned up and whose words will be wrapped</span>
<span class="gp">... </span><span class="s1">        across a couple lines&#39;&#39;&#39;</span><span class="p">)</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">parser</span><span class="o">.</span><span class="n">print_help</span><span class="p">()</span>
<span class="go">usage: PROG [-h]</span>

<span class="go">this description was indented weird but that is okay</span>

<span class="go">options:</span>
<span class="go"> -h, --help  show this help message and exit</span>

<span class="go">likewise for this epilog whose whitespace will be cleaned up and whose words</span>
<span class="go">will be wrapped across a couple lines</span>
</pre></div>
</div>
<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>
indicates that <a class="reference internal" href="#description">description</a> and <a class="reference internal" href="#epilog">epilog</a> are already correctly formatted and
should not be line-wrapped:</p>
<div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="gp">&gt;&gt;&gt; </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="gp">... </span>    <span class="n">prog</span><span class="o">=</span><span class="s1">&#39;PROG&#39;</span><span class="p">,</span>
<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>
<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">&#39;&#39;&#39;</span><span class="se">\</span>
<span class="gp">... </span><span class="s1">        Please do not mess up this text!</span>
<span class="gp">... </span><span class="s1">        --------------------------------</span>
<span class="gp">... </span><span class="s1">            I have indented it</span>
<span class="gp">... </span><span class="s1">            exactly the way</span>
<span class="gp">... </span><span class="s1">            I want it</span>
<span class="gp">... </span><span class="s1">        &#39;&#39;&#39;</span><span class="p">))</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">parser</span><span class="o">.</span><span class="n">print_help</span><span class="p">()</span>
<span class="go">usage: PROG [-h]</span>

<span class="go">Please do not mess up this text!</span>
<span class="go">--------------------------------</span>
<span class="go">   I have indented it</span>
<span class="go">   exactly the way</span>
<span class="go">   I want it</span>

<span class="go">options:</span>
<span class="go"> -h, --help  show this help message and exit</span>
</pre></div>
</div>
<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,
including argument descriptions. However, multiple newlines are replaced with
one. If you wish to preserve multiple blank lines, add spaces between the
newlines.</p>
<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 about
default values to each of the argument help messages:</p>
<div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="gp">&gt;&gt;&gt; </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="gp">... </span>    <span class="n">prog</span><span class="o">=</span><span class="s1">&#39;PROG&#39;</span><span class="p">,</span>
<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>
<span class="gp">&gt;&gt;&gt; </span><span class="n">parser</span><span class="o">.</span><span class="n">add_argument</span><span class="p">(</span><span class="s1">&#39;--foo&#39;</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">&#39;FOO!&#39;</span><span class="p">)</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">parser</span><span class="o">.</span><span class="n">add_argument</span><span class="p">(</span><span class="s1">&#39;bar&#39;</span><span class="p">,</span> <span class="n">nargs</span><span class="o">=</span><span class="s1">&#39;*&#39;</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">&#39;BAR!&#39;</span><span class="p">)</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">parser</span><span class="o">.</span><span class="n">print_help</span><span class="p">()</span>
<span class="go">usage: PROG [-h] [--foo FOO] [bar ...]</span>

<span class="go">positional arguments:</span>
<span class="go"> bar         BAR! (default: [1, 2, 3])</span>

<span class="go">options:</span>
<span class="go"> -h, --help  show this help message and exit</span>
<span class="go"> --foo FOO   FOO! (default: 42)</span>
</pre></div>
</div>
<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 each
argument as the display name for its values (rather than using the <a class="reference internal" href="#dest">dest</a>
as the regular formatter does):</p>
<div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="gp">&gt;&gt;&gt; </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="gp">... </span>    <span class="n">prog</span><span class="o">=</span><span class="s1">&#39;PROG&#39;</span><span class="p">,</span>
<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>
<span class="gp">&gt;&gt;&gt; </span><span class="n">parser</span><span class="o">.</span><span class="n">add_argument</span><span class="p">(</span><span class="s1">&#39;--foo&#39;</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="gp">&gt;&gt;&gt; </span><span class="n">parser</span><span class="o">.</span><span class="n">add_argument</span><span class="p">(</span><span class="s1">&#39;bar&#39;</span><span class="p">,</span> <span class="nb">type</span><span class="o">=</span><span class="nb">float</span><span class="p">)</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">parser</span><span class="o">.</span><span class="n">print_help</span><span class="p">()</span>
<span class="go">usage: PROG [-h] [--foo int] float</span>

<span class="go">positional arguments:</span>
<span class="go">  float</span>

<span class="go">options:</span>
<span class="go">  -h, --help  show this help message and exit</span>
<span class="go">  --foo int</span>
</pre></div>
</div>
</section>
<section id="prefix-chars">
<h3>prefix_chars<a class="headerlink" href="#prefix-chars" title="Link to this heading">¶</a></h3>
<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>.
Parsers that need to support different or additional prefix
characters, e.g. for options
like <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> argument
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:</p>
<div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="gp">&gt;&gt;&gt; </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">&#39;PROG&#39;</span><span class="p">,</span> <span class="n">prefix_chars</span><span class="o">=</span><span class="s1">&#39;-+&#39;</span><span class="p">)</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">parser</span><span class="o">.</span><span class="n">add_argument</span><span class="p">(</span><span class="s1">&#39;+f&#39;</span><span class="p">)</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">parser</span><span class="o">.</span><span class="n">add_argument</span><span class="p">(</span><span class="s1">&#39;++bar&#39;</span><span class="p">)</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">parser</span><span class="o">.</span><span class="n">parse_args</span><span class="p">(</span><span class="s1">&#39;+f X ++bar Y&#39;</span><span class="o">.</span><span class="n">split</span><span class="p">())</span>
<span class="go">Namespace(bar=&#39;Y&#39;, f=&#39;X&#39;)</span>
</pre></div>
</div>
<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 of
characters 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 be
disallowed.</p>
</section>
<section id="fromfile-prefix-chars">
<h3>fromfile_prefix_chars<a class="headerlink" href="#fromfile-prefix-chars" title="Link to this heading">¶</a></h3>
<p>Sometimes, when dealing with a particularly long argument list, it
may make sense to keep the list of arguments in a file rather than typing it out
at the command line.  If the <code class="docutils literal notranslate"><span class="pre">fromfile_prefix_chars=</span></code> argument is given 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, then arguments that start with any of the
specified characters will be treated as files, and will be replaced by the
arguments they contain.  For example:</p>
<div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="gp">&gt;&gt;&gt; </span><span class="k">with</span> <span class="nb">open</span><span class="p">(</span><span class="s1">&#39;args.txt&#39;</span><span class="p">,</span> <span class="s1">&#39;w&#39;</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>
<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">&#39;-f</span><span class="se">\n</span><span class="s1">bar&#39;</span><span class="p">)</span>
<span class="gp">...</span>
<span class="gp">&gt;&gt;&gt; </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">&#39;@&#39;</span><span class="p">)</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">parser</span><span class="o">.</span><span class="n">add_argument</span><span class="p">(</span><span class="s1">&#39;-f&#39;</span><span class="p">)</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">parser</span><span class="o">.</span><span class="n">parse_args</span><span class="p">([</span><span class="s1">&#39;-f&#39;</span><span class="p">,</span> <span class="s1">&#39;foo&#39;</span><span class="p">,</span> <span class="s1">&#39;@args.txt&#39;</span><span class="p">])</span>
<span class="go">Namespace(f=&#39;bar&#39;)</span>
</pre></div>
</div>
<p>Arguments read from a file must be one per line by default (but see also
<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 they
were in the same place as the original file referencing argument on the command
line.  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">'&#64;args.txt']</span></code>
is 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>
<div class="admonition note">
<p class="admonition-title">Note</p>
<p>Empty lines are treated as empty strings (<code class="docutils literal notranslate"><span class="pre">''</span></code>), which are allowed as values but
not as arguments. Empty lines that are read as arguments will result in an
“unrecognized arguments” error.</p>
</div>
<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>
to read the file containing arguments.</p>
<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 that
arguments will never be treated as file references.</p>
<div class="versionchanged">
<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 files
from 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>
and <code class="docutils literal notranslate"><span class="pre">&quot;strict&quot;</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>.
Arguments file should be encoded in UTF-8 instead of ANSI Codepage on Windows.</p>
</div>
</section>
<section id="argument-default">
<h3>argument_default<a class="headerlink" href="#argument-default" title="Link to this heading">¶</a></h3>
<p>Generally, argument defaults are specified either by passing a default to
<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 the
<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-value
pairs.  Sometimes however, it may be useful to specify a single parser-wide
default for arguments.  This can be accomplished by passing the
<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,
to 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>
calls, we supply <code class="docutils literal notranslate"><span class="pre">argument_default=SUPPRESS</span></code>:</p>
<div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="gp">&gt;&gt;&gt; </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>
<span class="gp">&gt;&gt;&gt; </span><span class="n">parser</span><span class="o">.</span><span class="n">add_argument</span><span class="p">(</span><span class="s1">&#39;--foo&#39;</span><span class="p">)</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">parser</span><span class="o">.</span><span class="n">add_argument</span><span class="p">(</span><span class="s1">&#39;bar&#39;</span><span class="p">,</span> <span class="n">nargs</span><span class="o">=</span><span class="s1">&#39;?&#39;</span><span class="p">)</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">parser</span><span class="o">.</span><span class="n">parse_args</span><span class="p">([</span><span class="s1">&#39;--foo&#39;</span><span class="p">,</span> <span class="s1">&#39;1&#39;</span><span class="p">,</span> <span class="s1">&#39;BAR&#39;</span><span class="p">])</span>
<span class="go">Namespace(bar=&#39;BAR&#39;, foo=&#39;1&#39;)</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">parser</span><span class="o">.</span><span class="n">parse_args</span><span class="p">([])</span>
<span class="go">Namespace()</span>
</pre></div>
</div>
</section>
<section id="allow-abbrev">
<span id="id4"></span><h3>allow_abbrev<a class="headerlink" href="#allow-abbrev" title="Link to this heading">¶</a></h3>
<p>Normally, when you pass an 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> 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>,
it <a class="reference internal" href="#prefix-matching"><span class="std std-ref">recognizes abbreviations</span></a> of long options.</p>
<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>
<div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="gp">&gt;&gt;&gt; </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">&#39;PROG&#39;</span><span class="p">,</span> <span class="n">allow_abbrev</span><span class="o">=</span><span class="kc">False</span><span class="p">)</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">parser</span><span class="o">.</span><span class="n">add_argument</span><span class="p">(</span><span class="s1">&#39;--foobar&#39;</span><span class="p">,</span> <span class="n">action</span><span class="o">=</span><span class="s1">&#39;store_true&#39;</span><span class="p">)</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">parser</span><span class="o">.</span><span class="n">add_argument</span><span class="p">(</span><span class="s1">&#39;--foonley&#39;</span><span class="p">,</span> <span class="n">action</span><span class="o">=</span><span class="s1">&#39;store_false&#39;</span><span class="p">)</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">parser</span><span class="o">.</span><span class="n">parse_args</span><span class="p">([</span><span class="s1">&#39;--foon&#39;</span><span class="p">])</span>
<span class="go">usage: PROG [-h] [--foobar] [--foonley]</span>
<span class="go">PROG: error: unrecognized arguments: --foon</span>
</pre></div>
</div>
<div class="versionadded">
<p><span class="versionmodified added">Added in version 3.5.</span></p>
</div>
</section>
<section id="conflict-handler">
<h3>conflict_handler<a class="headerlink" href="#conflict-handler" title="Link to this heading">¶</a></h3>
<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 option
string.  By default, <code class="xref py py-class docutils literal notranslate"><span class="pre">ArgumentParser</span></code> objects raise an exception if an
attempt is made to create an argument with an option string that is already in
use:</p>
<div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="gp">&gt;&gt;&gt; </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">&#39;PROG&#39;</span><span class="p">)</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">parser</span><span class="o">.</span><span class="n">add_argument</span><span class="p">(</span><span class="s1">&#39;-f&#39;</span><span class="p">,</span> <span class="s1">&#39;--foo&#39;</span><span class="p">,</span> <span class="n">help</span><span class="o">=</span><span class="s1">&#39;old foo help&#39;</span><span class="p">)</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">parser</span><span class="o">.</span><span class="n">add_argument</span><span class="p">(</span><span class="s1">&#39;--foo&#39;</span><span class="p">,</span> <span class="n">help</span><span class="o">=</span><span class="s1">&#39;new foo help&#39;</span><span class="p">)</span>
<span class="gt">Traceback (most recent call last):</span>
<span class="gr"> ..</span>
<span class="gr">ArgumentError</span>: <span class="n">argument --foo: conflicting option string(s): --foo</span>
</pre></div>
</div>
<p>Sometimes (e.g. when using <a class="reference internal" href="#parents">parents</a>) it may be useful to simply override any
older arguments with the same option string.  To get this behavior, the value
<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 of
<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>
<div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="gp">&gt;&gt;&gt; </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">&#39;PROG&#39;</span><span class="p">,</span> <span class="n">conflict_handler</span><span class="o">=</span><span class="s1">&#39;resolve&#39;</span><span class="p">)</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">parser</span><span class="o">.</span><span class="n">add_argument</span><span class="p">(</span><span class="s1">&#39;-f&#39;</span><span class="p">,</span> <span class="s1">&#39;--foo&#39;</span><span class="p">,</span> <span class="n">help</span><span class="o">=</span><span class="s1">&#39;old foo help&#39;</span><span class="p">)</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">parser</span><span class="o">.</span><span class="n">add_argument</span><span class="p">(</span><span class="s1">&#39;--foo&#39;</span><span class="p">,</span> <span class="n">help</span><span class="o">=</span><span class="s1">&#39;new foo help&#39;</span><span class="p">)</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">parser</span><span class="o">.</span><span class="n">print_help</span><span class="p">()</span>
<span class="go">usage: PROG [-h] [-f FOO] [--foo FOO]</span>

<span class="go">options:</span>
<span class="go"> -h, --help  show this help message and exit</span>
<span class="go"> -f FOO      old foo help</span>
<span class="go"> --foo FOO   new foo help</span>
</pre></div>
</div>
<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 its
option strings are overridden.  So, in the example above, the old <code class="docutils literal notranslate"><span class="pre">-f/--foo</span></code>
action 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> option
string was overridden.</p>
</section>
<section id="add-help">
<h3>add_help<a class="headerlink" href="#add-help" title="Link to this heading">¶</a></h3>
<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 displays
the 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 command
line, the <code class="xref py py-class docutils literal notranslate"><span class="pre">ArgumentParser</span></code> help will be printed.</p>
<p>Occasionally, it may be useful to disable the addition of this help option.
This 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 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>
<div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="gp">&gt;&gt;&gt; </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">&#39;PROG&#39;</span><span class="p">,</span> <span class="n">add_help</span><span class="o">=</span><span class="kc">False</span><span class="p">)</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">parser</span><span class="o">.</span><span class="n">add_argument</span><span class="p">(</span><span class="s1">&#39;--foo&#39;</span><span class="p">,</span> <span class="n">help</span><span class="o">=</span><span class="s1">&#39;foo help&#39;</span><span class="p">)</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">parser</span><span class="o">.</span><span class="n">print_help</span><span class="p">()</span>
<span class="go">usage: PROG [--foo FOO]</span>

<span class="go">options:</span>
<span class="go"> --foo FOO  foo help</span>
</pre></div>
</div>
<p>The help option is typically <code class="docutils literal notranslate"><span class="pre">-h/--help</span></code>. The exception to this is
if 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>, in
which 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.  In
this case, the first character in <code class="docutils literal notranslate"><span class="pre">prefix_chars</span></code> is used to prefix
the help options:</p>
<div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="gp">&gt;&gt;&gt; </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">&#39;PROG&#39;</span><span class="p">,</span> <span class="n">prefix_chars</span><span class="o">=</span><span class="s1">&#39;+/&#39;</span><span class="p">)</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">parser</span><span class="o">.</span><span class="n">print_help</span><span class="p">()</span>
<span class="go">usage: PROG [+h]</span>

<span class="go">options:</span>
<span class="go">  +h, ++help  show this help message and exit</span>
</pre></div>
</div>
</section>
<section id="exit-on-error">
<h3>exit_on_error<a class="headerlink" href="#exit-on-error" title="Link to this heading">¶</a></h3>
<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>
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>, 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 status
code of 2.</p>
<p>If the user would like to catch errors manually, the feature can be enabled by setting
<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>
<div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="gp">&gt;&gt;&gt; </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>
<span class="gp">&gt;&gt;&gt; </span><span class="n">parser</span><span class="o">.</span><span class="n">add_argument</span><span class="p">(</span><span class="s1">&#39;--integers&#39;</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="go">_StoreAction(option_strings=[&#39;--integers&#39;], dest=&#39;integers&#39;, nargs=None, const=None, default=None, type=&lt;class &#39;int&#39;&gt;, choices=None, help=None, metavar=None)</span>
<span class="gp">&gt;&gt;&gt; </span><span class="k">try</span><span class="p">:</span>
<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">&#39;--integers a&#39;</span><span class="o">.</span><span class="n">split</span><span class="p">())</span>
<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>
<span class="gp">... </span>    <span class="nb">print</span><span class="p">(</span><span class="s1">&#39;Catching an argumentError&#39;</span><span class="p">)</span>
<span class="gp">...</span>
<span class="go">Catching an argumentError</span>
</pre></div>
</div>
<div class="versionadded">
<p><span class="versionmodified added">Added in version 3.9.</span></p>
</div>
</section>
<section id="suggest-on-error">
<h3>suggest_on_error<a class="headerlink" href="#suggest-on-error" title="Link to this heading">¶</a></h3>
<p>By default, when a user passes an invalid argument choice or subparser name,
<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 for
mistyped arguments. The error message will list the permissible argument
choices (if specified) or subparser names, along with a “maybe you meant”
suggestion if a close match is found. Note that this only applies for arguments
when the choices specified are strings:</p>
<div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="gp">&gt;&gt;&gt; </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>
<span class="gp">&gt;&gt;&gt; </span><span class="n">parser</span><span class="o">.</span><span class="n">add_argument</span><span class="p">(</span><span class="s1">&#39;--action&#39;</span><span class="p">,</span> <span class="n">choices</span><span class="o">=</span><span class="p">[</span><span class="s1">&#39;debug&#39;</span><span class="p">,</span> <span class="s1">&#39;dryrun&#39;</span><span class="p">])</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">parser</span><span class="o">.</span><span class="n">parse_args</span><span class="p">([</span><span class="s1">&#39;--action&#39;</span><span class="p">,</span> <span class="s1">&#39;debugg&#39;</span><span class="p">])</span>
<span class="go">usage: tester.py [-h] [--action {debug,dryrun}]</span>
<span class="go">tester.py: error: argument --action: invalid choice: &#39;debugg&#39;, maybe you meant &#39;debug&#39;? (choose from debug, dryrun)</span>
</pre></div>
</div>
<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>
<div class="versionadded">
<p><span class="versionmodified added">Added in version 3.14.</span></p>
</div>
<div class="versionchanged">
<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>
</div>
</section>
<section id="color">
<h3>color<a class="headerlink" href="#color" title="Link to this heading">¶</a></h3>
<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>.
If 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 local
environment</span></a>, or in the argument parser itself
by 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>
<div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="gp">&gt;&gt;&gt; </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">&#39;Process some integers.&#39;</span><span class="p">,</span>
<span class="gp">... </span>                                 <span class="n">color</span><span class="o">=</span><span class="kc">False</span><span class="p">)</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">parser</span><span class="o">.</span><span class="n">add_argument</span><span class="p">(</span><span class="s1">&#39;--action&#39;</span><span class="p">,</span> <span class="n">choices</span><span class="o">=</span><span class="p">[</span><span class="s1">&#39;sum&#39;</span><span class="p">,</span> <span class="s1">&#39;max&#39;</span><span class="p">])</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">parser</span><span class="o">.</span><span class="n">add_argument</span><span class="p">(</span><span class="s1">&#39;integers&#39;</span><span class="p">,</span> <span class="n">metavar</span><span class="o">=</span><span class="s1">&#39;N&#39;</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">&#39;+&#39;</span><span class="p">,</span>
<span class="gp">... </span>                    <span class="n">help</span><span class="o">=</span><span class="s1">&#39;an integer for the accumulator&#39;</span><span class="p">)</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">parser</span><span class="o">.</span><span class="n">parse_args</span><span class="p">([</span><span class="s1">&#39;--help&#39;</span><span class="p">])</span>
</pre></div>
</div>
<p>Note that when <code class="docutils literal notranslate"><span class="pre">color=True</span></code>, colored output depends on both environment
variables and terminal capabilities.  However, if <code class="docutils literal notranslate"><span class="pre">color=False</span></code>, colored
output is always disabled, even if environment variables like <code class="docutils literal notranslate"><span class="pre">FORCE_COLOR</span></code>
are set.</p>
<div class="versionadded">
<p><span class="versionmodified added">Added in version 3.14.</span></p>
</div>
<p>To highlight inline code in your description or epilog text, you can use
backticks:</p>
<div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="gp">&gt;&gt;&gt; </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="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>
<span class="gp">... </span>    <span class="n">epilog</span><span class="o">=</span><span class="s1">&#39;&#39;&#39;Examples:</span>
<span class="gp">... </span><span class="s1">  `python -m myapp --verbose`</span>
<span class="gp">... </span><span class="s1">  `python -m myapp --config settings.json`</span>
<span class="gp">... </span><span class="s1">&#39;&#39;&#39;</span><span class="p">)</span>
</pre></div>
</div>
<p>When colors are enabled, the text inside backticks will be displayed in a
distinct color to help examples stand out. When colors are disabled, backticks
are preserved as-is, which is readable in plain text.</p>
<div class="admonition note">
<p class="admonition-title">Note</p>
<p>Backtick markup only applies to description and epilog text. It does not
apply to individual argument <code class="docutils literal notranslate"><span class="pre">help</span></code> strings.</p>
</div>
<div class="versionadded">
<p><span class="versionmodified added">Added in version 3.15.</span></p>
</div>
</section>
</section>
<section id="the-add-argument-method">
<h2>The add_argument() method<a class="headerlink" href="#the-add-argument-method" title="Link to this heading">¶</a></h2>
<dl class="py method">
<dt class="sig sig-object py" id="argparse.ArgumentParser.add_argument">
<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>
<dd><p>Define how a single command-line argument should be parsed.  Each parameter
has its own more detailed description below, but in short they are:</p>
<ul class="simple">
<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>
or <code class="docutils literal notranslate"><span class="pre">'-f',</span> <span class="pre">'--foo'</span></code>.</p></li>
<li><p><a class="reference internal" href="#action">action</a> - The basic type of action to be taken when this argument is
encountered at the command line.</p></li>
<li><p><a class="reference internal" href="#nargs">nargs</a> - The number of command-line arguments that should be consumed.</p></li>
<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>
<li><p><a class="reference internal" href="#default">default</a> - The value produced if the argument is absent from the
command line and if it is absent from the namespace object.</p></li>
<li><p><a class="reference internal" href="#type">type</a> - The type to which the command-line argument should be converted.</p></li>
<li><p><a class="reference internal" href="#choices">choices</a> - A sequence of the allowable values for the argument.</p></li>
<li><p><a class="reference internal" href="#required">required</a> - Whether or not the command-line option may be omitted
(optionals only).</p></li>
<li><p><a class="reference internal" href="#help">help</a> - A brief description of what the argument does.</p></li>
<li><p><a class="reference internal" href="#metavar">metavar</a> - A name for the argument in usage messages.</p></li>
<li><p><a class="reference internal" href="#dest">dest</a> - The name of the attribute to be added to the object returned by
<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>
<li><p><a class="reference internal" href="#deprecated">deprecated</a> - Whether or not use of the argument is deprecated.</p></li>
</ul>
<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>
</dd></dl>

<p>The following sections describe how each of these are used.</p>
<section id="name-or-flags">
<span id="id5"></span><h3>name or flags<a class="headerlink" href="#name-or-flags" title="Link to this heading">¶</a></h3>
<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 optional
argument, 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 of
filenames, is expected.  The first arguments passed to
<code class="xref py py-meth docutils literal notranslate"><span class="pre">add_argument()</span></code> must therefore be either a series of
flags, or a simple argument name.</p>
<p>For example, an optional argument could be created like:</p>
<div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="gp">&gt;&gt;&gt; </span><span class="n">parser</span><span class="o">.</span><span class="n">add_argument</span><span class="p">(</span><span class="s1">&#39;-f&#39;</span><span class="p">,</span> <span class="s1">&#39;--foo&#39;</span><span class="p">)</span>
</pre></div>
</div>
<p>while a positional argument could be created like:</p>
<div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="gp">&gt;&gt;&gt; </span><span class="n">parser</span><span class="o">.</span><span class="n">add_argument</span><span class="p">(</span><span class="s1">&#39;bar&#39;</span><span class="p">)</span>
</pre></div>
</div>
<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 be
identified by the <code class="docutils literal notranslate"><span class="pre">-</span></code> prefix, and the remaining arguments will be assumed to
be positional:</p>
<div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="gp">&gt;&gt;&gt; </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">&#39;PROG&#39;</span><span class="p">)</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">parser</span><span class="o">.</span><span class="n">add_argument</span><span class="p">(</span><span class="s1">&#39;-f&#39;</span><span class="p">,</span> <span class="s1">&#39;--foo&#39;</span><span class="p">)</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">parser</span><span class="o">.</span><span class="n">add_argument</span><span class="p">(</span><span class="s1">&#39;bar&#39;</span><span class="p">)</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">parser</span><span class="o">.</span><span class="n">parse_args</span><span class="p">([</span><span class="s1">&#39;BAR&#39;</span><span class="p">])</span>
<span class="go">Namespace(bar=&#39;BAR&#39;, foo=None)</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">parser</span><span class="o">.</span><span class="n">parse_args</span><span class="p">([</span><span class="s1">&#39;BAR&#39;</span><span class="p">,</span> <span class="s1">&#39;--foo&#39;</span><span class="p">,</span> <span class="s1">&#39;FOO&#39;</span><span class="p">])</span>
<span class="go">Namespace(bar=&#39;BAR&#39;, foo=&#39;FOO&#39;)</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">parser</span><span class="o">.</span><span class="n">parse_args</span><span class="p">([</span><span class="s1">&#39;--foo&#39;</span><span class="p">,</span> <span class="s1">&#39;FOO&#39;</span><span class="p">])</span>
<span class="go">usage: PROG [-h] [-f FOO] bar</span>
<span class="go">PROG: error: the following arguments are required: bar</span>
</pre></div>
</div>
<p>By default, <code class="xref py py-mod docutils literal notranslate"><span class="pre">argparse</span></code> automatically handles the internal naming and
display names of arguments, simplifying the process without requiring
additional configuration.
As 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.
For optional arguments, the <a class="reference internal" href="#dest">dest</a> parameter defaults to the argument name, with
underscores <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 to
the upper-cased name. For example:</p>
<div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="gp">&gt;&gt;&gt; </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">&#39;PROG&#39;</span><span class="p">)</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">parser</span><span class="o">.</span><span class="n">add_argument</span><span class="p">(</span><span class="s1">&#39;--foo-bar&#39;</span><span class="p">)</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">parser</span><span class="o">.</span><span class="n">parse_args</span><span class="p">([</span><span class="s1">&#39;--foo-bar&#39;</span><span class="p">,</span> <span class="s1">&#39;FOO-BAR&#39;</span><span class="p">])</span>
<span class="go">Namespace(foo_bar=&#39;FOO-BAR&#39;)</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">parser</span><span class="o">.</span><span class="n">print_help</span><span class="p">()</span>
<span class="go">usage:  [-h] [--foo-bar FOO-BAR]</span>

<span class="go">optional arguments:</span>
<span class="go"> -h, --help  show this help message and exit</span>
<span class="go"> --foo-bar FOO-BAR</span>
</pre></div>
</div>
</section>
<section id="action">
<span id="id6"></span><h3>action<a class="headerlink" href="#action" title="Link to this heading">¶</a></h3>
<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.  These
actions can do just about anything with the command-line arguments associated with
them, though most actions simply add an attribute to the object returned by
<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 specifies
how the command-line arguments should be handled. The supplied actions are:</p>
<ul>
<li><p><code class="docutils literal notranslate"><span class="pre">'store'</span></code> - This just stores the argument’s value.  This is the default
action.</p></li>
<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> keyword
argument; 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>.  The
<code class="docutils literal notranslate"><span class="pre">'store_const'</span></code> action is most commonly used with optional arguments that
specify some sort of flag.  For example:</p>
<div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="gp">&gt;&gt;&gt; </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="gp">&gt;&gt;&gt; </span><span class="n">parser</span><span class="o">.</span><span class="n">add_argument</span><span class="p">(</span><span class="s1">&#39;--foo&#39;</span><span class="p">,</span> <span class="n">action</span><span class="o">=</span><span class="s1">&#39;store_const&#39;</span><span class="p">,</span> <span class="n">const</span><span class="o">=</span><span class="mi">42</span><span class="p">)</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">parser</span><span class="o">.</span><span class="n">parse_args</span><span class="p">([</span><span class="s1">&#39;--foo&#39;</span><span class="p">])</span>
<span class="go">Namespace(foo=42)</span>
</pre></div>
</div>
</li>
<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 of
<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>
with default values of <code class="docutils literal notranslate"><span class="pre">False</span></code> and
<code class="docutils literal notranslate"><span class="pre">True</span></code>:</p>
<div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="gp">&gt;&gt;&gt; </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="gp">&gt;&gt;&gt; </span><span class="n">parser</span><span class="o">.</span><span class="n">add_argument</span><span class="p">(</span><span class="s1">&#39;--foo&#39;</span><span class="p">,</span> <span class="n">action</span><span class="o">=</span><span class="s1">&#39;store_true&#39;</span><span class="p">)</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">parser</span><span class="o">.</span><span class="n">add_argument</span><span class="p">(</span><span class="s1">&#39;--bar&#39;</span><span class="p">,</span> <span class="n">action</span><span class="o">=</span><span class="s1">&#39;store_false&#39;</span><span class="p">)</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">parser</span><span class="o">.</span><span class="n">add_argument</span><span class="p">(</span><span class="s1">&#39;--baz&#39;</span><span class="p">,</span> <span class="n">action</span><span class="o">=</span><span class="s1">&#39;store_false&#39;</span><span class="p">)</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">parser</span><span class="o">.</span><span class="n">parse_args</span><span class="p">(</span><span class="s1">&#39;--foo --bar&#39;</span><span class="o">.</span><span class="n">split</span><span class="p">())</span>
<span class="go">Namespace(foo=True, bar=False, baz=True)</span>
</pre></div>
</div>
</li>
<li><p><code class="docutils literal notranslate"><span class="pre">'append'</span></code> - This appends each argument value to a list.
It is useful for allowing an option to be specified multiple times.
If the default value is a non-empty list, the parsed value will start
with the default list’s elements and any values from the command line
will be appended after those default values. Example usage:</p>
<div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="gp">&gt;&gt;&gt; </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="gp">&gt;&gt;&gt; </span><span class="n">parser</span><span class="o">.</span><span class="n">add_argument</span><span class="p">(</span><span class="s1">&#39;--foo&#39;</span><span class="p">,</span> <span class="n">action</span><span class="o">=</span><span class="s1">&#39;append&#39;</span><span class="p">,</span> <span class="n">default</span><span class="o">=</span><span class="p">[</span><span class="s1">&#39;0&#39;</span><span class="p">])</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">parser</span><span class="o">.</span><span class="n">parse_args</span><span class="p">(</span><span class="s1">&#39;--foo 1 --foo 2&#39;</span><span class="o">.</span><span class="n">split</span><span class="p">())</span>
<span class="go">Namespace(foo=[&#39;0&#39;, &#39;1&#39;, &#39;2&#39;])</span>
</pre></div>
</div>
</li>
<li><p><code class="docutils literal notranslate"><span class="pre">'append_const'</span></code> - This appends the value specified by
the <a class="reference internal" href="#const">const</a> keyword argument to a list; 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>. The <code class="docutils literal notranslate"><span class="pre">'append_const'</span></code> action is typically
useful when multiple arguments need to store constants to the same list. For
example:</p>
<div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="gp">&gt;&gt;&gt; </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="gp">&gt;&gt;&gt; </span><span class="n">parser</span><span class="o">.</span><span class="n">add_argument</span><span class="p">(</span><span class="s1">&#39;--str&#39;</span><span class="p">,</span> <span class="n">dest</span><span class="o">=</span><span class="s1">&#39;types&#39;</span><span class="p">,</span> <span class="n">action</span><span class="o">=</span><span class="s1">&#39;append_const&#39;</span><span class="p">,</span> <span class="n">const</span><span class="o">=</span><span class="nb">str</span><span class="p">)</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">parser</span><span class="o">.</span><span class="n">add_argument</span><span class="p">(</span><span class="s1">&#39;--int&#39;</span><span class="p">,</span> <span class="n">dest</span><span class="o">=</span><span class="s1">&#39;types&#39;</span><span class="p">,</span> <span class="n">action</span><span class="o">=</span><span class="s1">&#39;append_const&#39;</span><span class="p">,</span> <span class="n">const</span><span class="o">=</span><span class="nb">int</span><span class="p">)</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">parser</span><span class="o">.</span><span class="n">parse_args</span><span class="p">(</span><span class="s1">&#39;--str --int&#39;</span><span class="o">.</span><span class="n">split</span><span class="p">())</span>
<span class="go">Namespace(types=[&lt;class &#39;str&#39;&gt;, &lt;class &#39;int&#39;&gt;])</span>
</pre></div>
</div>
</li>
<li><p><code class="docutils literal notranslate"><span class="pre">'extend'</span></code> - This appends each item from a multi-value
argument to a list.
The <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 argument
value <code class="docutils literal notranslate"><span class="pre">'+'</span></code> or <code class="docutils literal notranslate"><span class="pre">'*'</span></code>.
Note 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>, each
character of the argument string will be appended to the list.
Example usage:</p>
<div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="gp">&gt;&gt;&gt; </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="gp">&gt;&gt;&gt; </span><span class="n">parser</span><span class="o">.</span><span class="n">add_argument</span><span class="p">(</span><span class="s2">&quot;--foo&quot;</span><span class="p">,</span> <span class="n">action</span><span class="o">=</span><span class="s2">&quot;extend&quot;</span><span class="p">,</span> <span class="n">nargs</span><span class="o">=</span><span class="s2">&quot;+&quot;</span><span class="p">,</span> <span class="nb">type</span><span class="o">=</span><span class="nb">str</span><span class="p">)</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">parser</span><span class="o">.</span><span class="n">parse_args</span><span class="p">([</span><span class="s2">&quot;--foo&quot;</span><span class="p">,</span> <span class="s2">&quot;f1&quot;</span><span class="p">,</span> <span class="s2">&quot;--foo&quot;</span><span class="p">,</span> <span class="s2">&quot;f2&quot;</span><span class="p">,</span> <span class="s2">&quot;f3&quot;</span><span class="p">,</span> <span class="s2">&quot;f4&quot;</span><span class="p">])</span>
<span class="go">Namespace(foo=[&#39;f1&#39;, &#39;f2&#39;, &#39;f3&#39;, &#39;f4&#39;])</span>
</pre></div>
</div>
<div class="versionadded">
<p><span class="versionmodified added">Added in version 3.8.</span></p>
</div>
</li>
<li><p><code class="docutils literal notranslate"><span class="pre">'count'</span></code> - This counts the number of times an argument occurs. For
example, this is useful for increasing verbosity levels:</p>
<div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="gp">&gt;&gt;&gt; </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="gp">&gt;&gt;&gt; </span><span class="n">parser</span><span class="o">.</span><span class="n">add_argument</span><span class="p">(</span><span class="s1">&#39;--verbose&#39;</span><span class="p">,</span> <span class="s1">&#39;-v&#39;</span><span class="p">,</span> <span class="n">action</span><span class="o">=</span><span class="s1">&#39;count&#39;</span><span class="p">,</span> <span class="n">default</span><span class="o">=</span><span class="mi">0</span><span class="p">)</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">parser</span><span class="o">.</span><span class="n">parse_args</span><span class="p">([</span><span class="s1">&#39;-vvv&#39;</span><span class="p">])</span>
<span class="go">Namespace(verbose=3)</span>
</pre></div>
</div>
<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>
</li>
<li><p><code class="docutils literal notranslate"><span class="pre">'help'</span></code> - This prints a complete help message for all the options in the
current parser and then exits. By default a help action is automatically
added 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 the
output is created.</p></li>
<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 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> call, and prints version information
and exits when invoked:</p>
<div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="gp">&gt;&gt;&gt; </span><span class="kn">import</span><span class="w"> </span><span class="nn">argparse</span>
<span class="gp">&gt;&gt;&gt; </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">&#39;PROG&#39;</span><span class="p">)</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">parser</span><span class="o">.</span><span class="n">add_argument</span><span class="p">(</span><span class="s1">&#39;--version&#39;</span><span class="p">,</span> <span class="n">action</span><span class="o">=</span><span class="s1">&#39;version&#39;</span><span class="p">,</span> <span class="n">version</span><span class="o">=</span><span class="s1">&#39;</span><span class="si">%(prog)s</span><span class="s1"> 2.0&#39;</span><span class="p">)</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">parser</span><span class="o">.</span><span class="n">parse_args</span><span class="p">([</span><span class="s1">&#39;--version&#39;</span><span class="p">])</span>
<span class="go">PROG 2.0</span>
</pre></div>
</div>
</li>
</ul>
<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> subclass
(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 same
interface. Only actions that consume command-line arguments (e.g. <code class="docutils literal notranslate"><span class="pre">'store'</span></code>,
<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 used
with positional arguments.</p>
<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>,
overriding 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> and
<code class="xref py py-meth docutils literal notranslate"><span class="pre">format_usage()</span></code> methods. You can also register custom actions using the
<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>
<p>An example of a custom action:</p>
<div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="gp">&gt;&gt;&gt; </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>
<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>
<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>
<span class="gp">... </span>            <span class="k">raise</span> <span class="ne">ValueError</span><span class="p">(</span><span class="s2">&quot;nargs not allowed&quot;</span><span class="p">)</span>
<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>
<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>
<span class="gp">... </span>        <span class="nb">print</span><span class="p">(</span><span class="s1">&#39;</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">&#39;</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>
<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>
<span class="gp">...</span>
<span class="gp">&gt;&gt;&gt; </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="gp">&gt;&gt;&gt; </span><span class="n">parser</span><span class="o">.</span><span class="n">add_argument</span><span class="p">(</span><span class="s1">&#39;--foo&#39;</span><span class="p">,</span> <span class="n">action</span><span class="o">=</span><span class="n">FooAction</span><span class="p">)</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">parser</span><span class="o">.</span><span class="n">add_argument</span><span class="p">(</span><span class="s1">&#39;bar&#39;</span><span class="p">,</span> <span class="n">action</span><span class="o">=</span><span class="n">FooAction</span><span class="p">)</span>
<span class="gp">&gt;&gt;&gt; </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">&#39;1 --foo 2&#39;</span><span class="o">.</span><span class="n">split</span><span class="p">())</span>
<span class="go">Namespace(bar=None, foo=None) &#39;1&#39; None</span>
<span class="go">Namespace(bar=&#39;1&#39;, foo=None) &#39;2&#39; &#39;--foo&#39;</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">args</span>
<span class="go">Namespace(bar=&#39;1&#39;, foo=&#39;2&#39;)</span>
</pre></div>
</div>
<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>
</section>
<section id="nargs">
<span id="id7"></span><h3>nargs<a class="headerlink" href="#nargs" title="Link to this heading">¶</a></h3>
<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 a
single action to be taken.  The <code class="docutils literal notranslate"><span class="pre">nargs</span></code> keyword argument associates a
different number of command-line arguments with a single action.
See 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>
<ul>
<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 gathered
together into a list.  For example:</p>
<div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="gp">&gt;&gt;&gt; </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="gp">&gt;&gt;&gt; </span><span class="n">parser</span><span class="o">.</span><span class="n">add_argument</span><span class="p">(</span><span class="s1">&#39;--foo&#39;</span><span class="p">,</span> <span class="n">nargs</span><span class="o">=</span><span class="mi">2</span><span class="p">)</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">parser</span><span class="o">.</span><span class="n">add_argument</span><span class="p">(</span><span class="s1">&#39;bar&#39;</span><span class="p">,</span> <span class="n">nargs</span><span class="o">=</span><span class="mi">1</span><span class="p">)</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">parser</span><span class="o">.</span><span class="n">parse_args</span><span class="p">(</span><span class="s1">&#39;c --foo a b&#39;</span><span class="o">.</span><span class="n">split</span><span class="p">())</span>
<span class="go">Namespace(bar=[&#39;c&#39;], foo=[&#39;a&#39;, &#39;b&#39;])</span>
</pre></div>
</div>
<p>Note that <code class="docutils literal notranslate"><span class="pre">nargs=1</span></code> produces a list of one item.  This is different from
the default, in which the item is produced by itself.</p>
</li>
</ul>
<ul id="index-0">
<li><p><code class="docutils literal notranslate"><span class="pre">'?'</span></code>. One argument will be consumed from the command line if possible, and
produced as a single item.  If no command-line argument is present, the value from
<a class="reference internal" href="#default">default</a> will be produced.  Note that for optional arguments, there is an
additional case - the option string is present but not followed by a
command-line argument.  In this case the value from <a class="reference internal" href="#const">const</a> will be produced.  Some
examples to illustrate this:</p>
<div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="gp">&gt;&gt;&gt; </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="gp">&gt;&gt;&gt; </span><span class="n">parser</span><span class="o">.</span><span class="n">add_argument</span><span class="p">(</span><span class="s1">&#39;--foo&#39;</span><span class="p">,</span> <span class="n">nargs</span><span class="o">=</span><span class="s1">&#39;?&#39;</span><span class="p">,</span> <span class="n">const</span><span class="o">=</span><span class="s1">&#39;c&#39;</span><span class="p">,</span> <span class="n">default</span><span class="o">=</span><span class="s1">&#39;d&#39;</span><span class="p">)</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">parser</span><span class="o">.</span><span class="n">add_argument</span><span class="p">(</span><span class="s1">&#39;bar&#39;</span><span class="p">,</span> <span class="n">nargs</span><span class="o">=</span><span class="s1">&#39;?&#39;</span><span class="p">,</span> <span class="n">default</span><span class="o">=</span><span class="s1">&#39;d&#39;</span><span class="p">)</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">parser</span><span class="o">.</span><span class="n">parse_args</span><span class="p">([</span><span class="s1">&#39;XX&#39;</span><span class="p">,</span> <span class="s1">&#39;--foo&#39;</span><span class="p">,</span> <span class="s1">&#39;YY&#39;</span><span class="p">])</span>
<span class="go">Namespace(bar=&#39;XX&#39;, foo=&#39;YY&#39;)</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">parser</span><span class="o">.</span><span class="n">parse_args</span><span class="p">([</span><span class="s1">&#39;XX&#39;</span><span class="p">,</span> <span class="s1">&#39;--foo&#39;</span><span class="p">])</span>
<span class="go">Namespace(bar=&#39;XX&#39;, foo=&#39;c&#39;)</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">parser</span><span class="o">.</span><span class="n">parse_args</span><span class="p">([])</span>
<span class="go">Namespace(bar=&#39;d&#39;, foo=&#39;d&#39;)</span>
</pre></div>
</div>
<p>One of the more common uses of <code class="docutils literal notranslate"><span class="pre">nargs='?'</span></code> is to allow optional input and
output files:</p>
<div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="gp">&gt;&gt;&gt; </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="gp">&gt;&gt;&gt; </span><span class="n">parser</span><span class="o">.</span><span class="n">add_argument</span><span class="p">(</span><span class="s1">&#39;infile&#39;</span><span class="p">,</span> <span class="n">nargs</span><span class="o">=</span><span class="s1">&#39;?&#39;</span><span class="p">)</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">parser</span><span class="o">.</span><span class="n">add_argument</span><span class="p">(</span><span class="s1">&#39;outfile&#39;</span><span class="p">,</span> <span class="n">nargs</span><span class="o">=</span><span class="s1">&#39;?&#39;</span><span class="p">)</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">parser</span><span class="o">.</span><span class="n">parse_args</span><span class="p">([</span><span class="s1">&#39;input.txt&#39;</span><span class="p">,</span> <span class="s1">&#39;output.txt&#39;</span><span class="p">])</span>
<span class="go">Namespace(infile=&#39;input.txt&#39;, outfile=&#39;output.txt&#39;)</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">parser</span><span class="o">.</span><span class="n">parse_args</span><span class="p">([</span><span class="s1">&#39;input.txt&#39;</span><span class="p">])</span>
<span class="go">Namespace(infile=&#39;input.txt&#39;, outfile=None)</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">parser</span><span class="o">.</span><span class="n">parse_args</span><span class="p">([])</span>
<span class="go">Namespace(infile=None, outfile=None)</span>
</pre></div>
</div>
</li>
</ul>
<ul id="index-1">
<li><p><code class="docutils literal notranslate"><span class="pre">'*'</span></code>.  All command-line arguments present are gathered into a list.  Note that
it generally doesn’t make much sense to have more than one positional argument
with <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> is
possible.  For example:</p>
<div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="gp">&gt;&gt;&gt; </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="gp">&gt;&gt;&gt; </span><span class="n">parser</span><span class="o">.</span><span class="n">add_argument</span><span class="p">(</span><span class="s1">&#39;--foo&#39;</span><span class="p">,</span> <span class="n">nargs</span><span class="o">=</span><span class="s1">&#39;*&#39;</span><span class="p">)</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">parser</span><span class="o">.</span><span class="n">add_argument</span><span class="p">(</span><span class="s1">&#39;--bar&#39;</span><span class="p">,</span> <span class="n">nargs</span><span class="o">=</span><span class="s1">&#39;*&#39;</span><span class="p">)</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">parser</span><span class="o">.</span><span class="n">add_argument</span><span class="p">(</span><span class="s1">&#39;baz&#39;</span><span class="p">,</span> <span class="n">nargs</span><span class="o">=</span><span class="s1">&#39;*&#39;</span><span class="p">)</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">parser</span><span class="o">.</span><span class="n">parse_args</span><span class="p">(</span><span class="s1">&#39;a b --foo x y --bar 1 2&#39;</span><span class="o">.</span><span class="n">split</span><span class="p">())</span>
<span class="go">Namespace(bar=[&#39;1&#39;, &#39;2&#39;], baz=[&#39;a&#39;, &#39;b&#39;], foo=[&#39;x&#39;, &#39;y&#39;])</span>
</pre></div>
</div>
</li>
</ul>
<ul id="index-2">
<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 a
list.  Additionally, an error message will be generated if there wasn’t at
least one command-line argument present.  For example:</p>
<div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="gp">&gt;&gt;&gt; </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">&#39;PROG&#39;</span><span class="p">)</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">parser</span><span class="o">.</span><span class="n">add_argument</span><span class="p">(</span><span class="s1">&#39;foo&#39;</span><span class="p">,</span> <span class="n">nargs</span><span class="o">=</span><span class="s1">&#39;+&#39;</span><span class="p">)</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">parser</span><span class="o">.</span><span class="n">parse_args</span><span class="p">([</span><span class="s1">&#39;a&#39;</span><span class="p">,</span> <span class="s1">&#39;b&#39;</span><span class="p">])</span>
<span class="go">Namespace(foo=[&#39;a&#39;, &#39;b&#39;])</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">parser</span><span class="o">.</span><span class="n">parse_args</span><span class="p">([])</span>
<span class="go">usage: PROG [-h] foo [foo ...]</span>
<span class="go">PROG: error: the following arguments are required: foo</span>
</pre></div>
</div>
</li>
</ul>
<p>If the <code class="docutils literal notranslate"><span class="pre">nargs</span></code> keyword argument is not provided, the number of arguments consumed
is determined by the <a class="reference internal" href="#action">action</a>.  Generally this means a single command-line argument
will be consumed and a single item (not a list) will be produced.
Actions that do not consume command-line arguments (e.g.
<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>
</section>
<section id="const">
<span id="id8"></span><h3>const<a class="headerlink" href="#const" title="Link to this heading">¶</a></h3>
<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 hold
constant values that are not read from the command line but are required for
the 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>
<ul class="simple">
<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
<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 the
<code class="docutils literal notranslate"><span class="pre">const</span></code> value to one of the attributes of the object returned by
<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.
If <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 will
receive a default value of <code class="docutils literal notranslate"><span class="pre">None</span></code>.</p></li>
<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 strings
(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 optional
argument that can be followed by zero or one command-line arguments.
When parsing the command line, if the option string is encountered with no
command-line argument following it, the value from <code class="docutils literal notranslate"><span class="pre">const</span></code> will be used.
See the <a class="reference internal" href="#nargs">nargs</a> description for examples.</p></li>
</ul>
<div class="versionchanged">
<p><span class="versionmodified changed">Changed in version 3.11: </span><code class="docutils literal notranslate"><span class="pre">const=None</span></code> by default, including when <code class="docutils literal notranslate"><span class="pre">action='append_const'</span></code> or
<code class="docutils literal notranslate"><span class="pre">action='store_const'</span></code>.</p>
</div>
</section>
<section id="default">
<span id="id9"></span><h3>default<a class="headerlink" href="#default" title="Link to this heading">¶</a></h3>
<p>All optional arguments and some positional arguments may be omitted at the
command line.  The <code class="docutils literal notranslate"><span class="pre">default</span></code> keyword 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>, whose value defaults to <code class="docutils literal notranslate"><span class="pre">None</span></code>,
specifies what value should be used if the command-line argument is not present.
For optional arguments, the <code class="docutils literal notranslate"><span class="pre">default</span></code> value is used when the option string
was not present at the command line:</p>
<div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="gp">&gt;&gt;&gt; </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="gp">&gt;&gt;&gt; </span><span class="n">parser</span><span class="o">.</span><span class="n">add_argument</span><span class="p">(</span><span class="s1">&#39;--foo&#39;</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="gp">&gt;&gt;&gt; </span><span class="n">parser</span><span class="o">.</span><span class="n">parse_args</span><span class="p">([</span><span class="s1">&#39;--foo&#39;</span><span class="p">,</span> <span class="s1">&#39;2&#39;</span><span class="p">])</span>
<span class="go">Namespace(foo=&#39;2&#39;)</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">parser</span><span class="o">.</span><span class="n">parse_args</span><span class="p">([])</span>
<span class="go">Namespace(foo=42)</span>
</pre></div>
</div>
<p>If the target namespace already has an attribute set, the action <em>default</em>
will not overwrite it:</p>
<div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="gp">&gt;&gt;&gt; </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="gp">&gt;&gt;&gt; </span><span class="n">parser</span><span class="o">.</span><span class="n">add_argument</span><span class="p">(</span><span class="s1">&#39;--foo&#39;</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="gp">&gt;&gt;&gt; </span><span class="n">parser</span><span class="o">.</span><span class="n">parse_args</span><span class="p">([],</span> <span class="n">namespace</span><span class="o">=</span><span class="n">argparse</span><span class="o">.</span><span class="n">Namespace</span><span class="p">(</span><span class="n">foo</span><span class="o">=</span><span class="mi">101</span><span class="p">))</span>
<span class="go">Namespace(foo=101)</span>
</pre></div>
</div>
<p>If the <code class="docutils literal notranslate"><span class="pre">default</span></code> value is a string, the parser parses the value as if it
were a command-line argument.  In particular, the parser applies any <a class="reference internal" href="#type">type</a>
conversion argument, if provided, before setting the attribute on the
<a class="reference internal" href="#argparse.Namespace" title="argparse.Namespace"><code class="xref py py-class docutils literal notranslate"><span class="pre">Namespace</span></code></a> return value.  Otherwise, the parser uses the value as is:</p>
<div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="gp">&gt;&gt;&gt; </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="gp">&gt;&gt;&gt; </span><span class="n">parser</span><span class="o">.</span><span class="n">add_argument</span><span class="p">(</span><span class="s1">&#39;--length&#39;</span><span class="p">,</span> <span class="n">default</span><span class="o">=</span><span class="s1">&#39;10&#39;</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="gp">&gt;&gt;&gt; </span><span class="n">parser</span><span class="o">.</span><span class="n">add_argument</span><span class="p">(</span><span class="s1">&#39;--width&#39;</span><span class="p">,</span> <span class="n">default</span><span class="o">=</span><span class="mf">10.5</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="gp">&gt;&gt;&gt; </span><span class="n">parser</span><span class="o">.</span><span class="n">parse_args</span><span class="p">()</span>
<span class="go">Namespace(length=10, width=10.5)</span>
</pre></div>
</div>
<p>For positional arguments with <a class="reference internal" href="#nargs">nargs</a> equal to <code class="docutils literal notranslate"><span class="pre">?</span></code> or <code class="docutils literal notranslate"><span class="pre">*</span></code>, the <code class="docutils literal notranslate"><span class="pre">default</span></code> value
is used when no command-line argument was present:</p>
<div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="gp">&gt;&gt;&gt; </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="gp">&gt;&gt;&gt; </span><span class="n">parser</span><span class="o">.</span><span class="n">add_argument</span><span class="p">(</span><span class="s1">&#39;foo&#39;</span><span class="p">,</span> <span class="n">nargs</span><span class="o">=</span><span class="s1">&#39;?&#39;</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="gp">&gt;&gt;&gt; </span><span class="n">parser</span><span class="o">.</span><span class="n">parse_args</span><span class="p">([</span><span class="s1">&#39;a&#39;</span><span class="p">])</span>
<span class="go">Namespace(foo=&#39;a&#39;)</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">parser</span><span class="o">.</span><span class="n">parse_args</span><span class="p">([])</span>
<span class="go">Namespace(foo=42)</span>
</pre></div>
</div>
<p>For <a class="reference internal" href="#required">required</a> arguments, the <code class="docutils literal notranslate"><span class="pre">default</span></code> value is ignored. For example, this
applies to positional arguments with <a class="reference internal" href="#nargs">nargs</a> values other than <code class="docutils literal notranslate"><span class="pre">?</span></code> or <code class="docutils literal notranslate"><span class="pre">*</span></code>,
or optional arguments marked as <code class="docutils literal notranslate"><span class="pre">required=True</span></code>.</p>
<p>Providing <code class="docutils literal notranslate"><span class="pre">default=argparse.SUPPRESS</span></code> causes no attribute to be added if the
command-line argument was not present:</p>
<div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="gp">&gt;&gt;&gt; </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="gp">&gt;&gt;&gt; </span><span class="n">parser</span><span class="o">.</span><span class="n">add_argument</span><span class="p">(</span><span class="s1">&#39;--foo&#39;</span><span class="p">,</span> <span class="n">default</span><span class="o">=</span><span class="n">argparse</span><span class="o">.</span><span class="n">SUPPRESS</span><span class="p">)</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">parser</span><span class="o">.</span><span class="n">parse_args</span><span class="p">([])</span>
<span class="go">Namespace()</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">parser</span><span class="o">.</span><span class="n">parse_args</span><span class="p">([</span><span class="s1">&#39;--foo&#39;</span><span class="p">,</span> <span class="s1">&#39;1&#39;</span><span class="p">])</span>
<span class="go">Namespace(foo=&#39;1&#39;)</span>
</pre></div>
</div>
</section>
<section id="type">
<span id="argparse-type"></span><h3>type<a class="headerlink" href="#type" title="Link to this heading">¶</a></h3>
<p>By default, the parser reads command-line arguments in as simple
strings. However, quite often the command-line string should instead be
interpreted as another type, such as a <a class="reference internal" href="functions.html#float" title="float"><code class="xref py py-class docutils literal notranslate"><span class="pre">float</span></code></a> or <a class="reference internal" href="functions.html#int" title="int"><code class="xref py py-class docutils literal notranslate"><span class="pre">int</span></code></a>.  The
<code class="docutils literal notranslate"><span class="pre">type</span></code> keyword for <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> allows any
necessary type-checking and type conversions to be performed.</p>
<p>If the <a class="reference internal" href="#type">type</a> keyword is used with the <a class="reference internal" href="#default">default</a> keyword, the type converter
is only applied if the default is a string.</p>
<p>The argument to <code class="docutils literal notranslate"><span class="pre">type</span></code> can be a callable that accepts a single string or
the name of a registered type (see <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>)
If the function raises <a class="reference internal" href="#argparse.ArgumentTypeError" title="argparse.ArgumentTypeError"><code class="xref py py-exc docutils literal notranslate"><span class="pre">ArgumentTypeError</span></code></a>, <a class="reference internal" href="exceptions.html#TypeError" title="TypeError"><code class="xref py py-exc docutils literal notranslate"><span class="pre">TypeError</span></code></a>, or
<a class="reference internal" href="exceptions.html#ValueError" title="ValueError"><code class="xref py py-exc docutils literal notranslate"><span class="pre">ValueError</span></code></a>, the exception is caught and a nicely formatted error
message is displayed. Other exception types are not handled.</p>
<p>Common built-in types and functions can be used as type converters:</p>
<div class="highlight-python notranslate"><div class="highlight"><pre><span></span><span class="kn">import</span><span class="w"> </span><span class="nn">argparse</span>
<span class="kn">import</span><span class="w"> </span><span class="nn">pathlib</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">parser</span><span class="o">.</span><span class="n">add_argument</span><span class="p">(</span><span class="s1">&#39;count&#39;</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">parser</span><span class="o">.</span><span class="n">add_argument</span><span class="p">(</span><span class="s1">&#39;distance&#39;</span><span class="p">,</span> <span class="nb">type</span><span class="o">=</span><span class="nb">float</span><span class="p">)</span>
<span class="n">parser</span><span class="o">.</span><span class="n">add_argument</span><span class="p">(</span><span class="s1">&#39;street&#39;</span><span class="p">,</span> <span class="nb">type</span><span class="o">=</span><span class="n">ascii</span><span class="p">)</span>
<span class="n">parser</span><span class="o">.</span><span class="n">add_argument</span><span class="p">(</span><span class="s1">&#39;code_point&#39;</span><span class="p">,</span> <span class="nb">type</span><span class="o">=</span><span class="nb">ord</span><span class="p">)</span>
<span class="n">parser</span><span class="o">.</span><span class="n">add_argument</span><span class="p">(</span><span class="s1">&#39;datapath&#39;</span><span class="p">,</span> <span class="nb">type</span><span class="o">=</span><span class="n">pathlib</span><span class="o">.</span><span class="n">Path</span><span class="p">)</span>
</pre></div>
</div>
<p>User defined functions can be used as well:</p>
<div class="highlight-pycon notranslate"><div class="highlight"><pre><span></span><span class="gp">&gt;&gt;&gt; </span><span class="k">def</span><span class="w"> </span><span class="nf">hyphenated</span><span class="p">(</span><span class="n">string</span><span class="p">):</span>
<span class="gp">... </span>    <span class="k">return</span> <span class="s1">&#39;-&#39;</span><span class="o">.</span><span class="n">join</span><span class="p">([</span><span class="n">word</span><span class="p">[:</span><span class="mi">4</span><span class="p">]</span> <span class="k">for</span> <span class="n">word</span> <span class="ow">in</span> <span class="n">string</span><span class="o">.</span><span class="n">casefold</span><span class="p">()</span><span class="o">.</span><span class="n">split</span><span class="p">()])</span>
<span class="gp">...</span>
<span class="gp">&gt;&gt;&gt; </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="gp">&gt;&gt;&gt; </span><span class="n">_</span> <span class="o">=</span> <span class="n">parser</span><span class="o">.</span><span class="n">add_argument</span><span class="p">(</span><span class="s1">&#39;short_title&#39;</span><span class="p">,</span> <span class="nb">type</span><span class="o">=</span><span class="n">hyphenated</span><span class="p">)</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">parser</span><span class="o">.</span><span class="n">parse_args</span><span class="p">([</span><span class="s1">&#39;&quot;The Tale of Two Cities&quot;&#39;</span><span class="p">])</span>
<span class="go">Namespace(short_title=&#39;&quot;the-tale-of-two-citi&#39;)</span>
</pre></div>
</div>
<p>The <a class="reference internal" href="functions.html#bool" title="bool"><code class="xref py py-func docutils literal notranslate"><span class="pre">bool()</span></code></a> function is not recommended as a type converter.  All it does
is convert empty strings to <code class="docutils literal notranslate"><span class="pre">False</span></code> and non-empty strings to <code class="docutils literal notranslate"><span class="pre">True</span></code>.
This is usually not what is desired.</p>
<p>In general, the <code class="docutils literal notranslate"><span class="pre">type</span></code> keyword is a convenience that should only be used for
simple conversions that can only raise one of the three supported exceptions.
Anything with more interesting error-handling or resource management should be
done downstream after the arguments are parsed.</p>
<p>For example, JSON or YAML conversions have complex error cases that require
better reporting than can be given by the <code class="docutils literal notranslate"><span class="pre">type</span></code> keyword.  A
<a class="reference internal" href="json.html#json.JSONDecodeError" title="json.JSONDecodeError"><code class="xref py py-exc docutils literal notranslate"><span class="pre">JSONDecodeError</span></code></a> would not be well formatted and a
<a class="reference internal" href="exceptions.html#FileNotFoundError" title="FileNotFoundError"><code class="xref py py-exc docutils literal notranslate"><span class="pre">FileNotFoundError</span></code></a> exception would not be handled at all.</p>
<p>Even <a class="reference internal" href="#argparse.FileType" title="argparse.FileType"><code class="xref py py-class docutils literal notranslate"><span class="pre">FileType</span></code></a> has its limitations for use with the <code class="docutils literal notranslate"><span class="pre">type</span></code>
keyword.  If one argument uses <code class="xref py py-class docutils literal notranslate"><span class="pre">FileType</span></code> and then a
subsequent argument fails, an error is reported but the file is not
automatically closed.  In this case, it would be better to wait until after
the parser has run and then use the <a class="reference internal" href="../reference/compound_stmts.html#with"><code class="xref std std-keyword docutils literal notranslate"><span class="pre">with</span></code></a>-statement to manage the
files.</p>
<p>For type checkers that simply check against a fixed set of values, consider
using the <a class="reference internal" href="#choices">choices</a> keyword instead.</p>
</section>
<section id="choices">
<span id="id10"></span><h3>choices<a class="headerlink" href="#choices" title="Link to this heading">¶</a></h3>
<p>Some command-line arguments should be selected from a restricted set of values.
These can be handled by passing a sequence object as the <em>choices</em> keyword
argument to <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>.  When the command line is
parsed, argument values will be checked, and an error message will be displayed
if the argument was not one of the acceptable values:</p>
<div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="gp">&gt;&gt;&gt; </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">&#39;game.py&#39;</span><span class="p">)</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">parser</span><span class="o">.</span><span class="n">add_argument</span><span class="p">(</span><span class="s1">&#39;move&#39;</span><span class="p">,</span> <span class="n">choices</span><span class="o">=</span><span class="p">[</span><span class="s1">&#39;rock&#39;</span><span class="p">,</span> <span class="s1">&#39;paper&#39;</span><span class="p">,</span> <span class="s1">&#39;scissors&#39;</span><span class="p">])</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">parser</span><span class="o">.</span><span class="n">parse_args</span><span class="p">([</span><span class="s1">&#39;rock&#39;</span><span class="p">])</span>
<span class="go">Namespace(move=&#39;rock&#39;)</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">parser</span><span class="o">.</span><span class="n">parse_args</span><span class="p">([</span><span class="s1">&#39;fire&#39;</span><span class="p">])</span>
<span class="go">usage: game.py [-h] {rock,paper,scissors}</span>
<span class="go">game.py: error: argument move: invalid choice: &#39;fire&#39; (choose from &#39;rock&#39;,</span>
<span class="go">&#39;paper&#39;, &#39;scissors&#39;)</span>
</pre></div>
</div>
<p>Any sequence can be passed as the <em>choices</em> value, so <a class="reference internal" href="stdtypes.html#list" title="list"><code class="xref py py-class docutils literal notranslate"><span class="pre">list</span></code></a> objects,
<a class="reference internal" href="stdtypes.html#tuple" title="tuple"><code class="xref py py-class docutils literal notranslate"><span class="pre">tuple</span></code></a> objects, and custom sequences are all supported.</p>
<p>Use of <a class="reference internal" href="enum.html#enum.Enum" title="enum.Enum"><code class="xref py py-class docutils literal notranslate"><span class="pre">enum.Enum</span></code></a> is not recommended because it is difficult to
control its appearance in usage, help, and error messages.</p>
<p>Note that <em>choices</em> are checked after any <a class="reference internal" href="#type">type</a>
conversions have been performed, so objects in <em>choices</em>
should match the <a class="reference internal" href="#type">type</a> specified. This can make <em>choices</em>
appear unfamiliar in usage, help, or error messages.</p>
<p>To keep <em>choices</em> user-friendly, consider a custom type wrapper that
converts and formats values, or omit <a class="reference internal" href="#type">type</a> and handle conversion in
your application code.</p>
<p>Formatted choices override the default <em>metavar</em> which is normally derived
from <em>dest</em>.  This is usually what you want because the user never sees the
<em>dest</em> parameter.  If this display isn’t desirable (perhaps because there are
many choices), just specify an explicit <a class="reference internal" href="#metavar">metavar</a>.</p>
</section>
<section id="required">
<span id="id11"></span><h3>required<a class="headerlink" href="#required" title="Link to this heading">¶</a></h3>
<p>In general, the <code class="xref py py-mod docutils literal notranslate"><span class="pre">argparse</span></code> module assumes that flags like <code class="docutils literal notranslate"><span class="pre">-f</span></code> and <code class="docutils literal notranslate"><span class="pre">--bar</span></code>
indicate <em>optional</em> arguments, which can always be omitted at the command line.
To make an option <em>required</em>, <code class="docutils literal notranslate"><span class="pre">True</span></code> can be specified for the <code class="docutils literal notranslate"><span class="pre">required=</span></code>
keyword argument to <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>:</p>
<div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="gp">&gt;&gt;&gt; </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="gp">&gt;&gt;&gt; </span><span class="n">parser</span><span class="o">.</span><span class="n">add_argument</span><span class="p">(</span><span class="s1">&#39;--foo&#39;</span><span class="p">,</span> <span class="n">required</span><span class="o">=</span><span class="kc">True</span><span class="p">)</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">parser</span><span class="o">.</span><span class="n">parse_args</span><span class="p">([</span><span class="s1">&#39;--foo&#39;</span><span class="p">,</span> <span class="s1">&#39;BAR&#39;</span><span class="p">])</span>
<span class="go">Namespace(foo=&#39;BAR&#39;)</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">parser</span><span class="o">.</span><span class="n">parse_args</span><span class="p">([])</span>
<span class="go">usage: [-h] --foo FOO</span>
<span class="go">: error: the following arguments are required: --foo</span>
</pre></div>
</div>
<p>As the example shows, if an option is marked as <code class="docutils literal notranslate"><span class="pre">required</span></code>,
<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> will report an error if that option is not
present at the command line.</p>
<div class="admonition note">
<p class="admonition-title">Note</p>
<p>Required options are generally considered bad form because users expect
<em>options</em> to be <em>optional</em>, and thus they should be avoided when possible.</p>
</div>
</section>
<section id="help">
<span id="id12"></span><h3>help<a class="headerlink" href="#help" title="Link to this heading">¶</a></h3>
<p>The <code class="docutils literal notranslate"><span class="pre">help</span></code> value is a string containing a brief description of the argument.
When a user requests help (usually by using <code class="docutils literal notranslate"><span class="pre">-h</span></code> or <code class="docutils literal notranslate"><span class="pre">--help</span></code> at the
command line), these <code class="docutils literal notranslate"><span class="pre">help</span></code> descriptions will be displayed with each
argument.</p>
<p>The <code class="docutils literal notranslate"><span class="pre">help</span></code> strings can include various format specifiers to avoid repetition
of things like the program name or the argument <a class="reference internal" href="#default">default</a>.  The available
specifiers include the program name, <code class="docutils literal notranslate"><span class="pre">%(prog)s</span></code> and most keyword arguments to
<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>, e.g. <code class="docutils literal notranslate"><span class="pre">%(default)s</span></code>, <code class="docutils literal notranslate"><span class="pre">%(type)s</span></code>, etc.:</p>
<div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="gp">&gt;&gt;&gt; </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">&#39;frobble&#39;</span><span class="p">)</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">parser</span><span class="o">.</span><span class="n">add_argument</span><span class="p">(</span><span class="s1">&#39;bar&#39;</span><span class="p">,</span> <span class="n">nargs</span><span class="o">=</span><span class="s1">&#39;?&#39;</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="gp">... </span>                    <span class="n">help</span><span class="o">=</span><span class="s1">&#39;the bar to </span><span class="si">%(prog)s</span><span class="s1"> (default: </span><span class="si">%(default)s</span><span class="s1">)&#39;</span><span class="p">)</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">parser</span><span class="o">.</span><span class="n">print_help</span><span class="p">()</span>
<span class="go">usage: frobble [-h] [bar]</span>

<span class="go">positional arguments:</span>
<span class="go"> bar     the bar to frobble (default: 42)</span>

<span class="go">options:</span>
<span class="go"> -h, --help  show this help message and exit</span>
</pre></div>
</div>
<p>As the help string supports %-formatting, if you want a literal <code class="docutils literal notranslate"><span class="pre">%</span></code> to appear
in the help string, you must escape it as <code class="docutils literal notranslate"><span class="pre">%%</span></code>.</p>
<p><code class="xref py py-mod docutils literal notranslate"><span class="pre">argparse</span></code> supports silencing the help entry for certain options, by
setting the <code class="docutils literal notranslate"><span class="pre">help</span></code> value to <code class="docutils literal notranslate"><span class="pre">argparse.SUPPRESS</span></code>:</p>
<div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="gp">&gt;&gt;&gt; </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">&#39;frobble&#39;</span><span class="p">)</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">parser</span><span class="o">.</span><span class="n">add_argument</span><span class="p">(</span><span class="s1">&#39;--foo&#39;</span><span class="p">,</span> <span class="n">help</span><span class="o">=</span><span class="n">argparse</span><span class="o">.</span><span class="n">SUPPRESS</span><span class="p">)</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">parser</span><span class="o">.</span><span class="n">print_help</span><span class="p">()</span>
<span class="go">usage: frobble [-h]</span>

<span class="go">options:</span>
<span class="go">  -h, --help  show this help message and exit</span>
</pre></div>
</div>
</section>
<section id="metavar">
<span id="id13"></span><h3>metavar<a class="headerlink" href="#metavar" title="Link to this heading">¶</a></h3>
<p>When <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> generates help messages, it needs some way to refer
to each expected argument.  By default, <code class="xref py py-class docutils literal notranslate"><span class="pre">ArgumentParser</span></code> objects use the <a class="reference internal" href="#dest">dest</a>
value as the “name” of each object.  By default, for positional argument
actions, the <a class="reference internal" href="#dest">dest</a> value is used directly, and for optional argument actions,
the <a class="reference internal" href="#dest">dest</a> value is uppercased.  So, a single positional argument with
<code class="docutils literal notranslate"><span class="pre">dest='bar'</span></code> will be referred to as <code class="docutils literal notranslate"><span class="pre">bar</span></code>. A single
optional argument <code class="docutils literal notranslate"><span class="pre">--foo</span></code> that should be followed by a single command-line argument
will be referred to as <code class="docutils literal notranslate"><span class="pre">FOO</span></code>.  An example:</p>
<div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="gp">&gt;&gt;&gt; </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="gp">&gt;&gt;&gt; </span><span class="n">parser</span><span class="o">.</span><span class="n">add_argument</span><span class="p">(</span><span class="s1">&#39;--foo&#39;</span><span class="p">)</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">parser</span><span class="o">.</span><span class="n">add_argument</span><span class="p">(</span><span class="s1">&#39;bar&#39;</span><span class="p">)</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">parser</span><span class="o">.</span><span class="n">parse_args</span><span class="p">(</span><span class="s1">&#39;X --foo Y&#39;</span><span class="o">.</span><span class="n">split</span><span class="p">())</span>
<span class="go">Namespace(bar=&#39;X&#39;, foo=&#39;Y&#39;)</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">parser</span><span class="o">.</span><span class="n">print_help</span><span class="p">()</span>
<span class="go">usage:  [-h] [--foo FOO] bar</span>

<span class="go">positional arguments:</span>
<span class="go"> bar</span>

<span class="go">options:</span>
<span class="go"> -h, --help  show this help message and exit</span>
<span class="go"> --foo FOO</span>
</pre></div>
</div>
<p>An alternative name can be specified with <code class="docutils literal notranslate"><span class="pre">metavar</span></code>:</p>
<div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="gp">&gt;&gt;&gt; </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="gp">&gt;&gt;&gt; </span><span class="n">parser</span><span class="o">.</span><span class="n">add_argument</span><span class="p">(</span><span class="s1">&#39;--foo&#39;</span><span class="p">,</span> <span class="n">metavar</span><span class="o">=</span><span class="s1">&#39;YYY&#39;</span><span class="p">)</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">parser</span><span class="o">.</span><span class="n">add_argument</span><span class="p">(</span><span class="s1">&#39;bar&#39;</span><span class="p">,</span> <span class="n">metavar</span><span class="o">=</span><span class="s1">&#39;XXX&#39;</span><span class="p">)</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">parser</span><span class="o">.</span><span class="n">parse_args</span><span class="p">(</span><span class="s1">&#39;X --foo Y&#39;</span><span class="o">.</span><span class="n">split</span><span class="p">())</span>
<span class="go">Namespace(bar=&#39;X&#39;, foo=&#39;Y&#39;)</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">parser</span><span class="o">.</span><span class="n">print_help</span><span class="p">()</span>
<span class="go">usage:  [-h] [--foo YYY] XXX</span>

<span class="go">positional arguments:</span>
<span class="go"> XXX</span>

<span class="go">options:</span>
<span class="go"> -h, --help  show this help message and exit</span>
<span class="go"> --foo YYY</span>
</pre></div>
</div>
<p>Note that <code class="docutils literal notranslate"><span class="pre">metavar</span></code> only changes the <em>displayed</em> name - the name of the
attribute on 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> object is still determined
by the <a class="reference internal" href="#dest">dest</a> value.</p>
<p>Different values of <code class="docutils literal notranslate"><span class="pre">nargs</span></code> may cause the metavar to be used multiple times.
Providing a tuple to <code class="docutils literal notranslate"><span class="pre">metavar</span></code> specifies a different display for each of the
arguments:</p>
<div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="gp">&gt;&gt;&gt; </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">&#39;PROG&#39;</span><span class="p">)</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">parser</span><span class="o">.</span><span class="n">add_argument</span><span class="p">(</span><span class="s1">&#39;-x&#39;</span><span class="p">,</span> <span class="n">nargs</span><span class="o">=</span><span class="mi">2</span><span class="p">)</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">parser</span><span class="o">.</span><span class="n">add_argument</span><span class="p">(</span><span class="s1">&#39;--foo&#39;</span><span class="p">,</span> <span class="n">nargs</span><span class="o">=</span><span class="mi">2</span><span class="p">,</span> <span class="n">metavar</span><span class="o">=</span><span class="p">(</span><span class="s1">&#39;bar&#39;</span><span class="p">,</span> <span class="s1">&#39;baz&#39;</span><span class="p">))</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">parser</span><span class="o">.</span><span class="n">print_help</span><span class="p">()</span>
<span class="go">usage: PROG [-h] [-x X X] [--foo bar baz]</span>

<span class="go">options:</span>
<span class="go"> -h, --help     show this help message and exit</span>
<span class="go"> -x X X</span>
<span class="go"> --foo bar baz</span>
</pre></div>
</div>
</section>
<section id="dest">
<span id="id14"></span><h3>dest<a class="headerlink" href="#dest" title="Link to this heading">¶</a></h3>
<p>Most <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 add some value as an attribute of the
object returned by <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 name of this
attribute is determined by the <code class="docutils literal notranslate"><span class="pre">dest</span></code> keyword 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>.  For positional argument actions,
<code class="docutils literal notranslate"><span class="pre">dest</span></code> is normally supplied as the first argument to
<code class="xref py py-meth docutils literal notranslate"><span class="pre">add_argument()</span></code>:</p>
<div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="gp">&gt;&gt;&gt; </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="gp">&gt;&gt;&gt; </span><span class="n">parser</span><span class="o">.</span><span class="n">add_argument</span><span class="p">(</span><span class="s1">&#39;bar&#39;</span><span class="p">)</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">parser</span><span class="o">.</span><span class="n">parse_args</span><span class="p">([</span><span class="s1">&#39;XXX&#39;</span><span class="p">])</span>
<span class="go">Namespace(bar=&#39;XXX&#39;)</span>
</pre></div>
</div>
<p>For optional argument actions, the value of <code class="docutils literal notranslate"><span class="pre">dest</span></code> is normally inferred from
the option strings.  <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> generates the value of <code class="docutils literal notranslate"><span class="pre">dest</span></code> by
taking the first double-dash long option string and stripping away the initial
<code class="docutils literal notranslate"><span class="pre">-</span></code> characters.
If no double-dash long option strings were supplied, <code class="docutils literal notranslate"><span class="pre">dest</span></code> will be derived
from the first single-dash long option string by stripping the initial <code class="docutils literal notranslate"><span class="pre">-</span></code>
character.
If no long option strings were supplied, <code class="docutils literal notranslate"><span class="pre">dest</span></code> will be derived from
the first short option string by stripping the initial <code class="docutils literal notranslate"><span class="pre">-</span></code> character.  Any
internal <code class="docutils literal notranslate"><span class="pre">-</span></code> characters will be converted to <code class="docutils literal notranslate"><span class="pre">_</span></code> characters to make sure
the string is a valid attribute name.  The examples below illustrate this
behavior:</p>
<div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="gp">&gt;&gt;&gt; </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="gp">&gt;&gt;&gt; </span><span class="n">parser</span><span class="o">.</span><span class="n">add_argument</span><span class="p">(</span><span class="s1">&#39;-f&#39;</span><span class="p">,</span> <span class="s1">&#39;--foo-bar&#39;</span><span class="p">,</span> <span class="s1">&#39;--foo&#39;</span><span class="p">)</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">parser</span><span class="o">.</span><span class="n">add_argument</span><span class="p">(</span><span class="s1">&#39;-q&#39;</span><span class="p">,</span> <span class="s1">&#39;-quz&#39;</span><span class="p">)</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">parser</span><span class="o">.</span><span class="n">add_argument</span><span class="p">(</span><span class="s1">&#39;-x&#39;</span><span class="p">,</span> <span class="s1">&#39;-y&#39;</span><span class="p">)</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">parser</span><span class="o">.</span><span class="n">parse_args</span><span class="p">(</span><span class="s1">&#39;-f 1 -q 2 -x 3&#39;</span><span class="o">.</span><span class="n">split</span><span class="p">())</span>
<span class="go">Namespace(foo_bar=&#39;1&#39;, quz=&#39;2&#39;, x=&#39;3&#39;)</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">parser</span><span class="o">.</span><span class="n">parse_args</span><span class="p">(</span><span class="s1">&#39;--foo 1 -quz 2 -y 3&#39;</span><span class="o">.</span><span class="n">split</span><span class="p">())</span>
<span class="go">Namespace(foo_bar=&#39;1&#39;, quz=&#39;2&#39;, x=&#39;2&#39;)</span>
</pre></div>
</div>
<p><code class="docutils literal notranslate"><span class="pre">dest</span></code> allows a custom attribute name to be provided:</p>
<div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="gp">&gt;&gt;&gt; </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="gp">&gt;&gt;&gt; </span><span class="n">parser</span><span class="o">.</span><span class="n">add_argument</span><span class="p">(</span><span class="s1">&#39;--foo&#39;</span><span class="p">,</span> <span class="n">dest</span><span class="o">=</span><span class="s1">&#39;bar&#39;</span><span class="p">)</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">parser</span><span class="o">.</span><span class="n">parse_args</span><span class="p">(</span><span class="s1">&#39;--foo XXX&#39;</span><span class="o">.</span><span class="n">split</span><span class="p">())</span>
<span class="go">Namespace(bar=&#39;XXX&#39;)</span>
</pre></div>
</div>
<div class="versionchanged">
<p><span class="versionmodified changed">Changed in version 3.15: </span>Single-dash long option now takes precedence over short options.</p>
</div>
</section>
<section id="deprecated">
<span id="id15"></span><h3>deprecated<a class="headerlink" href="#deprecated" title="Link to this heading">¶</a></h3>
<p>During a project’s lifetime, some arguments may need to be removed from the
command line. Before removing them, you should inform
your users that the arguments are deprecated and will be removed.
The <code class="docutils literal notranslate"><span class="pre">deprecated</span></code> keyword 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>, which defaults to <code class="docutils literal notranslate"><span class="pre">False</span></code>,
specifies if the argument is deprecated and will be removed
in the future.
For arguments, if <code class="docutils literal notranslate"><span class="pre">deprecated</span></code> is <code class="docutils literal notranslate"><span class="pre">True</span></code>, then a warning will be
printed 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> when the argument is used:</p>
<div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="gp">&gt;&gt;&gt; </span><span class="kn">import</span><span class="w"> </span><span class="nn">argparse</span>
<span class="gp">&gt;&gt;&gt; </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">&#39;snake.py&#39;</span><span class="p">)</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">parser</span><span class="o">.</span><span class="n">add_argument</span><span class="p">(</span><span class="s1">&#39;--legs&#39;</span><span class="p">,</span> <span class="n">default</span><span class="o">=</span><span class="mi">0</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">deprecated</span><span class="o">=</span><span class="kc">True</span><span class="p">)</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">parser</span><span class="o">.</span><span class="n">parse_args</span><span class="p">([])</span>
<span class="go">Namespace(legs=0)</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">parser</span><span class="o">.</span><span class="n">parse_args</span><span class="p">([</span><span class="s1">&#39;--legs&#39;</span><span class="p">,</span> <span class="s1">&#39;4&#39;</span><span class="p">])</span>
<span class="go">snake.py: warning: option &#39;--legs&#39; is deprecated</span>
<span class="go">Namespace(legs=4)</span>
</pre></div>
</div>
<div class="versionadded">
<p><span class="versionmodified added">Added in version 3.13.</span></p>
</div>
</section>
<section id="action-classes">
<h3>Action classes<a class="headerlink" href="#action-classes" title="Link to this heading">¶</a></h3>
<p><code class="xref py py-class docutils literal notranslate"><span class="pre">Action</span></code> classes implement the Action API, a callable which returns a callable
which processes arguments from the command-line. Any object which follows
this API may be passed as the <code class="docutils literal notranslate"><span class="pre">action</span></code> parameter to
<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>.</p>
<dl class="py class">
<dt class="sig sig-object py" id="argparse.Action">
<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">Action</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">option_strings</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">dest</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">nargs</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">const</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">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">type</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">choices</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">required</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">False</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">help</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">metavar</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">None</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="#argparse.Action" title="Link to this definition">¶</a></dt>
<dd><p><code class="xref py py-class docutils literal notranslate"><span class="pre">Action</span></code> objects are used by 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> to represent the information
needed to parse a single argument from one or more strings from the
command line. The <code class="xref py py-class docutils literal notranslate"><span class="pre">Action</span></code> class must accept the two positional arguments
plus any keyword arguments passed to <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>
except for the <code class="docutils literal notranslate"><span class="pre">action</span></code> itself.</p>
<p>Instances of <code class="xref py py-class docutils literal notranslate"><span class="pre">Action</span></code> (or return value of any callable to the
<code class="docutils literal notranslate"><span class="pre">action</span></code> parameter) should have attributes <code class="xref py py-attr docutils literal notranslate"><span class="pre">dest</span></code>,
<code class="xref py py-attr docutils literal notranslate"><span class="pre">option_strings</span></code>, <code class="xref py py-attr docutils literal notranslate"><span class="pre">default</span></code>, <code class="xref py py-attr docutils literal notranslate"><span class="pre">type</span></code>, <code class="xref py py-attr docutils literal notranslate"><span class="pre">required</span></code>,
<code class="xref py py-attr docutils literal notranslate"><span class="pre">help</span></code>, etc. defined. The easiest way to ensure these attributes
are defined is to call <code class="xref py py-meth docutils literal notranslate"><span class="pre">Action.__init__()</span></code>.</p>
<dl class="py method">
<dt class="sig sig-object py" id="argparse.Action.__call__">
<span class="sig-name descname"><span class="pre">__call__</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">parser</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">namespace</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">values</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">option_string</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">None</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="#argparse.Action.__call__" title="Link to this definition">¶</a></dt>
<dd><p><code class="xref py py-class docutils literal notranslate"><span class="pre">Action</span></code> instances should be callable, so subclasses must override the
<code class="xref py py-meth docutils literal notranslate"><span class="pre">__call__()</span></code> method, which should accept four parameters:</p>
<ul class="simple">
<li><p><em>parser</em> - 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> object which contains this action.</p></li>
<li><p><em>namespace</em> - The <a class="reference internal" href="#argparse.Namespace" title="argparse.Namespace"><code class="xref py py-class docutils literal notranslate"><span class="pre">Namespace</span></code></a> object that will be returned by
<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>.  Most actions add an attribute to this
object using <a class="reference internal" href="functions.html#setattr" title="setattr"><code class="xref py py-func docutils literal notranslate"><span class="pre">setattr()</span></code></a>.</p></li>
<li><p><em>values</em> - The associated command-line arguments, with any type conversions
applied.  Type conversions are specified with the <a class="reference internal" href="#type">type</a> keyword argument to
<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>.</p></li>
<li><p><em>option_string</em> - The option string that was used to invoke this action.
The <code class="docutils literal notranslate"><span class="pre">option_string</span></code> argument is optional, and will be absent if the action
is associated with a positional argument.</p></li>
</ul>
<p>The <code class="xref py py-meth docutils literal notranslate"><span class="pre">__call__()</span></code> method may perform arbitrary actions, but will typically set
attributes on the <code class="docutils literal notranslate"><span class="pre">namespace</span></code> based on <code class="docutils literal notranslate"><span class="pre">dest</span></code> and <code class="docutils literal notranslate"><span class="pre">values</span></code>.</p>
</dd></dl>

<dl class="py method">
<dt class="sig sig-object py" id="argparse.Action.format_usage">
<span class="sig-name descname"><span class="pre">format_usage</span></span><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#argparse.Action.format_usage" title="Link to this definition">¶</a></dt>
<dd><p><code class="xref py py-class docutils literal notranslate"><span class="pre">Action</span></code> subclasses can define a <code class="xref py py-meth docutils literal notranslate"><span class="pre">format_usage()</span></code> method that takes no argument
and return a string which will be used when printing the usage of the program.
If such method is not provided, a sensible default will be used.</p>
</dd></dl>

</dd></dl>

<dl class="py class">
<dt class="sig sig-object py" id="argparse.BooleanOptionalAction">
<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">BooleanOptionalAction</span></span><a class="headerlink" href="#argparse.BooleanOptionalAction" title="Link to this definition">¶</a></dt>
<dd><p>A subclass of <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> for handling boolean flags with positive
and negative options. Adding a single argument such as <code class="docutils literal notranslate"><span class="pre">--foo</span></code> automatically
creates both <code class="docutils literal notranslate"><span class="pre">--foo</span></code> and <code class="docutils literal notranslate"><span class="pre">--no-foo</span></code> options, storing <code class="docutils literal notranslate"><span class="pre">True</span></code> and <code class="docutils literal notranslate"><span class="pre">False</span></code>
respectively:</p>
<div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="gp">&gt;&gt;&gt; </span><span class="kn">import</span><span class="w"> </span><span class="nn">argparse</span>
<span class="gp">&gt;&gt;&gt; </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="gp">&gt;&gt;&gt; </span><span class="n">parser</span><span class="o">.</span><span class="n">add_argument</span><span class="p">(</span><span class="s1">&#39;--foo&#39;</span><span class="p">,</span> <span class="n">action</span><span class="o">=</span><span class="n">argparse</span><span class="o">.</span><span class="n">BooleanOptionalAction</span><span class="p">)</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">parser</span><span class="o">.</span><span class="n">parse_args</span><span class="p">([</span><span class="s1">&#39;--no-foo&#39;</span><span class="p">])</span>
<span class="go">Namespace(foo=False)</span>
</pre></div>
</div>
<p>Single-dash long options are also supported.
For example, negative option <code class="docutils literal notranslate"><span class="pre">-nofoo</span></code> is automatically added for
positive option <code class="docutils literal notranslate"><span class="pre">-foo</span></code>.
But no additional options are added for short options such as <code class="docutils literal notranslate"><span class="pre">-f</span></code>.</p>
<div class="versionadded">
<p><span class="versionmodified added">Added in version 3.9.</span></p>
</div>
<div class="versionchanged">
<p><span class="versionmodified changed">Changed in version 3.15: </span>Added support for single-dash options.</p>
<p>Added support for alternate <a class="reference internal" href="#prefix-chars">prefix_chars</a>.</p>
</div>
</dd></dl>

</section>
</section>
<section id="the-parse-args-method">
<h2>The parse_args() method<a class="headerlink" href="#the-parse-args-method" title="Link to this heading">¶</a></h2>
<dl class="py method">
<dt class="sig sig-object py" id="argparse.ArgumentParser.parse_args">
<span class="sig-prename descclassname"><span class="pre">ArgumentParser.</span></span><span class="sig-name descname"><span class="pre">parse_args</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">args</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">namespace</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">None</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="#argparse.ArgumentParser.parse_args" title="Link to this definition">¶</a></dt>
<dd><p>Convert argument strings to objects and assign them as attributes of the
namespace.  Return the populated namespace.</p>
<p>Previous calls to <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> determine exactly what objects are
created and how they are assigned. See the documentation for
<code class="xref py py-meth docutils literal notranslate"><span class="pre">add_argument()</span></code> for details.</p>
<ul class="simple">
<li><p><a class="reference internal" href="#args">args</a> - List of strings to parse.  The default is taken from
<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>.</p></li>
<li><p><a class="reference internal" href="#namespace">namespace</a> - An object to take the attributes.  The default is a new empty
<a class="reference internal" href="#argparse.Namespace" title="argparse.Namespace"><code class="xref py py-class docutils literal notranslate"><span class="pre">Namespace</span></code></a> object.</p></li>
</ul>
</dd></dl>

<section id="option-value-syntax">
<h3>Option value syntax<a class="headerlink" href="#option-value-syntax" title="Link to this heading">¶</a></h3>
<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">parse_args()</span></code></a> method supports several ways of
specifying the value of an option (if it takes one).  In the simplest case, the
option and its value are passed as two separate arguments:</p>
<div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="gp">&gt;&gt;&gt; </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">&#39;PROG&#39;</span><span class="p">)</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">parser</span><span class="o">.</span><span class="n">add_argument</span><span class="p">(</span><span class="s1">&#39;-x&#39;</span><span class="p">)</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">parser</span><span class="o">.</span><span class="n">add_argument</span><span class="p">(</span><span class="s1">&#39;--foo&#39;</span><span class="p">)</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">parser</span><span class="o">.</span><span class="n">parse_args</span><span class="p">([</span><span class="s1">&#39;-x&#39;</span><span class="p">,</span> <span class="s1">&#39;X&#39;</span><span class="p">])</span>
<span class="go">Namespace(foo=None, x=&#39;X&#39;)</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">parser</span><span class="o">.</span><span class="n">parse_args</span><span class="p">([</span><span class="s1">&#39;--foo&#39;</span><span class="p">,</span> <span class="s1">&#39;FOO&#39;</span><span class="p">])</span>
<span class="go">Namespace(foo=&#39;FOO&#39;, x=None)</span>
</pre></div>
</div>
<p>For long options (options with names longer than a single character), the option
and value can also be passed as a single command-line argument, using <code class="docutils literal notranslate"><span class="pre">=</span></code> to
separate them:</p>
<div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="gp">&gt;&gt;&gt; </span><span class="n">parser</span><span class="o">.</span><span class="n">parse_args</span><span class="p">([</span><span class="s1">&#39;--foo=FOO&#39;</span><span class="p">])</span>
<span class="go">Namespace(foo=&#39;FOO&#39;, x=None)</span>
</pre></div>
</div>
<p>For short options (options only one character long), the option and its value
can be concatenated:</p>
<div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="gp">&gt;&gt;&gt; </span><span class="n">parser</span><span class="o">.</span><span class="n">parse_args</span><span class="p">([</span><span class="s1">&#39;-xX&#39;</span><span class="p">])</span>
<span class="go">Namespace(foo=None, x=&#39;X&#39;)</span>
</pre></div>
</div>
<p>Several short options can be joined together, using only a single <code class="docutils literal notranslate"><span class="pre">-</span></code> prefix,
as long as only the last option (or none of them) requires a value:</p>
<div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="gp">&gt;&gt;&gt; </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">&#39;PROG&#39;</span><span class="p">)</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">parser</span><span class="o">.</span><span class="n">add_argument</span><span class="p">(</span><span class="s1">&#39;-x&#39;</span><span class="p">,</span> <span class="n">action</span><span class="o">=</span><span class="s1">&#39;store_true&#39;</span><span class="p">)</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">parser</span><span class="o">.</span><span class="n">add_argument</span><span class="p">(</span><span class="s1">&#39;-y&#39;</span><span class="p">,</span> <span class="n">action</span><span class="o">=</span><span class="s1">&#39;store_true&#39;</span><span class="p">)</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">parser</span><span class="o">.</span><span class="n">add_argument</span><span class="p">(</span><span class="s1">&#39;-z&#39;</span><span class="p">)</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">parser</span><span class="o">.</span><span class="n">parse_args</span><span class="p">([</span><span class="s1">&#39;-xyzZ&#39;</span><span class="p">])</span>
<span class="go">Namespace(x=True, y=True, z=&#39;Z&#39;)</span>
</pre></div>
</div>
</section>
<section id="invalid-arguments">
<h3>Invalid arguments<a class="headerlink" href="#invalid-arguments" title="Link to this heading">¶</a></h3>
<p>While parsing the command line, <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> checks for a
variety of errors, including ambiguous options, invalid types, invalid options,
wrong number of positional arguments, etc.  When it encounters such an error,
it exits and prints the error along with a usage message:</p>
<div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="gp">&gt;&gt;&gt; </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">&#39;PROG&#39;</span><span class="p">)</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">parser</span><span class="o">.</span><span class="n">add_argument</span><span class="p">(</span><span class="s1">&#39;--foo&#39;</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="gp">&gt;&gt;&gt; </span><span class="n">parser</span><span class="o">.</span><span class="n">add_argument</span><span class="p">(</span><span class="s1">&#39;bar&#39;</span><span class="p">,</span> <span class="n">nargs</span><span class="o">=</span><span class="s1">&#39;?&#39;</span><span class="p">)</span>

<span class="gp">&gt;&gt;&gt; </span><span class="c1"># invalid type</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">parser</span><span class="o">.</span><span class="n">parse_args</span><span class="p">([</span><span class="s1">&#39;--foo&#39;</span><span class="p">,</span> <span class="s1">&#39;spam&#39;</span><span class="p">])</span>
<span class="go">usage: PROG [-h] [--foo FOO] [bar]</span>
<span class="go">PROG: error: argument --foo: invalid int value: &#39;spam&#39;</span>

<span class="gp">&gt;&gt;&gt; </span><span class="c1"># invalid option</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">parser</span><span class="o">.</span><span class="n">parse_args</span><span class="p">([</span><span class="s1">&#39;--bar&#39;</span><span class="p">])</span>
<span class="go">usage: PROG [-h] [--foo FOO] [bar]</span>
<span class="go">PROG: error: no such option: --bar</span>

<span class="gp">&gt;&gt;&gt; </span><span class="c1"># wrong number of arguments</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">parser</span><span class="o">.</span><span class="n">parse_args</span><span class="p">([</span><span class="s1">&#39;spam&#39;</span><span class="p">,</span> <span class="s1">&#39;badger&#39;</span><span class="p">])</span>
<span class="go">usage: PROG [-h] [--foo FOO] [bar]</span>
<span class="go">PROG: error: extra arguments found: badger</span>
</pre></div>
</div>
</section>
<section id="arguments-containing">
<h3>Arguments containing <code class="docutils literal notranslate"><span class="pre">-</span></code><a class="headerlink" href="#arguments-containing" title="Link to this heading">¶</a></h3>
<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">parse_args()</span></code></a> method attempts to give errors whenever
the user has clearly made a mistake, but some situations are inherently
ambiguous.  For example, the command-line argument <code class="docutils literal notranslate"><span class="pre">-1</span></code> could either be an
attempt to specify an option or an attempt to provide a positional argument.
The <code class="xref py py-meth docutils literal notranslate"><span class="pre">parse_args()</span></code> method is cautious here: positional
arguments may only begin with <code class="docutils literal notranslate"><span class="pre">-</span></code> if they look like negative numbers and
there are no options in the parser that look like negative numbers:</p>
<div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="gp">&gt;&gt;&gt; </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">&#39;PROG&#39;</span><span class="p">)</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">parser</span><span class="o">.</span><span class="n">add_argument</span><span class="p">(</span><span class="s1">&#39;-x&#39;</span><span class="p">)</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">parser</span><span class="o">.</span><span class="n">add_argument</span><span class="p">(</span><span class="s1">&#39;foo&#39;</span><span class="p">,</span> <span class="n">nargs</span><span class="o">=</span><span class="s1">&#39;?&#39;</span><span class="p">)</span>

<span class="gp">&gt;&gt;&gt; </span><span class="c1"># no negative number options, so -1 is a positional argument</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">parser</span><span class="o">.</span><span class="n">parse_args</span><span class="p">([</span><span class="s1">&#39;-x&#39;</span><span class="p">,</span> <span class="s1">&#39;-1&#39;</span><span class="p">])</span>
<span class="go">Namespace(foo=None, x=&#39;-1&#39;)</span>

<span class="gp">&gt;&gt;&gt; </span><span class="c1"># no negative number options, so -1 and -5 are positional arguments</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">parser</span><span class="o">.</span><span class="n">parse_args</span><span class="p">([</span><span class="s1">&#39;-x&#39;</span><span class="p">,</span> <span class="s1">&#39;-1&#39;</span><span class="p">,</span> <span class="s1">&#39;-5&#39;</span><span class="p">])</span>
<span class="go">Namespace(foo=&#39;-5&#39;, x=&#39;-1&#39;)</span>

<span class="gp">&gt;&gt;&gt; </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">&#39;PROG&#39;</span><span class="p">)</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">parser</span><span class="o">.</span><span class="n">add_argument</span><span class="p">(</span><span class="s1">&#39;-1&#39;</span><span class="p">,</span> <span class="n">dest</span><span class="o">=</span><span class="s1">&#39;one&#39;</span><span class="p">)</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">parser</span><span class="o">.</span><span class="n">add_argument</span><span class="p">(</span><span class="s1">&#39;foo&#39;</span><span class="p">,</span> <span class="n">nargs</span><span class="o">=</span><span class="s1">&#39;?&#39;</span><span class="p">)</span>

<span class="gp">&gt;&gt;&gt; </span><span class="c1"># negative number options present, so -1 is an option</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">parser</span><span class="o">.</span><span class="n">parse_args</span><span class="p">([</span><span class="s1">&#39;-1&#39;</span><span class="p">,</span> <span class="s1">&#39;X&#39;</span><span class="p">])</span>
<span class="go">Namespace(foo=None, one=&#39;X&#39;)</span>

<span class="gp">&gt;&gt;&gt; </span><span class="c1"># negative number options present, so -2 is an option</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">parser</span><span class="o">.</span><span class="n">parse_args</span><span class="p">([</span><span class="s1">&#39;-2&#39;</span><span class="p">])</span>
<span class="go">usage: PROG [-h] [-1 ONE] [foo]</span>
<span class="go">PROG: error: no such option: -2</span>

<span class="gp">&gt;&gt;&gt; </span><span class="c1"># negative number options present, so both -1s are options</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">parser</span><span class="o">.</span><span class="n">parse_args</span><span class="p">([</span><span class="s1">&#39;-1&#39;</span><span class="p">,</span> <span class="s1">&#39;-1&#39;</span><span class="p">])</span>
<span class="go">usage: PROG [-h] [-1 ONE] [foo]</span>
<span class="go">PROG: error: argument -1: expected one argument</span>
</pre></div>
</div>
<p>If you have positional arguments that must begin with <code class="docutils literal notranslate"><span class="pre">-</span></code> and don’t look
like negative numbers, you can insert the pseudo-argument <code class="docutils literal notranslate"><span class="pre">'--'</span></code> which tells
<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> that everything after that is a positional
argument:</p>
<div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="gp">&gt;&gt;&gt; </span><span class="n">parser</span><span class="o">.</span><span class="n">parse_args</span><span class="p">([</span><span class="s1">&#39;--&#39;</span><span class="p">,</span> <span class="s1">&#39;-f&#39;</span><span class="p">])</span>
<span class="go">Namespace(foo=&#39;-f&#39;, one=None)</span>
</pre></div>
</div>
<p>See also <a class="reference internal" href="../howto/argparse.html#specifying-ambiguous-arguments"><span class="std std-ref">the argparse howto on ambiguous arguments</span></a>
for more details.</p>
</section>
<section id="argument-abbreviations-prefix-matching">
<span id="prefix-matching"></span><h3>Argument abbreviations (prefix matching)<a class="headerlink" href="#argument-abbreviations-prefix-matching" title="Link to this heading">¶</a></h3>
<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">parse_args()</span></code></a> method <a class="reference internal" href="#allow-abbrev"><span class="std std-ref">by default</span></a>
allows long options to be abbreviated to a prefix, if the abbreviation is
unambiguous (the prefix matches a unique option):</p>
<div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="gp">&gt;&gt;&gt; </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">&#39;PROG&#39;</span><span class="p">)</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">parser</span><span class="o">.</span><span class="n">add_argument</span><span class="p">(</span><span class="s1">&#39;-bacon&#39;</span><span class="p">)</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">parser</span><span class="o">.</span><span class="n">add_argument</span><span class="p">(</span><span class="s1">&#39;-badger&#39;</span><span class="p">)</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">parser</span><span class="o">.</span><span class="n">parse_args</span><span class="p">(</span><span class="s1">&#39;-bac MMM&#39;</span><span class="o">.</span><span class="n">split</span><span class="p">())</span>
<span class="go">Namespace(bacon=&#39;MMM&#39;, badger=None)</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">parser</span><span class="o">.</span><span class="n">parse_args</span><span class="p">(</span><span class="s1">&#39;-bad WOOD&#39;</span><span class="o">.</span><span class="n">split</span><span class="p">())</span>
<span class="go">Namespace(bacon=None, badger=&#39;WOOD&#39;)</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">parser</span><span class="o">.</span><span class="n">parse_args</span><span class="p">(</span><span class="s1">&#39;-ba BA&#39;</span><span class="o">.</span><span class="n">split</span><span class="p">())</span>
<span class="go">usage: PROG [-h] [-bacon BACON] [-badger BADGER]</span>
<span class="go">PROG: error: ambiguous option: -ba could match -badger, -bacon</span>
</pre></div>
</div>
<p>An error is produced for arguments that could produce more than one options.
This feature can be disabled by setting <a class="reference internal" href="#allow-abbrev"><span class="std std-ref">allow_abbrev</span></a> to <code class="docutils literal notranslate"><span class="pre">False</span></code>.</p>
</section>
<section id="beyond-sys-argv">
<span id="args"></span><h3>Beyond <code class="docutils literal notranslate"><span class="pre">sys.argv</span></code><a class="headerlink" href="#beyond-sys-argv" title="Link to this heading">¶</a></h3>
<p>Sometimes it may be useful to have 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> parse arguments other than those
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>.  This can be accomplished by passing a list of strings to
<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>.  This is useful for testing at the
interactive prompt:</p>
<div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="gp">&gt;&gt;&gt; </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="gp">&gt;&gt;&gt; </span><span class="n">parser</span><span class="o">.</span><span class="n">add_argument</span><span class="p">(</span>
<span class="gp">... </span>    <span class="s1">&#39;integers&#39;</span><span class="p">,</span> <span class="n">metavar</span><span class="o">=</span><span class="s1">&#39;int&#39;</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">choices</span><span class="o">=</span><span class="nb">range</span><span class="p">(</span><span class="mi">10</span><span class="p">),</span>
<span class="gp">... </span>    <span class="n">nargs</span><span class="o">=</span><span class="s1">&#39;+&#39;</span><span class="p">,</span> <span class="n">help</span><span class="o">=</span><span class="s1">&#39;an integer in the range 0..9&#39;</span><span class="p">)</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">parser</span><span class="o">.</span><span class="n">add_argument</span><span class="p">(</span>
<span class="gp">... </span>    <span class="s1">&#39;--sum&#39;</span><span class="p">,</span> <span class="n">dest</span><span class="o">=</span><span class="s1">&#39;accumulate&#39;</span><span class="p">,</span> <span class="n">action</span><span class="o">=</span><span class="s1">&#39;store_const&#39;</span><span class="p">,</span> <span class="n">const</span><span class="o">=</span><span class="nb">sum</span><span class="p">,</span>
<span class="gp">... </span>    <span class="n">default</span><span class="o">=</span><span class="nb">max</span><span class="p">,</span> <span class="n">help</span><span class="o">=</span><span class="s1">&#39;sum the integers (default: find the max)&#39;</span><span class="p">)</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">parser</span><span class="o">.</span><span class="n">parse_args</span><span class="p">([</span><span class="s1">&#39;1&#39;</span><span class="p">,</span> <span class="s1">&#39;2&#39;</span><span class="p">,</span> <span class="s1">&#39;3&#39;</span><span class="p">,</span> <span class="s1">&#39;4&#39;</span><span class="p">])</span>
<span class="go">Namespace(accumulate=&lt;built-in function max&gt;, integers=[1, 2, 3, 4])</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">parser</span><span class="o">.</span><span class="n">parse_args</span><span class="p">([</span><span class="s1">&#39;1&#39;</span><span class="p">,</span> <span class="s1">&#39;2&#39;</span><span class="p">,</span> <span class="s1">&#39;3&#39;</span><span class="p">,</span> <span class="s1">&#39;4&#39;</span><span class="p">,</span> <span class="s1">&#39;--sum&#39;</span><span class="p">])</span>
<span class="go">Namespace(accumulate=&lt;built-in function sum&gt;, integers=[1, 2, 3, 4])</span>
</pre></div>
</div>
</section>
<section id="the-namespace-object">
<span id="namespace"></span><h3>The Namespace object<a class="headerlink" href="#the-namespace-object" title="Link to this heading">¶</a></h3>
<dl class="py class">
<dt class="sig sig-object py" id="argparse.Namespace">
<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">Namespace</span></span><a class="headerlink" href="#argparse.Namespace" title="Link to this definition">¶</a></dt>
<dd><p>Simple class used by default by <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> to create
an object holding attributes and return it.</p>
<p>This class is deliberately simple, just an <a class="reference internal" href="functions.html#object" title="object"><code class="xref py py-class docutils literal notranslate"><span class="pre">object</span></code></a> subclass with a
readable string representation. If you prefer to have dict-like view of the
attributes, you can use the standard Python idiom, <a class="reference internal" href="functions.html#vars" title="vars"><code class="xref py py-func docutils literal notranslate"><span class="pre">vars()</span></code></a>:</p>
<div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="gp">&gt;&gt;&gt; </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="gp">&gt;&gt;&gt; </span><span class="n">parser</span><span class="o">.</span><span class="n">add_argument</span><span class="p">(</span><span class="s1">&#39;--foo&#39;</span><span class="p">)</span>
<span class="gp">&gt;&gt;&gt; </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">&#39;--foo&#39;</span><span class="p">,</span> <span class="s1">&#39;BAR&#39;</span><span class="p">])</span>
<span class="gp">&gt;&gt;&gt; </span><span class="nb">vars</span><span class="p">(</span><span class="n">args</span><span class="p">)</span>
<span class="go">{&#39;foo&#39;: &#39;BAR&#39;}</span>
</pre></div>
</div>
<p>It may also be useful to have 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> assign attributes to an
already existing object, rather than a new <code class="xref py py-class docutils literal notranslate"><span class="pre">Namespace</span></code> object.  This can
be achieved by specifying the <code class="docutils literal notranslate"><span class="pre">namespace=</span></code> keyword argument:</p>
<div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="gp">&gt;&gt;&gt; </span><span class="k">class</span><span class="w"> </span><span class="nc">C</span><span class="p">:</span>
<span class="gp">... </span>    <span class="k">pass</span>
<span class="gp">...</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">c</span> <span class="o">=</span> <span class="n">C</span><span class="p">()</span>
<span class="gp">&gt;&gt;&gt; </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="gp">&gt;&gt;&gt; </span><span class="n">parser</span><span class="o">.</span><span class="n">add_argument</span><span class="p">(</span><span class="s1">&#39;--foo&#39;</span><span class="p">)</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">parser</span><span class="o">.</span><span class="n">parse_args</span><span class="p">(</span><span class="n">args</span><span class="o">=</span><span class="p">[</span><span class="s1">&#39;--foo&#39;</span><span class="p">,</span> <span class="s1">&#39;BAR&#39;</span><span class="p">],</span> <span class="n">namespace</span><span class="o">=</span><span class="n">c</span><span class="p">)</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">c</span><span class="o">.</span><span class="n">foo</span>
<span class="go">&#39;BAR&#39;</span>
</pre></div>
</div>
</dd></dl>

</section>
</section>
<section id="other-utilities">
<h2>Other utilities<a class="headerlink" href="#other-utilities" title="Link to this heading">¶</a></h2>
<section id="subcommands">
<h3>Subcommands<a class="headerlink" href="#subcommands" title="Link to this heading">¶</a></h3>
<dl class="py method">
<dt class="sig sig-object py" id="argparse.ArgumentParser.add_subparsers">
<span class="sig-prename descclassname"><span class="pre">ArgumentParser.</span></span><span class="sig-name descname"><span class="pre">add_subparsers</span></span><span class="sig-paren">(</span><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">title</span></span></em><span class="optional">]</span><span class="optional">[</span>, <em class="sig-param"><span class="n"><span class="pre">description</span></span></em><span class="optional">]</span><span class="optional">[</span>, <em class="sig-param"><span class="n"><span class="pre">prog</span></span></em><span class="optional">]</span><span class="optional">[</span>, <em class="sig-param"><span class="n"><span class="pre">parser_class</span></span></em><span class="optional">]</span><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">dest</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="sig-paren">)</span><a class="headerlink" href="#argparse.ArgumentParser.add_subparsers" title="Link to this definition">¶</a></dt>
<dd><p>Many programs split up their functionality into a number of subcommands,
for example, the <code class="docutils literal notranslate"><span class="pre">svn</span></code> program can invoke subcommands like <code class="docutils literal notranslate"><span class="pre">svn</span>
<span class="pre">checkout</span></code>, <code class="docutils literal notranslate"><span class="pre">svn</span> <span class="pre">update</span></code>, and <code class="docutils literal notranslate"><span class="pre">svn</span> <span class="pre">commit</span></code>.  Splitting up functionality
this way can be a particularly good idea when a program performs several
different functions which require different kinds of command-line arguments.
<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> supports the creation of such subcommands with the
<code class="xref py py-meth docutils literal notranslate"><span class="pre">add_subparsers()</span></code> method.  The <code class="xref py py-meth docutils literal notranslate"><span class="pre">add_subparsers()</span></code> method is normally
called with no arguments and returns a special action object.  This object
has a single method, <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>, which takes a
command name and any <code class="xref py py-class docutils literal notranslate"><span class="pre">ArgumentParser</span></code> constructor arguments, and
returns an <code class="xref py py-class docutils literal notranslate"><span class="pre">ArgumentParser</span></code> object that can be modified as usual.</p>
<p>Description of parameters:</p>
<ul class="simple">
<li><p><em>title</em> - title for the sub-parser group in help output; by default
“subcommands” if description is provided, otherwise uses title for
positional arguments</p></li>
<li><p><em>description</em> - description for the sub-parser group in help output, by
default <code class="docutils literal notranslate"><span class="pre">None</span></code></p></li>
<li><p><em>prog</em> - usage information that will be displayed with subcommand help,
by default the name of the program and any positional arguments before the
subparser argument</p></li>
<li><p><em>parser_class</em> - class which will be used to create sub-parser instances, by
default the class of the current parser (e.g. <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></li>
<li><p><a class="reference internal" href="#action">action</a> - the basic type of action to be taken when this argument is
encountered at the command line</p></li>
<li><p><a class="reference internal" href="#dest">dest</a> - name of the attribute under which subcommand name will be
stored; by default <code class="docutils literal notranslate"><span class="pre">None</span></code> and no value is stored</p></li>
<li><p><a class="reference internal" href="#required">required</a> - Whether or not a subcommand must be provided, by default
<code class="docutils literal notranslate"><span class="pre">False</span></code> (added in 3.7)</p></li>
<li><p><a class="reference internal" href="#help">help</a> - help for sub-parser group in help output, by default <code class="docutils literal notranslate"><span class="pre">None</span></code></p></li>
<li><p><a class="reference internal" href="#metavar">metavar</a> - string presenting available subcommands in help; by default it
is <code class="docutils literal notranslate"><span class="pre">None</span></code> and presents subcommands in form {cmd1, cmd2, ..}</p></li>
</ul>
<p>Some example usage:</p>
<div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="gp">&gt;&gt;&gt; </span><span class="c1"># create the top-level parser</span>
<span class="gp">&gt;&gt;&gt; </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">&#39;PROG&#39;</span><span class="p">)</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">parser</span><span class="o">.</span><span class="n">add_argument</span><span class="p">(</span><span class="s1">&#39;--foo&#39;</span><span class="p">,</span> <span class="n">action</span><span class="o">=</span><span class="s1">&#39;store_true&#39;</span><span class="p">,</span> <span class="n">help</span><span class="o">=</span><span class="s1">&#39;foo help&#39;</span><span class="p">)</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">subparsers</span> <span class="o">=</span> <span class="n">parser</span><span class="o">.</span><span class="n">add_subparsers</span><span class="p">(</span><span class="n">help</span><span class="o">=</span><span class="s1">&#39;subcommand help&#39;</span><span class="p">)</span>
<span class="gp">&gt;&gt;&gt;</span>
<span class="gp">&gt;&gt;&gt; </span><span class="c1"># create the parser for the &quot;a&quot; command</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">parser_a</span> <span class="o">=</span> <span class="n">subparsers</span><span class="o">.</span><span class="n">add_parser</span><span class="p">(</span><span class="s1">&#39;a&#39;</span><span class="p">,</span> <span class="n">help</span><span class="o">=</span><span class="s1">&#39;a help&#39;</span><span class="p">)</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">parser_a</span><span class="o">.</span><span class="n">add_argument</span><span class="p">(</span><span class="s1">&#39;bar&#39;</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">help</span><span class="o">=</span><span class="s1">&#39;bar help&#39;</span><span class="p">)</span>
<span class="gp">&gt;&gt;&gt;</span>
<span class="gp">&gt;&gt;&gt; </span><span class="c1"># create the parser for the &quot;b&quot; command</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">parser_b</span> <span class="o">=</span> <span class="n">subparsers</span><span class="o">.</span><span class="n">add_parser</span><span class="p">(</span><span class="s1">&#39;b&#39;</span><span class="p">,</span> <span class="n">help</span><span class="o">=</span><span class="s1">&#39;b help&#39;</span><span class="p">)</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">parser_b</span><span class="o">.</span><span class="n">add_argument</span><span class="p">(</span><span class="s1">&#39;--baz&#39;</span><span class="p">,</span> <span class="n">choices</span><span class="o">=</span><span class="p">(</span><span class="s1">&#39;X&#39;</span><span class="p">,</span> <span class="s1">&#39;Y&#39;</span><span class="p">,</span> <span class="s1">&#39;Z&#39;</span><span class="p">),</span> <span class="n">help</span><span class="o">=</span><span class="s1">&#39;baz help&#39;</span><span class="p">)</span>
<span class="gp">&gt;&gt;&gt;</span>
<span class="gp">&gt;&gt;&gt; </span><span class="c1"># parse some argument lists</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">parser</span><span class="o">.</span><span class="n">parse_args</span><span class="p">([</span><span class="s1">&#39;a&#39;</span><span class="p">,</span> <span class="s1">&#39;12&#39;</span><span class="p">])</span>
<span class="go">Namespace(bar=12, foo=False)</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">parser</span><span class="o">.</span><span class="n">parse_args</span><span class="p">([</span><span class="s1">&#39;--foo&#39;</span><span class="p">,</span> <span class="s1">&#39;b&#39;</span><span class="p">,</span> <span class="s1">&#39;--baz&#39;</span><span class="p">,</span> <span class="s1">&#39;Z&#39;</span><span class="p">])</span>
<span class="go">Namespace(baz=&#39;Z&#39;, foo=True)</span>
</pre></div>
</div>
<p>Note that the object returned by <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> will only contain
attributes for the main parser and the subparser that was selected by the
command line (and not any other subparsers).  So in the example above, when
the <code class="docutils literal notranslate"><span class="pre">a</span></code> command is specified, only the <code class="docutils literal notranslate"><span class="pre">foo</span></code> and <code class="docutils literal notranslate"><span class="pre">bar</span></code> attributes are
present, and when the <code class="docutils literal notranslate"><span class="pre">b</span></code> command is specified, only the <code class="docutils literal notranslate"><span class="pre">foo</span></code> and
<code class="docutils literal notranslate"><span class="pre">baz</span></code> attributes are present.</p>
<p>Similarly, when a help message is requested from a subparser, only the help
for that particular parser will be printed.  The help message will not
include parent parser or sibling parser messages.  (A help message for each
subparser command, however, can be given by supplying the <code class="docutils literal notranslate"><span class="pre">help=</span></code> argument
to <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> as above.)</p>
<div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="gp">&gt;&gt;&gt; </span><span class="n">parser</span><span class="o">.</span><span class="n">parse_args</span><span class="p">([</span><span class="s1">&#39;--help&#39;</span><span class="p">])</span>
<span class="go">usage: PROG [-h] [--foo] {a,b} ...</span>

<span class="go">positional arguments:</span>
<span class="go">  {a,b}   subcommand help</span>
<span class="go">    a     a help</span>
<span class="go">    b     b help</span>

<span class="go">options:</span>
<span class="go">  -h, --help  show this help message and exit</span>
<span class="go">  --foo   foo help</span>

<span class="gp">&gt;&gt;&gt; </span><span class="n">parser</span><span class="o">.</span><span class="n">parse_args</span><span class="p">([</span><span class="s1">&#39;a&#39;</span><span class="p">,</span> <span class="s1">&#39;--help&#39;</span><span class="p">])</span>
<span class="go">usage: PROG a [-h] bar</span>

<span class="go">positional arguments:</span>
<span class="go">  bar     bar help</span>

<span class="go">options:</span>
<span class="go">  -h, --help  show this help message and exit</span>

<span class="gp">&gt;&gt;&gt; </span><span class="n">parser</span><span class="o">.</span><span class="n">parse_args</span><span class="p">([</span><span class="s1">&#39;b&#39;</span><span class="p">,</span> <span class="s1">&#39;--help&#39;</span><span class="p">])</span>
<span class="go">usage: PROG b [-h] [--baz {X,Y,Z}]</span>

<span class="go">options:</span>
<span class="go">  -h, --help     show this help message and exit</span>
<span class="go">  --baz {X,Y,Z}  baz help</span>
</pre></div>
</div>
<p>The <code class="xref py py-meth docutils literal notranslate"><span class="pre">add_subparsers()</span></code> method also supports <code class="docutils literal notranslate"><span class="pre">title</span></code> and <code class="docutils literal notranslate"><span class="pre">description</span></code>
keyword arguments.  When either is present, the subparser’s commands will
appear in their own group in the help output.  For example:</p>
<div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="gp">&gt;&gt;&gt; </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="gp">&gt;&gt;&gt; </span><span class="n">subparsers</span> <span class="o">=</span> <span class="n">parser</span><span class="o">.</span><span class="n">add_subparsers</span><span class="p">(</span><span class="n">title</span><span class="o">=</span><span class="s1">&#39;subcommands&#39;</span><span class="p">,</span>
<span class="gp">... </span>                                   <span class="n">description</span><span class="o">=</span><span class="s1">&#39;valid subcommands&#39;</span><span class="p">,</span>
<span class="gp">... </span>                                   <span class="n">help</span><span class="o">=</span><span class="s1">&#39;additional help&#39;</span><span class="p">)</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">subparsers</span><span class="o">.</span><span class="n">add_parser</span><span class="p">(</span><span class="s1">&#39;foo&#39;</span><span class="p">)</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">subparsers</span><span class="o">.</span><span class="n">add_parser</span><span class="p">(</span><span class="s1">&#39;bar&#39;</span><span class="p">)</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">parser</span><span class="o">.</span><span class="n">parse_args</span><span class="p">([</span><span class="s1">&#39;-h&#39;</span><span class="p">])</span>
<span class="go">usage:  [-h] {foo,bar} ...</span>

<span class="go">options:</span>
<span class="go">  -h, --help  show this help message and exit</span>

<span class="go">subcommands:</span>
<span class="go">  valid subcommands</span>

<span class="go">  {foo,bar}   additional help</span>
</pre></div>
</div>
<p>One particularly effective way of handling subcommands is to combine the use
of the <code class="xref py py-meth docutils literal notranslate"><span class="pre">add_subparsers()</span></code> method with calls to <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> so
that each subparser knows which Python function it should execute.  For
example:</p>
<div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="gp">&gt;&gt;&gt; </span><span class="c1"># subcommand functions</span>
<span class="gp">&gt;&gt;&gt; </span><span class="k">def</span><span class="w"> </span><span class="nf">foo</span><span class="p">(</span><span class="n">args</span><span class="p">):</span>
<span class="gp">... </span>    <span class="nb">print</span><span class="p">(</span><span class="n">args</span><span class="o">.</span><span class="n">x</span> <span class="o">*</span> <span class="n">args</span><span class="o">.</span><span class="n">y</span><span class="p">)</span>
<span class="gp">...</span>
<span class="gp">&gt;&gt;&gt; </span><span class="k">def</span><span class="w"> </span><span class="nf">bar</span><span class="p">(</span><span class="n">args</span><span class="p">):</span>
<span class="gp">... </span>    <span class="nb">print</span><span class="p">(</span><span class="s1">&#39;((</span><span class="si">%s</span><span class="s1">))&#39;</span> <span class="o">%</span> <span class="n">args</span><span class="o">.</span><span class="n">z</span><span class="p">)</span>
<span class="gp">...</span>
<span class="gp">&gt;&gt;&gt; </span><span class="c1"># create the top-level parser</span>
<span class="gp">&gt;&gt;&gt; </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="gp">&gt;&gt;&gt; </span><span class="n">subparsers</span> <span class="o">=</span> <span class="n">parser</span><span class="o">.</span><span class="n">add_subparsers</span><span class="p">(</span><span class="n">required</span><span class="o">=</span><span class="kc">True</span><span class="p">)</span>
<span class="gp">&gt;&gt;&gt;</span>
<span class="gp">&gt;&gt;&gt; </span><span class="c1"># create the parser for the &quot;foo&quot; command</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">parser_foo</span> <span class="o">=</span> <span class="n">subparsers</span><span class="o">.</span><span class="n">add_parser</span><span class="p">(</span><span class="s1">&#39;foo&#39;</span><span class="p">)</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">parser_foo</span><span class="o">.</span><span class="n">add_argument</span><span class="p">(</span><span class="s1">&#39;-x&#39;</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">1</span><span class="p">)</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">parser_foo</span><span class="o">.</span><span class="n">add_argument</span><span class="p">(</span><span class="s1">&#39;y&#39;</span><span class="p">,</span> <span class="nb">type</span><span class="o">=</span><span class="nb">float</span><span class="p">)</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">parser_foo</span><span class="o">.</span><span class="n">set_defaults</span><span class="p">(</span><span class="n">func</span><span class="o">=</span><span class="n">foo</span><span class="p">)</span>
<span class="gp">&gt;&gt;&gt;</span>
<span class="gp">&gt;&gt;&gt; </span><span class="c1"># create the parser for the &quot;bar&quot; command</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">parser_bar</span> <span class="o">=</span> <span class="n">subparsers</span><span class="o">.</span><span class="n">add_parser</span><span class="p">(</span><span class="s1">&#39;bar&#39;</span><span class="p">)</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">parser_bar</span><span class="o">.</span><span class="n">add_argument</span><span class="p">(</span><span class="s1">&#39;z&#39;</span><span class="p">)</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">parser_bar</span><span class="o">.</span><span class="n">set_defaults</span><span class="p">(</span><span class="n">func</span><span class="o">=</span><span class="n">bar</span><span class="p">)</span>
<span class="gp">&gt;&gt;&gt;</span>
<span class="gp">&gt;&gt;&gt; </span><span class="c1"># parse the args and call whatever function was selected</span>
<span class="gp">&gt;&gt;&gt; </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">&#39;foo 1 -x 2&#39;</span><span class="o">.</span><span class="n">split</span><span class="p">())</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">args</span><span class="o">.</span><span class="n">func</span><span class="p">(</span><span class="n">args</span><span class="p">)</span>
<span class="go">2.0</span>
<span class="gp">&gt;&gt;&gt;</span>
<span class="gp">&gt;&gt;&gt; </span><span class="c1"># parse the args and call whatever function was selected</span>
<span class="gp">&gt;&gt;&gt; </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">&#39;bar XYZYX&#39;</span><span class="o">.</span><span class="n">split</span><span class="p">())</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">args</span><span class="o">.</span><span class="n">func</span><span class="p">(</span><span class="n">args</span><span class="p">)</span>
<span class="go">((XYZYX))</span>
</pre></div>
</div>
<p>This way, you can let <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> do the job of calling the
appropriate function after argument parsing is complete.  Associating
functions with actions like this is typically the easiest way to handle the
different actions for each of your subparsers.  However, if it is necessary
to check the name of the subparser that was invoked, the <code class="docutils literal notranslate"><span class="pre">dest</span></code> keyword
argument to the <code class="xref py py-meth docutils literal notranslate"><span class="pre">add_subparsers()</span></code> call will work:</p>
<div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="gp">&gt;&gt;&gt; </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="gp">&gt;&gt;&gt; </span><span class="n">subparsers</span> <span class="o">=</span> <span class="n">parser</span><span class="o">.</span><span class="n">add_subparsers</span><span class="p">(</span><span class="n">dest</span><span class="o">=</span><span class="s1">&#39;subparser_name&#39;</span><span class="p">)</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">subparser1</span> <span class="o">=</span> <span class="n">subparsers</span><span class="o">.</span><span class="n">add_parser</span><span class="p">(</span><span class="s1">&#39;1&#39;</span><span class="p">)</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">subparser1</span><span class="o">.</span><span class="n">add_argument</span><span class="p">(</span><span class="s1">&#39;-x&#39;</span><span class="p">)</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">subparser2</span> <span class="o">=</span> <span class="n">subparsers</span><span class="o">.</span><span class="n">add_parser</span><span class="p">(</span><span class="s1">&#39;2&#39;</span><span class="p">)</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">subparser2</span><span class="o">.</span><span class="n">add_argument</span><span class="p">(</span><span class="s1">&#39;y&#39;</span><span class="p">)</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">parser</span><span class="o">.</span><span class="n">parse_args</span><span class="p">([</span><span class="s1">&#39;2&#39;</span><span class="p">,</span> <span class="s1">&#39;frobble&#39;</span><span class="p">])</span>
<span class="go">Namespace(subparser_name=&#39;2&#39;, y=&#39;frobble&#39;)</span>
</pre></div>
</div>
<div class="versionchanged">
<p><span class="versionmodified changed">Changed in version 3.7: </span>New <em>required</em> keyword-only parameter.</p>
</div>
<div class="versionchanged">
<p><span class="versionmodified changed">Changed in version 3.14: </span>Subparser’s <em>prog</em> is no longer affected by a custom usage message in
the main parser.</p>
</div>
</dd></dl>

<dl class="py method">
<dt class="sig sig-object py" id="argparse._SubParsersAction.add_parser">
<span class="sig-prename descclassname"><span class="pre">_SubParsersAction.</span></span><span class="sig-name descname"><span class="pre">add_parser</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">name</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">help</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">aliases</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">deprecated</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">False</span></span></em>, <em class="sig-param"><span class="o"><span class="pre">**</span></span><span class="n"><span class="pre">kwargs</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="#argparse._SubParsersAction.add_parser" title="Link to this definition">¶</a></dt>
<dd><p>Create and return a new <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> object for the
subcommand <em>name</em>.</p>
<p>The <em>name</em> argument is the name of the sub-command.</p>
<p>The <em>help</em> argument provides a short description for this sub-command.</p>
<p>The <em>aliases</em> argument allows providing alternative names for this
sub-command. For example:</p>
<div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="gp">&gt;&gt;&gt; </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="gp">&gt;&gt;&gt; </span><span class="n">subparsers</span> <span class="o">=</span> <span class="n">parser</span><span class="o">.</span><span class="n">add_subparsers</span><span class="p">()</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">checkout</span> <span class="o">=</span> <span class="n">subparsers</span><span class="o">.</span><span class="n">add_parser</span><span class="p">(</span><span class="s1">&#39;checkout&#39;</span><span class="p">,</span> <span class="n">aliases</span><span class="o">=</span><span class="p">[</span><span class="s1">&#39;co&#39;</span><span class="p">])</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">checkout</span><span class="o">.</span><span class="n">add_argument</span><span class="p">(</span><span class="s1">&#39;foo&#39;</span><span class="p">)</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">parser</span><span class="o">.</span><span class="n">parse_args</span><span class="p">([</span><span class="s1">&#39;co&#39;</span><span class="p">,</span> <span class="s1">&#39;bar&#39;</span><span class="p">])</span>
<span class="go">Namespace(foo=&#39;bar&#39;)</span>
</pre></div>
</div>
<p>The <em>deprecated</em> argument, if <code class="docutils literal notranslate"><span class="pre">True</span></code>, marks the sub-command as
deprecated and will issue a warning when used. For example:</p>
<div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="gp">&gt;&gt;&gt; </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">&#39;chicken.py&#39;</span><span class="p">)</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">subparsers</span> <span class="o">=</span> <span class="n">parser</span><span class="o">.</span><span class="n">add_subparsers</span><span class="p">()</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">fly</span> <span class="o">=</span> <span class="n">subparsers</span><span class="o">.</span><span class="n">add_parser</span><span class="p">(</span><span class="s1">&#39;fly&#39;</span><span class="p">,</span> <span class="n">deprecated</span><span class="o">=</span><span class="kc">True</span><span class="p">)</span>
<span class="gp">&gt;&gt;&gt; </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">&#39;fly&#39;</span><span class="p">])</span>
<span class="go">chicken.py: warning: command &#39;fly&#39; is deprecated</span>
<span class="go">Namespace()</span>
</pre></div>
</div>
<p>All other keyword arguments are passed directly to the
<code class="xref py py-class docutils literal notranslate"><span class="pre">ArgumentParser</span></code> constructor.</p>
<div class="versionadded">
<p><span class="versionmodified added">Added in version 3.13: </span>Added the <em>deprecated</em> parameter.</p>
</div>
</dd></dl>

</section>
<section id="filetype-objects">
<h3>FileType objects<a class="headerlink" href="#filetype-objects" title="Link to this heading">¶</a></h3>
<dl class="py class">
<dt class="sig sig-object py" id="argparse.FileType">
<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">FileType</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">mode</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">'r'</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">bufsize</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">-1</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">encoding</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">None</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">errors</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">None</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="#argparse.FileType" title="Link to this definition">¶</a></dt>
<dd><p>The <code class="xref py py-class docutils literal notranslate"><span class="pre">FileType</span></code> factory creates objects that can be passed to the type
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">ArgumentParser.add_argument()</span></code></a>.  Arguments that have
<code class="xref py py-class docutils literal notranslate"><span class="pre">FileType</span></code> objects as their type will open command-line arguments as
files with the requested modes, buffer sizes, encodings and error handling
(see the <a class="reference internal" href="functions.html#open" title="open"><code class="xref py py-func docutils literal notranslate"><span class="pre">open()</span></code></a> function for more details):</p>
<div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="gp">&gt;&gt;&gt; </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="gp">&gt;&gt;&gt; </span><span class="n">parser</span><span class="o">.</span><span class="n">add_argument</span><span class="p">(</span><span class="s1">&#39;--raw&#39;</span><span class="p">,</span> <span class="nb">type</span><span class="o">=</span><span class="n">argparse</span><span class="o">.</span><span class="n">FileType</span><span class="p">(</span><span class="s1">&#39;wb&#39;</span><span class="p">,</span> <span class="mi">0</span><span class="p">))</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">parser</span><span class="o">.</span><span class="n">add_argument</span><span class="p">(</span><span class="s1">&#39;out&#39;</span><span class="p">,</span> <span class="nb">type</span><span class="o">=</span><span class="n">argparse</span><span class="o">.</span><span class="n">FileType</span><span class="p">(</span><span class="s1">&#39;w&#39;</span><span class="p">,</span> <span class="n">encoding</span><span class="o">=</span><span class="s1">&#39;UTF-8&#39;</span><span class="p">))</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">parser</span><span class="o">.</span><span class="n">parse_args</span><span class="p">([</span><span class="s1">&#39;--raw&#39;</span><span class="p">,</span> <span class="s1">&#39;raw.dat&#39;</span><span class="p">,</span> <span class="s1">&#39;file.txt&#39;</span><span class="p">])</span>
<span class="go">Namespace(out=&lt;_io.TextIOWrapper name=&#39;file.txt&#39; mode=&#39;w&#39; encoding=&#39;UTF-8&#39;&gt;, raw=&lt;_io.FileIO name=&#39;raw.dat&#39; mode=&#39;wb&#39;&gt;)</span>
</pre></div>
</div>
<p>FileType objects understand the pseudo-argument <code class="docutils literal notranslate"><span class="pre">'-'</span></code> and automatically
convert this into <a class="reference internal" href="sys.html#sys.stdin" title="sys.stdin"><code class="xref py py-data docutils literal notranslate"><span class="pre">sys.stdin</span></code></a> for readable <code class="xref py py-class docutils literal notranslate"><span class="pre">FileType</span></code> objects and
<a class="reference internal" href="sys.html#sys.stdout" title="sys.stdout"><code class="xref py py-data docutils literal notranslate"><span class="pre">sys.stdout</span></code></a> for writable <code class="xref py py-class docutils literal notranslate"><span class="pre">FileType</span></code> objects:</p>
<div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="gp">&gt;&gt;&gt; </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="gp">&gt;&gt;&gt; </span><span class="n">parser</span><span class="o">.</span><span class="n">add_argument</span><span class="p">(</span><span class="s1">&#39;infile&#39;</span><span class="p">,</span> <span class="nb">type</span><span class="o">=</span><span class="n">argparse</span><span class="o">.</span><span class="n">FileType</span><span class="p">(</span><span class="s1">&#39;r&#39;</span><span class="p">))</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">parser</span><span class="o">.</span><span class="n">parse_args</span><span class="p">([</span><span class="s1">&#39;-&#39;</span><span class="p">])</span>
<span class="go">Namespace(infile=&lt;_io.TextIOWrapper name=&#39;&lt;stdin&gt;&#39; encoding=&#39;UTF-8&#39;&gt;)</span>
</pre></div>
</div>
<div class="admonition note">
<p class="admonition-title">Note</p>
<p>If one argument uses <em>FileType</em> and then a subsequent argument fails,
an error is reported but the file is not automatically closed.
This can also clobber the output files.
In this case, it would be better to wait until after the parser has
run and then use the <a class="reference internal" href="../reference/compound_stmts.html#with"><code class="xref std std-keyword docutils literal notranslate"><span class="pre">with</span></code></a>-statement to manage the files.</p>
</div>
<div class="versionchanged">
<p><span class="versionmodified changed">Changed in version 3.4: </span>Added the <em>encodings</em> and <em>errors</em> parameters.</p>
</div>
<div class="deprecated">
<p><span class="versionmodified deprecated">Deprecated since version 3.14.</span></p>
</div>
</dd></dl>

</section>
<section id="argument-groups">
<h3>Argument groups<a class="headerlink" href="#argument-groups" title="Link to this heading">¶</a></h3>
<dl class="py method">
<dt class="sig sig-object py" id="argparse.ArgumentParser.add_argument_group">
<span class="sig-prename descclassname"><span class="pre">ArgumentParser.</span></span><span class="sig-name descname"><span class="pre">add_argument_group</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">title=None</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">description=None</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">argument_default</span></span></em><span class="optional">]</span><span class="optional">[</span>, <em class="sig-param"><span class="n"><span class="pre">conflict_handler</span></span></em><span class="optional">]</span><span class="sig-paren">)</span><a class="headerlink" href="#argparse.ArgumentParser.add_argument_group" title="Link to this definition">¶</a></dt>
<dd><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> groups command-line arguments into
“positional arguments” and “options” when displaying help
messages. When there is a better conceptual grouping of arguments than this
default one, appropriate groups can be created using the
<code class="xref py py-meth docutils literal notranslate"><span class="pre">add_argument_group()</span></code> method:</p>
<div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="gp">&gt;&gt;&gt; </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">&#39;PROG&#39;</span><span class="p">,</span> <span class="n">add_help</span><span class="o">=</span><span class="kc">False</span><span class="p">)</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">group</span> <span class="o">=</span> <span class="n">parser</span><span class="o">.</span><span class="n">add_argument_group</span><span class="p">(</span><span class="s1">&#39;group&#39;</span><span class="p">)</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">group</span><span class="o">.</span><span class="n">add_argument</span><span class="p">(</span><span class="s1">&#39;--foo&#39;</span><span class="p">,</span> <span class="n">help</span><span class="o">=</span><span class="s1">&#39;foo help&#39;</span><span class="p">)</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">group</span><span class="o">.</span><span class="n">add_argument</span><span class="p">(</span><span class="s1">&#39;bar&#39;</span><span class="p">,</span> <span class="n">help</span><span class="o">=</span><span class="s1">&#39;bar help&#39;</span><span class="p">)</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">parser</span><span class="o">.</span><span class="n">print_help</span><span class="p">()</span>
<span class="go">usage: PROG [--foo FOO] bar</span>

<span class="go">group:</span>
<span class="go">  bar    bar help</span>
<span class="go">  --foo FOO  foo help</span>
</pre></div>
</div>
<p>The <code class="xref py py-meth docutils literal notranslate"><span class="pre">add_argument_group()</span></code> method returns an argument group object which
has an <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 just like a regular
<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>.  When an argument is added to the group, the parser
treats it just like a normal argument, but displays the argument in a
separate group for help messages.  The <code class="xref py py-meth docutils literal notranslate"><span class="pre">add_argument_group()</span></code> method
accepts <em>title</em> and <em>description</em> arguments which can be used to
customize this display:</p>
<div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="gp">&gt;&gt;&gt; </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">&#39;PROG&#39;</span><span class="p">,</span> <span class="n">add_help</span><span class="o">=</span><span class="kc">False</span><span class="p">)</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">group1</span> <span class="o">=</span> <span class="n">parser</span><span class="o">.</span><span class="n">add_argument_group</span><span class="p">(</span><span class="s1">&#39;group1&#39;</span><span class="p">,</span> <span class="s1">&#39;group1 description&#39;</span><span class="p">)</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">group1</span><span class="o">.</span><span class="n">add_argument</span><span class="p">(</span><span class="s1">&#39;foo&#39;</span><span class="p">,</span> <span class="n">help</span><span class="o">=</span><span class="s1">&#39;foo help&#39;</span><span class="p">)</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">group2</span> <span class="o">=</span> <span class="n">parser</span><span class="o">.</span><span class="n">add_argument_group</span><span class="p">(</span><span class="s1">&#39;group2&#39;</span><span class="p">,</span> <span class="s1">&#39;group2 description&#39;</span><span class="p">)</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">group2</span><span class="o">.</span><span class="n">add_argument</span><span class="p">(</span><span class="s1">&#39;--bar&#39;</span><span class="p">,</span> <span class="n">help</span><span class="o">=</span><span class="s1">&#39;bar help&#39;</span><span class="p">)</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">parser</span><span class="o">.</span><span class="n">print_help</span><span class="p">()</span>
<span class="go">usage: PROG [--bar BAR] foo</span>

<span class="go">group1:</span>
<span class="go">  group1 description</span>

<span class="go">  foo    foo help</span>

<span class="go">group2:</span>
<span class="go">  group2 description</span>

<span class="go">  --bar BAR  bar help</span>
</pre></div>
</div>
<p>The optional, keyword-only parameters <a class="reference internal" href="#argument-default">argument_default</a> and <a class="reference internal" href="#conflict-handler">conflict_handler</a>
allow for finer-grained control of the behavior of the argument group. These
parameters have the same meaning as in 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,
but apply specifically to the argument group rather than the entire parser.</p>
<p>Note that any arguments not in your user-defined groups will end up back
in the usual “positional arguments” and “optional arguments” sections.</p>
<div class="deprecated-removed">
<p><span class="versionmodified removed">Deprecated since version 3.11, removed in version 3.14: </span>Calling <code class="xref py py-meth docutils literal notranslate"><span class="pre">add_argument_group()</span></code> on an argument group now raises an
exception. This nesting was never supported, often failed to work
correctly, and was unintentionally exposed through inheritance.</p>
</div>
<div class="deprecated">
<p><span class="versionmodified deprecated">Deprecated since version 3.14: </span>Passing <a class="reference internal" href="#prefix-chars">prefix_chars</a> to <code class="xref py py-meth docutils literal notranslate"><span class="pre">add_argument_group()</span></code>
is now deprecated.</p>
</div>
</dd></dl>

</section>
<section id="mutual-exclusion">
<h3>Mutual exclusion<a class="headerlink" href="#mutual-exclusion" title="Link to this heading">¶</a></h3>
<dl class="py method">
<dt class="sig sig-object py" id="argparse.ArgumentParser.add_mutually_exclusive_group">
<span class="sig-prename descclassname"><span class="pre">ArgumentParser.</span></span><span class="sig-name descname"><span class="pre">add_mutually_exclusive_group</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">required</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">False</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="#argparse.ArgumentParser.add_mutually_exclusive_group" title="Link to this definition">¶</a></dt>
<dd><p>Create a mutually exclusive group. <code class="xref py py-mod docutils literal notranslate"><span class="pre">argparse</span></code> will make sure that only
one of the arguments in the mutually exclusive group was present on the
command line:</p>
<div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="gp">&gt;&gt;&gt; </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">&#39;PROG&#39;</span><span class="p">)</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">group</span> <span class="o">=</span> <span class="n">parser</span><span class="o">.</span><span class="n">add_mutually_exclusive_group</span><span class="p">()</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">group</span><span class="o">.</span><span class="n">add_argument</span><span class="p">(</span><span class="s1">&#39;--foo&#39;</span><span class="p">,</span> <span class="n">action</span><span class="o">=</span><span class="s1">&#39;store_true&#39;</span><span class="p">)</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">group</span><span class="o">.</span><span class="n">add_argument</span><span class="p">(</span><span class="s1">&#39;--bar&#39;</span><span class="p">,</span> <span class="n">action</span><span class="o">=</span><span class="s1">&#39;store_false&#39;</span><span class="p">)</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">parser</span><span class="o">.</span><span class="n">parse_args</span><span class="p">([</span><span class="s1">&#39;--foo&#39;</span><span class="p">])</span>
<span class="go">Namespace(bar=True, foo=True)</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">parser</span><span class="o">.</span><span class="n">parse_args</span><span class="p">([</span><span class="s1">&#39;--bar&#39;</span><span class="p">])</span>
<span class="go">Namespace(bar=False, foo=False)</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">parser</span><span class="o">.</span><span class="n">parse_args</span><span class="p">([</span><span class="s1">&#39;--foo&#39;</span><span class="p">,</span> <span class="s1">&#39;--bar&#39;</span><span class="p">])</span>
<span class="go">usage: PROG [-h] [--foo | --bar]</span>
<span class="go">PROG: error: argument --bar: not allowed with argument --foo</span>
</pre></div>
</div>
<p>The <code class="xref py py-meth docutils literal notranslate"><span class="pre">add_mutually_exclusive_group()</span></code> method also accepts a <em>required</em>
argument, to indicate that at least one of the mutually exclusive arguments
is required:</p>
<div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="gp">&gt;&gt;&gt; </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">&#39;PROG&#39;</span><span class="p">)</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">group</span> <span class="o">=</span> <span class="n">parser</span><span class="o">.</span><span class="n">add_mutually_exclusive_group</span><span class="p">(</span><span class="n">required</span><span class="o">=</span><span class="kc">True</span><span class="p">)</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">group</span><span class="o">.</span><span class="n">add_argument</span><span class="p">(</span><span class="s1">&#39;--foo&#39;</span><span class="p">,</span> <span class="n">action</span><span class="o">=</span><span class="s1">&#39;store_true&#39;</span><span class="p">)</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">group</span><span class="o">.</span><span class="n">add_argument</span><span class="p">(</span><span class="s1">&#39;--bar&#39;</span><span class="p">,</span> <span class="n">action</span><span class="o">=</span><span class="s1">&#39;store_false&#39;</span><span class="p">)</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">parser</span><span class="o">.</span><span class="n">parse_args</span><span class="p">([])</span>
<span class="go">usage: PROG [-h] (--foo | --bar)</span>
<span class="go">PROG: error: one of the arguments --foo --bar is required</span>
</pre></div>
</div>
<p>Note that currently mutually exclusive argument groups do not support the
<em>title</em> and <em>description</em> arguments of
<a class="reference internal" href="#argparse.ArgumentParser.add_argument_group" title="argparse.ArgumentParser.add_argument_group"><code class="xref py py-meth docutils literal notranslate"><span class="pre">add_argument_group()</span></code></a>. However, a mutually exclusive
group can be added to an argument group that has a title and description.
For example:</p>
<div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="gp">&gt;&gt;&gt; </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">&#39;PROG&#39;</span><span class="p">)</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">group</span> <span class="o">=</span> <span class="n">parser</span><span class="o">.</span><span class="n">add_argument_group</span><span class="p">(</span><span class="s1">&#39;Group title&#39;</span><span class="p">,</span> <span class="s1">&#39;Group description&#39;</span><span class="p">)</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">exclusive_group</span> <span class="o">=</span> <span class="n">group</span><span class="o">.</span><span class="n">add_mutually_exclusive_group</span><span class="p">(</span><span class="n">required</span><span class="o">=</span><span class="kc">True</span><span class="p">)</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">exclusive_group</span><span class="o">.</span><span class="n">add_argument</span><span class="p">(</span><span class="s1">&#39;--foo&#39;</span><span class="p">,</span> <span class="n">help</span><span class="o">=</span><span class="s1">&#39;foo help&#39;</span><span class="p">)</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">exclusive_group</span><span class="o">.</span><span class="n">add_argument</span><span class="p">(</span><span class="s1">&#39;--bar&#39;</span><span class="p">,</span> <span class="n">help</span><span class="o">=</span><span class="s1">&#39;bar help&#39;</span><span class="p">)</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">parser</span><span class="o">.</span><span class="n">print_help</span><span class="p">()</span>
<span class="go">usage: PROG [-h] (--foo FOO | --bar BAR)</span>

<span class="go">options:</span>
<span class="go">  -h, --help  show this help message and exit</span>

<span class="go">Group title:</span>
<span class="go">  Group description</span>

<span class="go">  --foo FOO   foo help</span>
<span class="go">  --bar BAR   bar help</span>
</pre></div>
</div>
<div class="deprecated-removed">
<p><span class="versionmodified removed">Deprecated since version 3.11, removed in version 3.14: </span>Calling <a class="reference internal" href="#argparse.ArgumentParser.add_argument_group" title="argparse.ArgumentParser.add_argument_group"><code class="xref py py-meth docutils literal notranslate"><span class="pre">add_argument_group()</span></code></a> or <code class="xref py py-meth docutils literal notranslate"><span class="pre">add_mutually_exclusive_group()</span></code>
on a mutually exclusive group now raises an exception. This nesting was
never supported, often failed to work correctly, and was unintentionally
exposed through inheritance.</p>
</div>
</dd></dl>

</section>
<section id="parser-defaults">
<h3>Parser defaults<a class="headerlink" href="#parser-defaults" title="Link to this heading">¶</a></h3>
<dl class="py method">
<dt class="sig sig-object py" id="argparse.ArgumentParser.set_defaults">
<span class="sig-prename descclassname"><span class="pre">ArgumentParser.</span></span><span class="sig-name descname"><span class="pre">set_defaults</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="o"><span class="pre">**</span></span><span class="n"><span class="pre">kwargs</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="#argparse.ArgumentParser.set_defaults" title="Link to this definition">¶</a></dt>
<dd><p>Most of the time, the attributes of the object returned by <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>
will be fully determined by inspecting the command-line arguments and the argument
actions.  <code class="xref py py-meth docutils literal notranslate"><span class="pre">set_defaults()</span></code> allows some additional
attributes that are determined without any inspection of the command line to
be added:</p>
<div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="gp">&gt;&gt;&gt; </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="gp">&gt;&gt;&gt; </span><span class="n">parser</span><span class="o">.</span><span class="n">add_argument</span><span class="p">(</span><span class="s1">&#39;foo&#39;</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="gp">&gt;&gt;&gt; </span><span class="n">parser</span><span class="o">.</span><span class="n">set_defaults</span><span class="p">(</span><span class="n">bar</span><span class="o">=</span><span class="mi">42</span><span class="p">,</span> <span class="n">baz</span><span class="o">=</span><span class="s1">&#39;badger&#39;</span><span class="p">)</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">parser</span><span class="o">.</span><span class="n">parse_args</span><span class="p">([</span><span class="s1">&#39;736&#39;</span><span class="p">])</span>
<span class="go">Namespace(bar=42, baz=&#39;badger&#39;, foo=736)</span>
</pre></div>
</div>
<p>Note that defaults can be set at both the parser level using <code class="xref py py-meth docutils literal notranslate"><span class="pre">set_defaults()</span></code>
and at the argument level using <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>. If both are called for the
same argument, the last default set for an argument is used:</p>
<div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="gp">&gt;&gt;&gt; </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="gp">&gt;&gt;&gt; </span><span class="n">parser</span><span class="o">.</span><span class="n">add_argument</span><span class="p">(</span><span class="s1">&#39;--foo&#39;</span><span class="p">,</span> <span class="n">default</span><span class="o">=</span><span class="s1">&#39;bar&#39;</span><span class="p">)</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">parser</span><span class="o">.</span><span class="n">set_defaults</span><span class="p">(</span><span class="n">foo</span><span class="o">=</span><span class="s1">&#39;spam&#39;</span><span class="p">)</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">parser</span><span class="o">.</span><span class="n">parse_args</span><span class="p">([])</span>
<span class="go">Namespace(foo=&#39;spam&#39;)</span>
</pre></div>
</div>
<p>Parser-level defaults can be particularly useful when working with multiple
parsers.  See the <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> method for an
example of this type.</p>
</dd></dl>

<dl class="py method">
<dt class="sig sig-object py" id="argparse.ArgumentParser.get_default">
<span class="sig-prename descclassname"><span class="pre">ArgumentParser.</span></span><span class="sig-name descname"><span class="pre">get_default</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">dest</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="#argparse.ArgumentParser.get_default" title="Link to this definition">¶</a></dt>
<dd><p>Get the default value for a namespace attribute, as set by either
<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
<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>:</p>
<div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="gp">&gt;&gt;&gt; </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="gp">&gt;&gt;&gt; </span><span class="n">parser</span><span class="o">.</span><span class="n">add_argument</span><span class="p">(</span><span class="s1">&#39;--foo&#39;</span><span class="p">,</span> <span class="n">default</span><span class="o">=</span><span class="s1">&#39;badger&#39;</span><span class="p">)</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">parser</span><span class="o">.</span><span class="n">get_default</span><span class="p">(</span><span class="s1">&#39;foo&#39;</span><span class="p">)</span>
<span class="go">&#39;badger&#39;</span>
</pre></div>
</div>
</dd></dl>

</section>
<section id="printing-help">
<h3>Printing help<a class="headerlink" href="#printing-help" title="Link to this heading">¶</a></h3>
<p>In most typical applications, <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> will take
care of formatting and printing any usage or error messages.  However, several
formatting methods are available:</p>
<dl class="py method">
<dt class="sig sig-object py" id="argparse.ArgumentParser.print_usage">
<span class="sig-prename descclassname"><span class="pre">ArgumentParser.</span></span><span class="sig-name descname"><span class="pre">print_usage</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">file</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">None</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="#argparse.ArgumentParser.print_usage" title="Link to this definition">¶</a></dt>
<dd><p>Print a brief description of how 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> should be
invoked on the command line.  If <em>file</em> is <code class="docutils literal notranslate"><span class="pre">None</span></code>, <a class="reference internal" href="sys.html#sys.stdout" title="sys.stdout"><code class="xref py py-data docutils literal notranslate"><span class="pre">sys.stdout</span></code></a> is
assumed.</p>
</dd></dl>

<dl class="py method">
<dt class="sig sig-object py" id="argparse.ArgumentParser.print_help">
<span class="sig-prename descclassname"><span class="pre">ArgumentParser.</span></span><span class="sig-name descname"><span class="pre">print_help</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">file</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">None</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="#argparse.ArgumentParser.print_help" title="Link to this definition">¶</a></dt>
<dd><p>Print a help message, including the program usage and information about the
arguments registered with 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>.  If <em>file</em> is
<code class="docutils literal notranslate"><span class="pre">None</span></code>, <a class="reference internal" href="sys.html#sys.stdout" title="sys.stdout"><code class="xref py py-data docutils literal notranslate"><span class="pre">sys.stdout</span></code></a> is assumed.</p>
</dd></dl>

<p>There are also variants of these methods that simply return a string instead of
printing it:</p>
<dl class="py method">
<dt class="sig sig-object py" id="argparse.ArgumentParser.format_usage">
<span class="sig-prename descclassname"><span class="pre">ArgumentParser.</span></span><span class="sig-name descname"><span class="pre">format_usage</span></span><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#argparse.ArgumentParser.format_usage" title="Link to this definition">¶</a></dt>
<dd><p>Return a string containing a brief description of how 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> should be invoked on the command line.</p>
</dd></dl>

<dl class="py method">
<dt class="sig sig-object py" id="argparse.ArgumentParser.format_help">
<span class="sig-prename descclassname"><span class="pre">ArgumentParser.</span></span><span class="sig-name descname"><span class="pre">format_help</span></span><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#argparse.ArgumentParser.format_help" title="Link to this definition">¶</a></dt>
<dd><p>Return a string containing a help message, including the program usage and
information about the arguments registered with 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>.</p>
</dd></dl>

</section>
<section id="partial-parsing">
<h3>Partial parsing<a class="headerlink" href="#partial-parsing" title="Link to this heading">¶</a></h3>
<dl class="py method">
<dt class="sig sig-object py" id="argparse.ArgumentParser.parse_known_args">
<span class="sig-prename descclassname"><span class="pre">ArgumentParser.</span></span><span class="sig-name descname"><span class="pre">parse_known_args</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">args</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">namespace</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">None</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="#argparse.ArgumentParser.parse_known_args" title="Link to this definition">¶</a></dt>
<dd><p>Sometimes a script only needs to handle a specific set of command-line
arguments, leaving any unrecognized arguments for another script or program.
In these cases, the <code class="xref py py-meth docutils literal notranslate"><span class="pre">parse_known_args()</span></code> method can be
useful.</p>
<p>This method works similarly to <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>, but it does
not raise an error for extra, unrecognized arguments. Instead, it parses the
known arguments and returns a two item tuple that contains the populated
namespace and the list of any unrecognized arguments.</p>
<div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="gp">&gt;&gt;&gt; </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="gp">&gt;&gt;&gt; </span><span class="n">parser</span><span class="o">.</span><span class="n">add_argument</span><span class="p">(</span><span class="s1">&#39;--foo&#39;</span><span class="p">,</span> <span class="n">action</span><span class="o">=</span><span class="s1">&#39;store_true&#39;</span><span class="p">)</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">parser</span><span class="o">.</span><span class="n">add_argument</span><span class="p">(</span><span class="s1">&#39;bar&#39;</span><span class="p">)</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">parser</span><span class="o">.</span><span class="n">parse_known_args</span><span class="p">([</span><span class="s1">&#39;--foo&#39;</span><span class="p">,</span> <span class="s1">&#39;--badger&#39;</span><span class="p">,</span> <span class="s1">&#39;BAR&#39;</span><span class="p">,</span> <span class="s1">&#39;spam&#39;</span><span class="p">])</span>
<span class="go">(Namespace(bar=&#39;BAR&#39;, foo=True), [&#39;--badger&#39;, &#39;spam&#39;])</span>
</pre></div>
</div>
</dd></dl>

<div class="admonition warning">
<p class="admonition-title">Warning</p>
<p><a class="reference internal" href="#prefix-matching"><span class="std std-ref">Prefix matching</span></a> rules apply to
<a class="reference internal" href="#argparse.ArgumentParser.parse_known_args" title="argparse.ArgumentParser.parse_known_args"><code class="xref py py-meth docutils literal notranslate"><span class="pre">parse_known_args()</span></code></a>. The parser may consume an option even if it’s just
a prefix of one of its known options, instead of leaving it in the remaining
arguments list.</p>
</div>
</section>
<section id="customizing-file-parsing">
<h3>Customizing file parsing<a class="headerlink" href="#customizing-file-parsing" title="Link to this heading">¶</a></h3>
<dl class="py method">
<dt class="sig sig-object py" id="argparse.ArgumentParser.convert_arg_line_to_args">
<span class="sig-prename descclassname"><span class="pre">ArgumentParser.</span></span><span class="sig-name descname"><span class="pre">convert_arg_line_to_args</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">arg_line</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="#argparse.ArgumentParser.convert_arg_line_to_args" title="Link to this definition">¶</a></dt>
<dd><p>Arguments that are read from a file (see the <em>fromfile_prefix_chars</em>
keyword argument 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) are read one
argument per line. <code class="xref py py-meth docutils literal notranslate"><span class="pre">convert_arg_line_to_args()</span></code> can be overridden for
fancier reading.</p>
<p>This method takes a single argument <em>arg_line</em> which is a string read from
the argument file.  It returns a list of arguments parsed from this string.
The method is called once per line read from the argument file, in order.</p>
<p>A useful override of this method is one that treats each space-separated word
as an argument.  The following example demonstrates how to do this:</p>
<div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="k">class</span><span class="w"> </span><span class="nc">MyArgumentParser</span><span class="p">(</span><span class="n">argparse</span><span class="o">.</span><span class="n">ArgumentParser</span><span class="p">):</span>
    <span class="k">def</span><span class="w"> </span><span class="nf">convert_arg_line_to_args</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="n">arg_line</span><span class="p">):</span>
        <span class="k">return</span> <span class="n">arg_line</span><span class="o">.</span><span class="n">split</span><span class="p">()</span>
</pre></div>
</div>
</dd></dl>

</section>
<section id="exiting-methods">
<h3>Exiting methods<a class="headerlink" href="#exiting-methods" title="Link to this heading">¶</a></h3>
<dl class="py method">
<dt class="sig sig-object py" id="argparse.ArgumentParser.exit">
<span class="sig-prename descclassname"><span class="pre">ArgumentParser.</span></span><span class="sig-name descname"><span class="pre">exit</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">status</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">0</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">message</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">None</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="#argparse.ArgumentParser.exit" title="Link to this definition">¶</a></dt>
<dd><p>This method terminates the program, exiting with the specified <em>status</em>
and, if given, it prints 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> before that.
The user can override this method to handle these steps differently:</p>
<div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="k">class</span><span class="w"> </span><span class="nc">ErrorCatchingArgumentParser</span><span class="p">(</span><span class="n">argparse</span><span class="o">.</span><span class="n">ArgumentParser</span><span class="p">):</span>
    <span class="k">def</span><span class="w"> </span><span class="nf">exit</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="n">status</span><span class="o">=</span><span class="mi">0</span><span class="p">,</span> <span class="n">message</span><span class="o">=</span><span class="kc">None</span><span class="p">):</span>
        <span class="k">if</span> <span class="n">status</span><span class="p">:</span>
            <span class="k">raise</span> <span class="ne">Exception</span><span class="p">(</span><span class="sa">f</span><span class="s1">&#39;Exiting because of an error: </span><span class="si">{</span><span class="n">message</span><span class="si">}</span><span class="s1">&#39;</span><span class="p">)</span>
        <span class="n">exit</span><span class="p">(</span><span class="n">status</span><span class="p">)</span>
</pre></div>
</div>
</dd></dl>

<dl class="py method">
<dt class="sig sig-object py" id="argparse.ArgumentParser.error">
<span class="sig-prename descclassname"><span class="pre">ArgumentParser.</span></span><span class="sig-name descname"><span class="pre">error</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">message</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="#argparse.ArgumentParser.error" title="Link to this definition">¶</a></dt>
<dd><p>This method prints a usage message, including the <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 terminates the program with a status code of 2.</p>
</dd></dl>

</section>
<section id="intermixed-parsing">
<h3>Intermixed parsing<a class="headerlink" href="#intermixed-parsing" title="Link to this heading">¶</a></h3>
<dl class="py method">
<dt class="sig sig-object py" id="argparse.ArgumentParser.parse_intermixed_args">
<span class="sig-prename descclassname"><span class="pre">ArgumentParser.</span></span><span class="sig-name descname"><span class="pre">parse_intermixed_args</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">args</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">namespace</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">None</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="#argparse.ArgumentParser.parse_intermixed_args" title="Link to this definition">¶</a></dt>
<dd></dd></dl>

<dl class="py method">
<dt class="sig sig-object py" id="argparse.ArgumentParser.parse_known_intermixed_args">
<span class="sig-prename descclassname"><span class="pre">ArgumentParser.</span></span><span class="sig-name descname"><span class="pre">parse_known_intermixed_args</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">args</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">namespace</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">None</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="#argparse.ArgumentParser.parse_known_intermixed_args" title="Link to this definition">¶</a></dt>
<dd><p>A number of Unix commands allow the user to intermix optional arguments with
positional arguments.  The <a class="reference internal" href="#argparse.ArgumentParser.parse_intermixed_args" title="argparse.ArgumentParser.parse_intermixed_args"><code class="xref py py-meth docutils literal notranslate"><span class="pre">parse_intermixed_args()</span></code></a>
and <code class="xref py py-meth docutils literal notranslate"><span class="pre">parse_known_intermixed_args()</span></code> methods
support this parsing style.</p>
<p>These parsers do not support all the <code class="xref py py-mod docutils literal notranslate"><span class="pre">argparse</span></code> features, and will raise
exceptions if unsupported features are used.  In particular, subparsers,
and mutually exclusive groups that include both
optionals and positionals are not supported.</p>
<p>The following example shows the difference between
<a class="reference internal" href="#argparse.ArgumentParser.parse_known_args" title="argparse.ArgumentParser.parse_known_args"><code class="xref py py-meth docutils literal notranslate"><span class="pre">parse_known_args()</span></code></a> and
<a class="reference internal" href="#argparse.ArgumentParser.parse_intermixed_args" title="argparse.ArgumentParser.parse_intermixed_args"><code class="xref py py-meth docutils literal notranslate"><span class="pre">parse_intermixed_args()</span></code></a>: the former returns <code class="docutils literal notranslate"><span class="pre">['2',</span>
<span class="pre">'3']</span></code> as unparsed arguments, while the latter collects all the positionals
into <code class="docutils literal notranslate"><span class="pre">rest</span></code>.</p>
<div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="gp">&gt;&gt;&gt; </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="gp">&gt;&gt;&gt; </span><span class="n">parser</span><span class="o">.</span><span class="n">add_argument</span><span class="p">(</span><span class="s1">&#39;--foo&#39;</span><span class="p">)</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">parser</span><span class="o">.</span><span class="n">add_argument</span><span class="p">(</span><span class="s1">&#39;cmd&#39;</span><span class="p">)</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">parser</span><span class="o">.</span><span class="n">add_argument</span><span class="p">(</span><span class="s1">&#39;rest&#39;</span><span class="p">,</span> <span class="n">nargs</span><span class="o">=</span><span class="s1">&#39;*&#39;</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="gp">&gt;&gt;&gt; </span><span class="n">parser</span><span class="o">.</span><span class="n">parse_known_args</span><span class="p">(</span><span class="s1">&#39;doit 1 --foo bar 2 3&#39;</span><span class="o">.</span><span class="n">split</span><span class="p">())</span>
<span class="go">(Namespace(cmd=&#39;doit&#39;, foo=&#39;bar&#39;, rest=[1]), [&#39;2&#39;, &#39;3&#39;])</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">parser</span><span class="o">.</span><span class="n">parse_intermixed_args</span><span class="p">(</span><span class="s1">&#39;doit 1 --foo bar 2 3&#39;</span><span class="o">.</span><span class="n">split</span><span class="p">())</span>
<span class="go">Namespace(cmd=&#39;doit&#39;, foo=&#39;bar&#39;, rest=[1, 2, 3])</span>
</pre></div>
</div>
<p><code class="xref py py-meth docutils literal notranslate"><span class="pre">parse_known_intermixed_args()</span></code> returns a two item tuple
containing the populated namespace and the list of remaining argument strings.
<a class="reference internal" href="#argparse.ArgumentParser.parse_intermixed_args" title="argparse.ArgumentParser.parse_intermixed_args"><code class="xref py py-meth docutils literal notranslate"><span class="pre">parse_intermixed_args()</span></code></a> raises an error if there are any
remaining unparsed argument strings.</p>
<div class="versionadded">
<p><span class="versionmodified added">Added in version 3.7.</span></p>
</div>
</dd></dl>

</section>
<section id="registering-custom-types-or-actions">
<h3>Registering custom types or actions<a class="headerlink" href="#registering-custom-types-or-actions" title="Link to this heading">¶</a></h3>
<dl class="py method">
<dt class="sig sig-object py" id="argparse.ArgumentParser.register">
<span class="sig-prename descclassname"><span class="pre">ArgumentParser.</span></span><span class="sig-name descname"><span class="pre">register</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">registry_name</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">value</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">object</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="#argparse.ArgumentParser.register" title="Link to this definition">¶</a></dt>
<dd><p>Sometimes it’s desirable to use a custom string in error messages to provide
more user-friendly output. In these cases, <code class="xref py py-meth docutils literal notranslate"><span class="pre">register()</span></code> can be used to
register custom actions or types with a parser and allow you to reference the
type by their registered name instead of their callable name.</p>
<p>The <code class="xref py py-meth docutils literal notranslate"><span class="pre">register()</span></code> method accepts three arguments - a <em>registry_name</em>,
specifying the internal registry where the object will be stored (e.g.,
<code class="docutils literal notranslate"><span class="pre">action</span></code>, <code class="docutils literal notranslate"><span class="pre">type</span></code>), <em>value</em>, which is the key under which the object will
be registered, and object, the callable to be registered.</p>
<p>The following example shows how to register a custom type with a parser:</p>
<div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="gp">&gt;&gt;&gt; </span><span class="kn">import</span><span class="w"> </span><span class="nn">argparse</span>
<span class="gp">&gt;&gt;&gt; </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="gp">&gt;&gt;&gt; </span><span class="n">parser</span><span class="o">.</span><span class="n">register</span><span class="p">(</span><span class="s1">&#39;type&#39;</span><span class="p">,</span> <span class="s1">&#39;hexadecimal integer&#39;</span><span class="p">,</span> <span class="k">lambda</span> <span class="n">s</span><span class="p">:</span> <span class="nb">int</span><span class="p">(</span><span class="n">s</span><span class="p">,</span> <span class="mi">16</span><span class="p">))</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">parser</span><span class="o">.</span><span class="n">add_argument</span><span class="p">(</span><span class="s1">&#39;--foo&#39;</span><span class="p">,</span> <span class="nb">type</span><span class="o">=</span><span class="s1">&#39;hexadecimal integer&#39;</span><span class="p">)</span>
<span class="go">_StoreAction(option_strings=[&#39;--foo&#39;], dest=&#39;foo&#39;, nargs=None, const=None, default=None, type=&#39;hexadecimal integer&#39;, choices=None, required=False, help=None, metavar=None, deprecated=False)</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">parser</span><span class="o">.</span><span class="n">parse_args</span><span class="p">([</span><span class="s1">&#39;--foo&#39;</span><span class="p">,</span> <span class="s1">&#39;0xFA&#39;</span><span class="p">])</span>
<span class="go">Namespace(foo=250)</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">parser</span><span class="o">.</span><span class="n">parse_args</span><span class="p">([</span><span class="s1">&#39;--foo&#39;</span><span class="p">,</span> <span class="s1">&#39;1.2&#39;</span><span class="p">])</span>
<span class="go">usage: PROG [-h] [--foo FOO]</span>
<span class="go">PROG: error: argument --foo: invalid &#39;hexadecimal integer&#39; value: &#39;1.2&#39;</span>
</pre></div>
</div>
</dd></dl>

</section>
</section>
<section id="exceptions">
<h2>Exceptions<a class="headerlink" href="#exceptions" title="Link to this heading">¶</a></h2>
<dl class="py exception">
<dt class="sig sig-object py" id="argparse.ArgumentError">
<em class="property"><span class="k"><span class="pre">exception</span></span><span class="w"> </span></em><span class="sig-prename descclassname"><span class="pre">argparse.</span></span><span class="sig-name descname"><span class="pre">ArgumentError</span></span><a class="headerlink" href="#argparse.ArgumentError" title="Link to this definition">¶</a></dt>
<dd><p>An error from creating or using an argument (optional or positional).</p>
<p>The string value of this exception is the message, augmented with
information about the argument that caused it.</p>
</dd></dl>

<dl class="py exception">
<dt class="sig sig-object py" id="argparse.ArgumentTypeError">
<em class="property"><span class="k"><span class="pre">exception</span></span><span class="w"> </span></em><span class="sig-prename descclassname"><span class="pre">argparse.</span></span><span class="sig-name descname"><span class="pre">ArgumentTypeError</span></span><a class="headerlink" href="#argparse.ArgumentTypeError" title="Link to this definition">¶</a></dt>
<dd><p>Raised when something goes wrong converting a command line string to a type.</p>
</dd></dl>

<p class="rubric">Guides and Tutorials</p>
<div class="toctree-wrapper compound">
<ul>
<li class="toctree-l1"><a class="reference internal" href="../howto/argparse.html">Argparse Tutorial</a></li>
<li class="toctree-l1"><a class="reference internal" href="../howto/argparse-optparse.html">Migrating <code class="docutils literal notranslate"><span class="pre">optparse</span></code> code to <code class="docutils literal notranslate"><span class="pre">argparse</span></code></a></li>
</ul>
</div>
</section>
</section>


            <div class="clearer"></div>
          </div>
        </div>
      </div>
      <div class="sphinxsidebar" role="navigation" aria-label="Main">
        <div class="sphinxsidebarwrapper">
  <div>
    <h3><a href="../contents.html">Table of Contents</a></h3>
    <ul>
<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>
<li><a class="reference internal" href="#argumentparser-objects">ArgumentParser objects</a><ul>
<li><a class="reference internal" href="#prog">prog</a></li>
<li><a class="reference internal" href="#usage">usage</a></li>
<li><a class="reference internal" href="#description">description</a></li>
<li><a class="reference internal" href="#epilog">epilog</a></li>
<li><a class="reference internal" href="#parents">parents</a></li>
<li><a class="reference internal" href="#formatter-class">formatter_class</a></li>
<li><a class="reference internal" href="#prefix-chars">prefix_chars</a></li>
<li><a class="reference internal" href="#fromfile-prefix-chars">fromfile_prefix_chars</a></li>
<li><a class="reference internal" href="#argument-default">argument_default</a></li>
<li><a class="reference internal" href="#allow-abbrev">allow_abbrev</a></li>
<li><a class="reference internal" href="#conflict-handler">conflict_handler</a></li>
<li><a class="reference internal" href="#add-help">add_help</a></li>
<li><a class="reference internal" href="#exit-on-error">exit_on_error</a></li>
<li><a class="reference internal" href="#suggest-on-error">suggest_on_error</a></li>
<li><a class="reference internal" href="#color">color</a></li>
</ul>
</li>
<li><a class="reference internal" href="#the-add-argument-method">The add_argument() method</a><ul>
<li><a class="reference internal" href="#name-or-flags">name or flags</a></li>
<li><a class="reference internal" href="#action">action</a></li>
<li><a class="reference internal" href="#nargs">nargs</a></li>
<li><a class="reference internal" href="#const">const</a></li>
<li><a class="reference internal" href="#default">default</a></li>
<li><a class="reference internal" href="#type">type</a></li>
<li><a class="reference internal" href="#choices">choices</a></li>
<li><a class="reference internal" href="#required">required</a></li>
<li><a class="reference internal" href="#help">help</a></li>
<li><a class="reference internal" href="#metavar">metavar</a></li>
<li><a class="reference internal" href="#dest">dest</a></li>
<li><a class="reference internal" href="#deprecated">deprecated</a></li>
<li><a class="reference internal" href="#action-classes">Action classes</a></li>
</ul>
</li>
<li><a class="reference internal" href="#the-parse-args-method">The parse_args() method</a><ul>
<li><a class="reference internal" href="#option-value-syntax">Option value syntax</a></li>
<li><a class="reference internal" href="#invalid-arguments">Invalid arguments</a></li>
<li><a class="reference internal" href="#arguments-containing">Arguments containing <code class="docutils literal notranslate"><span class="pre">-</span></code></a></li>
<li><a class="reference internal" href="#argument-abbreviations-prefix-matching">Argument abbreviations (prefix matching)</a></li>
<li><a class="reference internal" href="#beyond-sys-argv">Beyond <code class="docutils literal notranslate"><span class="pre">sys.argv</span></code></a></li>
<li><a class="reference internal" href="#the-namespace-object">The Namespace object</a></li>
</ul>
</li>
<li><a class="reference internal" href="#other-utilities">Other utilities</a><ul>
<li><a class="reference internal" href="#subcommands">Subcommands</a></li>
<li><a class="reference internal" href="#filetype-objects">FileType objects</a></li>
<li><a class="reference internal" href="#argument-groups">Argument groups</a></li>
<li><a class="reference internal" href="#mutual-exclusion">Mutual exclusion</a></li>
<li><a class="reference internal" href="#parser-defaults">Parser defaults</a></li>
<li><a class="reference internal" href="#printing-help">Printing help</a></li>
<li><a class="reference internal" href="#partial-parsing">Partial parsing</a></li>
<li><a class="reference internal" href="#customizing-file-parsing">Customizing file parsing</a></li>
<li><a class="reference internal" href="#exiting-methods">Exiting methods</a></li>
<li><a class="reference internal" href="#intermixed-parsing">Intermixed parsing</a></li>
<li><a class="reference internal" href="#registering-custom-types-or-actions">Registering custom types or actions</a></li>
</ul>
</li>
<li><a class="reference internal" href="#exceptions">Exceptions</a></li>
</ul>
</li>
</ul>

  </div>
  <div>
    <h4>Previous topic</h4>
    <p class="topless"><a href="cmdlinelibs.html"
                          title="previous chapter">Command-line interface libraries</a></p>
  </div>
  <div>
    <h4>Next topic</h4>
    <p class="topless"><a href="../howto/argparse.html"
                          title="next chapter">Argparse Tutorial</a></p>
  </div>
  <script>
    document.addEventListener('DOMContentLoaded', () => {
        const title = document.querySelector('meta[property="og:title"]').content;
        const elements = document.querySelectorAll('.improvepage');
        const pageurl = window.location.href.split('?')[0];
        elements.forEach(element => {
            const url = new URL(element.href.split('?')[0].replace("-nojs", ""));
            url.searchParams.set('pagetitle', title);
            url.searchParams.set('pageurl', pageurl);
            url.searchParams.set('pagesource', "library/argparse.rst");
            element.href = url.toString();
        });
    });
  </script>
  <div role="note" aria-label="source link">
    <h3>This page</h3>
    <ul class="this-page-menu">
      <li><a href="../bugs.html">Report a bug</a></li>
      <li><a class="improvepage" href="../improve-page-nojs.html">Improve this page</a></li>
      <li>
        <a href="https://github.com/python/cpython/blob/main/Doc/library/argparse.rst?plain=1"
            rel="nofollow">Show source
        </a>
      </li>
      
    </ul>
  </div>
        </div>
<div id="sidebarbutton" title="Collapse sidebar">
<span>«</span>
</div>

      </div>
      <div class="clearer"></div>
    </div>  
    <div class="related" role="navigation" aria-label="Related">
      <h3>Navigation</h3>
      <ul>
        <li class="right" style="margin-right: 10px">
          <a href="../genindex.html" title="General Index"
             >index</a></li>
        <li class="right" >
          <a href="../py-modindex.html" title="Python Module Index"
             >modules</a> |</li>
        <li class="right" >
          <a href="../howto/argparse.html" title="Argparse Tutorial"
             >next</a> |</li>
        <li class="right" >
          <a href="cmdlinelibs.html" title="Command-line interface libraries"
             >previous</a> |</li>

          <li><img src="../_static/py.svg" alt="Python logo" style="vertical-align: middle; margin-top: -1px"></li>
          <li><a href="https://www.python.org/">Python</a> &#187;</li>
          <li class="switchers">
            <div class="language_switcher_placeholder"></div>
            <div class="version_switcher_placeholder"></div>
          </li>
          <li>
              
          </li>
    <li id="cpython-language-and-version">
      <a href="../index.html">3.15.0a6 Documentation</a> &#187;
    </li>

          <li class="nav-item nav-item-1"><a href="index.html" >The Python Standard Library</a> &#187;</li>
          <li class="nav-item nav-item-2"><a href="cmdlinelibs.html" >Command-line interface libraries</a> &#187;</li>
        <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>
                <li class="right">
                    

    <div class="inline-search" role="search">
        <form class="inline-search" action="../search.html" method="get">
          <input placeholder="Quick search" aria-label="Quick search" type="search" name="q" id="search-box">
          <input type="submit" value="Go">
        </form>
    </div>
                     |
                </li>
            <li class="right">
<label class="theme-selector-label">
    Theme
    <select class="theme-selector" oninput="activateTheme(this.value)">
        <option value="auto" selected>Auto</option>
        <option value="light">Light</option>
        <option value="dark">Dark</option>
    </select>
</label> |</li>
            
      </ul>
    </div>  
    <div class="footer">
    &copy; <a href="../copyright.html">Copyright</a> 2001 Python Software Foundation.
    <br>
    This page is licensed under the Python Software Foundation License Version 2.
    <br>
    Examples, recipes, and other code in the documentation are additionally licensed under the Zero Clause BSD License.
    <br>
    
      See <a href="/license.html">History and License</a> for more information.<br>
    
    
    <br>

    The Python Software Foundation is a non-profit corporation.
<a href="https://www.python.org/psf/donations/">Please donate.</a>
<br>
    <br>
      Last updated on Mar 10, 2026 (08:58 UTC).
    
      <a href="/bugs.html">Found a bug</a>?
    
    <br>

    Created using <a href="https://www.sphinx-doc.org/">Sphinx</a> 8.2.3.
    </div>

  </body>
</html>