Team Ai
Apppublic

parthtamu/rag-code-assistant

sourceHugging Faceupdated 7mo agoView on Hugging Face
0likes
zipapp.html685 linesDownload Raw Back to docs
1<!DOCTYPE html>2 3<html lang="en" data-content_root="../">4  <head>5    <meta charset="utf-8" />6    <meta name="viewport" content="width=device-width, initial-scale=1.0" /><meta name="viewport" content="width=device-width, initial-scale=1" />7<meta property="og:title" content="zipapp — Manage executable Python zip archives" />8<meta property="og:type" content="website" />9<meta property="og:url" content="https://docs.python.org/3/library/zipapp.html" />10<meta property="og:site_name" content="Python documentation" />11<meta property="og:description" content="Source code: Lib/zipapp.py This module provides tools to manage the creation of zip files containing Python code, which can be executed directly by the Python interpreter. The module provides both ..." />12<meta property="og:image:width" content="1146" />13<meta property="og:image:height" content="600" />14<meta property="og:image" content="https://docs.python.org/3.15/_images/social_previews/summary_library_zipapp_b618a93c.png" />15<meta property="og:image:alt" content="Source code: Lib/zipapp.py This module provides tools to manage the creation of zip files containing Python code, which can be executed directly by the Python interpreter. The module provides both ..." />16<meta name="description" content="Source code: Lib/zipapp.py This module provides tools to manage the creation of zip files containing Python code, which can be executed directly by the Python interpreter. The module provides both ..." />17<meta name="twitter:card" content="summary_large_image" />18<meta name="theme-color" content="#3776ab">19 20    <title>zipapp — Manage executable Python zip archives &#8212; Python 3.15.0a6 documentation</title><meta name="viewport" content="width=device-width, initial-scale=1.0">21    22    <link rel="stylesheet" type="text/css" href="../_static/pygments.css?v=b86133f3" />23    <link rel="stylesheet" type="text/css" href="../_static/classic.css?v=234b1a7c" />24    <link rel="stylesheet" type="text/css" href="../_static/pydoctheme.css?v=89a2f22a" />25    <link rel="stylesheet" type="text/css" href="../_static/profiling-sampling-visualization.css?v=0c2600ae" />26    <link id="pygments_dark_css" media="(prefers-color-scheme: dark)" rel="stylesheet" type="text/css" href="../_static/pygments_dark.css?v=5349f25f" />27    28    <script src="../_static/documentation_options.js?v=6b7c9ff5"></script>29    <script src="../_static/doctools.js?v=9bcbadda"></script>30    <script src="../_static/sphinx_highlight.js?v=dc90522c"></script>31    <script src="../_static/profiling-sampling-visualization.js?v=9811ed04"></script>32    33    <script src="../_static/sidebar.js"></script>34    35    <link rel="search" type="application/opensearchdescription+xml"36          title="Search within Python 3.15.0a6 documentation"37          href="../_static/opensearch.xml"/>38    <link rel="author" title="About these documents" href="../about.html" />39    <link rel="index" title="Index" href="../genindex.html" />40    <link rel="search" title="Search" href="../search.html" />41    <link rel="copyright" title="Copyright" href="../copyright.html" />42    <link rel="next" title="Python Runtime Services" href="python.html" />43    <link rel="prev" title="venv — Creation of virtual environments" href="venv.html" />44    45      46      <script defer file-types="bz2,epub,zip" data-domain="docs.python.org" src="https://analytics.python.org/js/script.file-downloads.outbound-links.js"></script>47      48      <link rel="canonical" href="https://docs.python.org/3/library/zipapp.html">49      50    51 52    53    <style>54      @media only screen {55        table.full-width-table {56            width: 100%;57        }58      }59    </style>60<link rel="stylesheet" href="../_static/pydoctheme_dark.css" media="(prefers-color-scheme: dark)" id="pydoctheme_dark_css">61    <link rel="shortcut icon" type="image/png" href="../_static/py.svg">62            <script type="text/javascript" src="../_static/copybutton.js"></script>63            <script type="text/javascript" src="../_static/menu.js"></script>64            <script type="text/javascript" src="../_static/search-focus.js"></script>65            <script type="text/javascript" src="../_static/themetoggle.js"></script> 66            <script type="text/javascript" src="../_static/rtd_switcher.js"></script>67            <meta name="readthedocs-addons-api-version" content="1">68 69  </head>70<body>71<div class="mobile-nav">72    <input type="checkbox" id="menuToggler" class="toggler__input" aria-controls="navigation"73           aria-pressed="false" aria-expanded="false" role="button" aria-label="Menu">74    <nav class="nav-content" role="navigation">75        <label for="menuToggler" class="toggler__label">76            <span></span>77        </label>78        <span class="nav-items-wrapper">79            <a href="https://www.python.org/" class="nav-logo">80                <img src="../_static/py.svg" alt="Python logo">81            </a>82            <span class="version_switcher_placeholder"></span>83            <form role="search" class="search" action="../search.html" method="get">84                <svg xmlns="http://www.w3.org/2000/svg" width="20" height="20" viewBox="0 0 24 24" class="search-icon">85                    <path fill-rule="nonzero" fill="currentColor" d="M15.5 14h-.79l-.28-.27a6.5 6.5 0 001.48-5.34c-.47-2.78-2.79-5-5.59-5.34a6.505 6.505 0 00-7.27 7.27c.34 2.8 2.56 5.12 5.34 5.59a6.5 6.5 0 005.34-1.48l.27.28v.79l4.25 4.25c.41.41 1.08.41 1.49 0 .41-.41.41-1.08 0-1.49L15.5 14zm-6 0C7.01 14 5 11.99 5 9.5S7.01 5 9.5 5 14 7.01 14 9.5 11.99 14 9.5 14z"></path>86                </svg>87                <input placeholder="Quick search" aria-label="Quick search" type="search" name="q">88                <input type="submit" value="Go">89            </form>90        </span>91    </nav>92    <div class="menu-wrapper">93        <nav class="menu" role="navigation" aria-label="main navigation">94            <div class="language_switcher_placeholder"></div>95            96<label class="theme-selector-label">97    Theme98    <select class="theme-selector" oninput="activateTheme(this.value)">99        <option value="auto" selected>Auto</option>100        <option value="light">Light</option>101        <option value="dark">Dark</option>102    </select>103</label>104  <div>105    <h3><a href="../contents.html">Table of Contents</a></h3>106    <ul>107<li><a class="reference internal" href="#"><code class="xref py py-mod docutils literal notranslate"><span class="pre">zipapp</span></code> — Manage executable Python zip archives</a><ul>108<li><a class="reference internal" href="#basic-example">Basic Example</a></li>109<li><a class="reference internal" href="#command-line-interface">Command-Line Interface</a></li>110<li><a class="reference internal" href="#python-api">Python API</a></li>111<li><a class="reference internal" href="#examples">Examples</a></li>112<li><a class="reference internal" href="#specifying-the-interpreter">Specifying the Interpreter</a></li>113<li><a class="reference internal" href="#creating-standalone-applications-with-zipapp">Creating Standalone Applications with zipapp</a><ul>114<li><a class="reference internal" href="#caveats">Caveats</a></li>115</ul>116</li>117<li><a class="reference internal" href="#the-python-zip-application-archive-format">The Python Zip Application Archive Format</a></li>118</ul>119</li>120</ul>121 122  </div>123  <div>124    <h4>Previous topic</h4>125    <p class="topless"><a href="venv.html"126                          title="previous chapter"><code class="xref py py-mod docutils literal notranslate"><span class="pre">venv</span></code> — Creation of virtual environments</a></p>127  </div>128  <div>129    <h4>Next topic</h4>130    <p class="topless"><a href="python.html"131                          title="next chapter">Python Runtime Services</a></p>132  </div>133  <script>134    document.addEventListener('DOMContentLoaded', () => {135        const title = document.querySelector('meta[property="og:title"]').content;136        const elements = document.querySelectorAll('.improvepage');137        const pageurl = window.location.href.split('?')[0];138        elements.forEach(element => {139            const url = new URL(element.href.split('?')[0].replace("-nojs", ""));140            url.searchParams.set('pagetitle', title);141            url.searchParams.set('pageurl', pageurl);142            url.searchParams.set('pagesource', "library/zipapp.rst");143            element.href = url.toString();144        });145    });146  </script>147  <div role="note" aria-label="source link">148    <h3>This page</h3>149    <ul class="this-page-menu">150      <li><a href="../bugs.html">Report a bug</a></li>151      <li><a class="improvepage" href="../improve-page-nojs.html">Improve this page</a></li>152      <li>153        <a href="https://github.com/python/cpython/blob/main/Doc/library/zipapp.rst?plain=1"154            rel="nofollow">Show source155        </a>156      </li>157      158    </ul>159  </div>160        </nav>161    </div>162</div>163 164  165    <div class="related" role="navigation" aria-label="Related">166      <h3>Navigation</h3>167      <ul>168        <li class="right" style="margin-right: 10px">169          <a href="../genindex.html" title="General Index"170             accesskey="I">index</a></li>171        <li class="right" >172          <a href="../py-modindex.html" title="Python Module Index"173             >modules</a> |</li>174        <li class="right" >175          <a href="python.html" title="Python Runtime Services"176             accesskey="N">next</a> |</li>177        <li class="right" >178          <a href="venv.html" title="venv — Creation of virtual environments"179             accesskey="P">previous</a> |</li>180 181          <li><img src="../_static/py.svg" alt="Python logo" style="vertical-align: middle; margin-top: -1px"></li>182          <li><a href="https://www.python.org/">Python</a> &#187;</li>183          <li class="switchers">184            <div class="language_switcher_placeholder"></div>185            <div class="version_switcher_placeholder"></div>186          </li>187          <li>188              189          </li>190    <li id="cpython-language-and-version">191      <a href="../index.html">3.15.0a6 Documentation</a> &#187;192    </li>193 194          <li class="nav-item nav-item-1"><a href="index.html" >The Python Standard Library</a> &#187;</li>195          <li class="nav-item nav-item-2"><a href="distribution.html" accesskey="U">Software Packaging and Distribution</a> &#187;</li>196        <li class="nav-item nav-item-this"><a href=""><code class="xref py py-mod docutils literal notranslate"><span class="pre">zipapp</span></code> — Manage executable Python zip archives</a></li>197                <li class="right">198                    199 200    <div class="inline-search" role="search">201        <form class="inline-search" action="../search.html" method="get">202          <input placeholder="Quick search" aria-label="Quick search" type="search" name="q" id="search-box">203          <input type="submit" value="Go">204        </form>205    </div>206                     |207                </li>208            <li class="right">209<label class="theme-selector-label">210    Theme211    <select class="theme-selector" oninput="activateTheme(this.value)">212        <option value="auto" selected>Auto</option>213        <option value="light">Light</option>214        <option value="dark">Dark</option>215    </select>216</label> |</li>217            218      </ul>219    </div>    220 221    <div class="document">222      <div class="documentwrapper">223        <div class="bodywrapper">224          <div class="body" role="main">225            226  <section id="module-zipapp">227<span id="zipapp-manage-executable-python-zip-archives"></span><h1><code class="xref py py-mod docutils literal notranslate"><span class="pre">zipapp</span></code> — Manage executable Python zip archives<a class="headerlink" href="#module-zipapp" title="Link to this heading">¶</a></h1>228<div class="versionadded">229<p><span class="versionmodified added">Added in version 3.5.</span></p>230</div>231<p><strong>Source code:</strong> <a class="extlink-source reference external" href="https://github.com/python/cpython/tree/main/Lib/zipapp.py">Lib/zipapp.py</a></p>232<hr class="docutils" id="index-0" />233<p>This module provides tools to manage the creation of zip files containing234Python code, which can be  <a class="reference internal" href="../using/cmdline.html#using-on-interface-options"><span class="std std-ref">executed directly by the Python interpreter</span></a>.  The module provides both a235<a class="reference internal" href="#zipapp-command-line-interface"><span class="std std-ref">Command-Line Interface</span></a> and a <a class="reference internal" href="#zipapp-python-api"><span class="std std-ref">Python API</span></a>.</p>236<section id="basic-example">237<h2>Basic Example<a class="headerlink" href="#basic-example" title="Link to this heading">¶</a></h2>238<p>The following example shows how the <a class="reference internal" href="#zipapp-command-line-interface"><span class="std std-ref">Command-Line Interface</span></a>239can be used to create an executable archive from a directory containing240Python code.  When run, the archive will execute the <code class="docutils literal notranslate"><span class="pre">main</span></code> function from241the module <code class="docutils literal notranslate"><span class="pre">myapp</span></code> in the archive.</p>242<div class="highlight-shell-session notranslate"><div class="highlight"><pre><span></span><span class="gp">$ </span>python<span class="w"> </span>-m<span class="w"> </span>zipapp<span class="w"> </span>myapp<span class="w"> </span>-m<span class="w"> </span><span class="s2">&quot;myapp:main&quot;</span>243<span class="gp">$ </span>python<span class="w"> </span>myapp.pyz244<span class="go">&lt;output from myapp&gt;</span>245</pre></div>246</div>247</section>248<section id="command-line-interface">249<span id="zipapp-command-line-interface"></span><h2>Command-Line Interface<a class="headerlink" href="#command-line-interface" title="Link to this heading">¶</a></h2>250<p>When called as a program from the command line, the following form is used:</p>251<div class="highlight-shell-session notranslate"><div class="highlight"><pre><span></span><span class="gp">$ </span>python<span class="w"> </span>-m<span class="w"> </span>zipapp<span class="w"> </span><span class="nb">source</span><span class="w"> </span><span class="o">[</span>options<span class="o">]</span>252</pre></div>253</div>254<p>If <em>source</em> is a directory, this will create an archive from the contents of255<em>source</em>.  If <em>source</em> is a file, it should be an archive, and it will be256copied to the target archive (or the contents of its shebang line will be257displayed if the –info option is specified).</p>258<p>The following options are understood:</p>259<dl class="std option">260<dt class="sig sig-object std" id="cmdoption-zipapp-o">261<span id="cmdoption-zipapp-output"></span><span class="sig-name descname"><span class="pre">-o</span></span><span class="sig-prename descclassname"> <span class="pre">&lt;output&gt;</span></span><span class="sig-prename descclassname"><span class="pre">,</span> </span><span class="sig-name descname"><span class="pre">--output</span></span><span class="sig-prename descclassname"><span class="pre">=&lt;output&gt;</span></span><a class="headerlink" href="#cmdoption-zipapp-o" title="Link to this definition">¶</a></dt>262<dd><p>Write the output to a file named <em>output</em>.  If this option is not specified,263the output filename will be the same as the input <em>source</em>, with the264extension <code class="docutils literal notranslate"><span class="pre">.pyz</span></code> added.  If an explicit filename is given, it is used as265is (so a <code class="docutils literal notranslate"><span class="pre">.pyz</span></code> extension should be included if required).</p>266<p>An output filename must be specified if the <em>source</em> is an archive (and in267that case, <em>output</em> must not be the same as <em>source</em>).</p>268</dd></dl>269 270<dl class="std option">271<dt class="sig sig-object std" id="cmdoption-zipapp-p">272<span id="cmdoption-zipapp-python"></span><span class="sig-name descname"><span class="pre">-p</span></span><span class="sig-prename descclassname"> <span class="pre">&lt;interpreter&gt;</span></span><span class="sig-prename descclassname"><span class="pre">,</span> </span><span class="sig-name descname"><span class="pre">--python</span></span><span class="sig-prename descclassname"><span class="pre">=&lt;interpreter&gt;</span></span><a class="headerlink" href="#cmdoption-zipapp-p" title="Link to this definition">¶</a></dt>273<dd><p>Add a <code class="docutils literal notranslate"><span class="pre">#!</span></code> line to the archive specifying <em>interpreter</em> as the command274to run.  Also, on POSIX, make the archive executable.  The default is to275write no <code class="docutils literal notranslate"><span class="pre">#!</span></code> line, and not make the file executable.</p>276</dd></dl>277 278<dl class="std option">279<dt class="sig sig-object std" id="cmdoption-zipapp-m">280<span id="cmdoption-zipapp-main"></span><span class="sig-name descname"><span class="pre">-m</span></span><span class="sig-prename descclassname"> <span class="pre">&lt;mainfn&gt;</span></span><span class="sig-prename descclassname"><span class="pre">,</span> </span><span class="sig-name descname"><span class="pre">--main</span></span><span class="sig-prename descclassname"><span class="pre">=&lt;mainfn&gt;</span></span><a class="headerlink" href="#cmdoption-zipapp-m" title="Link to this definition">¶</a></dt>281<dd><p>Write a <code class="docutils literal notranslate"><span class="pre">__main__.py</span></code> file to the archive that executes <em>mainfn</em>.  The282<em>mainfn</em> argument should have the form “pkg.mod:fn”, where “pkg.mod” is a283package/module in the archive, and “fn” is a callable in the given module.284The <code class="docutils literal notranslate"><span class="pre">__main__.py</span></code> file will execute that callable.</p>285<p><a class="reference internal" href="#cmdoption-zipapp-m"><code class="xref std std-option docutils literal notranslate"><span class="pre">--main</span></code></a> cannot be specified when copying an archive.</p>286</dd></dl>287 288<dl class="std option">289<dt class="sig sig-object std" id="cmdoption-zipapp-c">290<span id="cmdoption-zipapp-compress"></span><span class="sig-name descname"><span class="pre">-c</span></span><span class="sig-prename descclassname"></span><span class="sig-prename descclassname"><span class="pre">,</span> </span><span class="sig-name descname"><span class="pre">--compress</span></span><span class="sig-prename descclassname"></span><a class="headerlink" href="#cmdoption-zipapp-c" title="Link to this definition">¶</a></dt>291<dd><p>Compress files with the deflate method, reducing the size of the output292file. By default, files are stored uncompressed in the archive.</p>293<p><a class="reference internal" href="#cmdoption-zipapp-c"><code class="xref std std-option docutils literal notranslate"><span class="pre">--compress</span></code></a> has no effect when copying an archive.</p>294<div class="versionadded">295<p><span class="versionmodified added">Added in version 3.7.</span></p>296</div>297</dd></dl>298 299<dl class="std option">300<dt class="sig sig-object std" id="cmdoption-zipapp-info">301<span class="sig-name descname"><span class="pre">--info</span></span><span class="sig-prename descclassname"></span><a class="headerlink" href="#cmdoption-zipapp-info" title="Link to this definition">¶</a></dt>302<dd><p>Display the interpreter embedded in the archive, for diagnostic purposes.  In303this case, any other options are ignored and SOURCE must be an archive, not a304directory.</p>305</dd></dl>306 307<dl class="std option">308<dt class="sig sig-object std" id="cmdoption-zipapp-h">309<span id="cmdoption-zipapp-help"></span><span class="sig-name descname"><span class="pre">-h</span></span><span class="sig-prename descclassname"></span><span class="sig-prename descclassname"><span class="pre">,</span> </span><span class="sig-name descname"><span class="pre">--help</span></span><span class="sig-prename descclassname"></span><a class="headerlink" href="#cmdoption-zipapp-h" title="Link to this definition">¶</a></dt>310<dd><p>Print a short usage message and exit.</p>311</dd></dl>312 313</section>314<section id="python-api">315<span id="zipapp-python-api"></span><h2>Python API<a class="headerlink" href="#python-api" title="Link to this heading">¶</a></h2>316<p>The module defines two convenience functions:</p>317<dl class="py function">318<dt class="sig sig-object py" id="zipapp.create_archive">319<span class="sig-prename descclassname"><span class="pre">zipapp.</span></span><span class="sig-name descname"><span class="pre">create_archive</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">source</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">target</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">interpreter</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">main</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">filter</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">compressed</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="#zipapp.create_archive" title="Link to this definition">¶</a></dt>320<dd><p>Create an application archive from <em>source</em>.  The source can be any321of the following:</p>322<ul class="simple">323<li><p>The name of a directory, or a <a class="reference internal" href="../glossary.html#term-path-like-object"><span class="xref std std-term">path-like object</span></a> referring324to a directory, in which case a new application archive will be325created from the content of that directory.</p></li>326<li><p>The name of an existing application archive file, or a <a class="reference internal" href="../glossary.html#term-path-like-object"><span class="xref std std-term">path-like object</span></a>327referring to such a file, in which case the file is copied to328the target (modifying it to reflect the value given for the <em>interpreter</em>329argument).  The file name should include the <code class="docutils literal notranslate"><span class="pre">.pyz</span></code> extension, if required.</p></li>330<li><p>A file object open for reading in bytes mode.  The content of the331file should be an application archive, and the file object is332assumed to be positioned at the start of the archive.</p></li>333</ul>334<p>The <em>target</em> argument determines where the resulting archive will be335written:</p>336<ul class="simple">337<li><p>If it is the name of a file, or a <a class="reference internal" href="../glossary.html#term-path-like-object"><span class="xref std std-term">path-like object</span></a>,338the archive will be written to that file.</p></li>339<li><p>If it is an open file object, the archive will be written to that340file object, which must be open for writing in bytes mode.</p></li>341<li><p>If the target is omitted (or <code class="docutils literal notranslate"><span class="pre">None</span></code>), the source must be a directory342and the target will be a file with the same name as the source, with343a <code class="docutils literal notranslate"><span class="pre">.pyz</span></code> extension added.</p></li>344</ul>345<p>The <em>interpreter</em> argument specifies the name of the Python346interpreter with which the archive will be executed.  It is written as347a “shebang” line at the start of the archive.  On POSIX, this will be348interpreted by the OS, and on Windows it will be handled by the Python349launcher.  Omitting the <em>interpreter</em> results in no shebang line being350written.  If an interpreter is specified, and the target is a351filename, the executable bit of the target file will be set.</p>352<p>The <em>main</em> argument specifies the name of a callable which will be353used as the main program for the archive.  It can only be specified if354the source is a directory, and the source does not already contain a355<code class="docutils literal notranslate"><span class="pre">__main__.py</span></code> file.  The <em>main</em> argument should take the form356“pkg.module:callable” and the archive will be run by importing357“pkg.module” and executing the given callable with no arguments.  It358is an error to omit <em>main</em> if the source is a directory and does not359contain a <code class="docutils literal notranslate"><span class="pre">__main__.py</span></code> file, as otherwise the resulting archive360would not be executable.</p>361<p>The optional <em>filter</em> argument specifies a callback function that362is passed a Path object representing the path to the file being added363(relative to the source directory).  It should return <code class="docutils literal notranslate"><span class="pre">True</span></code> if the364file is to be added.</p>365<p>The optional <em>compressed</em> argument determines whether files are366compressed.  If set to <code class="docutils literal notranslate"><span class="pre">True</span></code>, files in the archive are compressed367with the deflate method; otherwise, files are stored uncompressed.368This argument has no effect when copying an existing archive.</p>369<p>If a file object is specified for <em>source</em> or <em>target</em>, it is the370caller’s responsibility to close it after calling create_archive.</p>371<p>When copying an existing archive, file objects supplied only need372<code class="docutils literal notranslate"><span class="pre">read</span></code> and <code class="docutils literal notranslate"><span class="pre">readline</span></code>, or <code class="docutils literal notranslate"><span class="pre">write</span></code> methods.  When creating an373archive from a directory, if the target is a file object it will be374passed to the <code class="docutils literal notranslate"><span class="pre">zipfile.ZipFile</span></code> class, and must supply the methods375needed by that class.</p>376<div class="versionchanged">377<p><span class="versionmodified changed">Changed in version 3.7: </span>Added the <em>filter</em> and <em>compressed</em> parameters.</p>378</div>379</dd></dl>380 381<dl class="py function">382<dt class="sig sig-object py" id="zipapp.get_interpreter">383<span class="sig-prename descclassname"><span class="pre">zipapp.</span></span><span class="sig-name descname"><span class="pre">get_interpreter</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">archive</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="#zipapp.get_interpreter" title="Link to this definition">¶</a></dt>384<dd><p>Return the interpreter specified in the <code class="docutils literal notranslate"><span class="pre">#!</span></code> line at the start of the385archive.  If there is no <code class="docutils literal notranslate"><span class="pre">#!</span></code> line, return <a class="reference internal" href="constants.html#None" title="None"><code class="xref py py-const docutils literal notranslate"><span class="pre">None</span></code></a>.386The <em>archive</em> argument can be a filename or a file-like object open387for reading in bytes mode.  It is assumed to be at the start of the archive.</p>388</dd></dl>389 390</section>391<section id="examples">392<span id="zipapp-examples"></span><h2>Examples<a class="headerlink" href="#examples" title="Link to this heading">¶</a></h2>393<p>Pack up a directory into an archive, and run it.</p>394<div class="highlight-shell-session notranslate"><div class="highlight"><pre><span></span><span class="gp">$ </span>python<span class="w"> </span>-m<span class="w"> </span>zipapp<span class="w"> </span>myapp395<span class="gp">$ </span>python<span class="w"> </span>myapp.pyz396<span class="go">&lt;output from myapp&gt;</span>397</pre></div>398</div>399<p>The same can be done using the <a class="reference internal" href="#zipapp.create_archive" title="zipapp.create_archive"><code class="xref py py-func docutils literal notranslate"><span class="pre">create_archive()</span></code></a> function:</p>400<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">zipapp</span>401<span class="gp">&gt;&gt;&gt; </span><span class="n">zipapp</span><span class="o">.</span><span class="n">create_archive</span><span class="p">(</span><span class="s1">&#39;myapp&#39;</span><span class="p">,</span> <span class="s1">&#39;myapp.pyz&#39;</span><span class="p">)</span>402</pre></div>403</div>404<p>To make the application directly executable on POSIX, specify an interpreter405to use.</p>406<div class="highlight-shell-session notranslate"><div class="highlight"><pre><span></span><span class="gp">$ </span>python<span class="w"> </span>-m<span class="w"> </span>zipapp<span class="w"> </span>myapp<span class="w"> </span>-p<span class="w"> </span><span class="s2">&quot;/usr/bin/env python&quot;</span>407<span class="gp">$ </span>./myapp.pyz408<span class="go">&lt;output from myapp&gt;</span>409</pre></div>410</div>411<p>To replace the shebang line on an existing archive, create a modified archive412using the <a class="reference internal" href="#zipapp.create_archive" title="zipapp.create_archive"><code class="xref py py-func docutils literal notranslate"><span class="pre">create_archive()</span></code></a> function:</p>413<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">zipapp</span>414<span class="gp">&gt;&gt;&gt; </span><span class="n">zipapp</span><span class="o">.</span><span class="n">create_archive</span><span class="p">(</span><span class="s1">&#39;old_archive.pyz&#39;</span><span class="p">,</span> <span class="s1">&#39;new_archive.pyz&#39;</span><span class="p">,</span> <span class="s1">&#39;/usr/bin/python3&#39;</span><span class="p">)</span>415</pre></div>416</div>417<p>To update the file in place, do the replacement in memory using a <a class="reference internal" href="io.html#io.BytesIO" title="io.BytesIO"><code class="xref py py-class docutils literal notranslate"><span class="pre">BytesIO</span></code></a>418object, and then overwrite the source afterwards.  Note that there is a risk419when overwriting a file in place that an error will result in the loss of420the original file.  This code does not protect against such errors, but421production code should do so.  Also, this method will only work if the archive422fits in memory:</p>423<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">zipapp</span>424<span class="gp">&gt;&gt;&gt; </span><span class="kn">import</span><span class="w"> </span><span class="nn">io</span>425<span class="gp">&gt;&gt;&gt; </span><span class="n">temp</span> <span class="o">=</span> <span class="n">io</span><span class="o">.</span><span class="n">BytesIO</span><span class="p">()</span>426<span class="gp">&gt;&gt;&gt; </span><span class="n">zipapp</span><span class="o">.</span><span class="n">create_archive</span><span class="p">(</span><span class="s1">&#39;myapp.pyz&#39;</span><span class="p">,</span> <span class="n">temp</span><span class="p">,</span> <span class="s1">&#39;/usr/bin/python2&#39;</span><span class="p">)</span>427<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;myapp.pyz&#39;</span><span class="p">,</span> <span class="s1">&#39;wb&#39;</span><span class="p">)</span> <span class="k">as</span> <span class="n">f</span><span class="p">:</span>428<span class="gp">&gt;&gt;&gt; </span>    <span class="n">f</span><span class="o">.</span><span class="n">write</span><span class="p">(</span><span class="n">temp</span><span class="o">.</span><span class="n">getvalue</span><span class="p">())</span>429</pre></div>430</div>431</section>432<section id="specifying-the-interpreter">433<span id="zipapp-specifying-the-interpreter"></span><h2>Specifying the Interpreter<a class="headerlink" href="#specifying-the-interpreter" title="Link to this heading">¶</a></h2>434<p>Note that if you specify an interpreter and then distribute your application435archive, you need to ensure that the interpreter used is portable.  The Python436launcher for Windows supports most common forms of POSIX <code class="docutils literal notranslate"><span class="pre">#!</span></code> line, but there437are other issues to consider:</p>438<ul class="simple">439<li><p>If you use “/usr/bin/env python” (or other forms of the “python” command,440such as “/usr/bin/python”), you need to consider that your users may have441either Python 2 or Python 3 as their default, and write your code to work442under both versions.</p></li>443<li><p>If you use an explicit version, for example “/usr/bin/env python3” your444application will not work for users who do not have that version.  (This445may be what you want if you have not made your code Python 2 compatible).</p></li>446<li><p>There is no way to say “python X.Y or later”, so be careful of using an447exact version like “/usr/bin/env python3.4” as you will need to change your448shebang line for users of Python 3.5, for example.</p></li>449</ul>450<p>Typically, you should use an “/usr/bin/env python2” or “/usr/bin/env python3”,451depending on whether your code is written for Python 2 or 3.</p>452</section>453<section id="creating-standalone-applications-with-zipapp">454<h2>Creating Standalone Applications with zipapp<a class="headerlink" href="#creating-standalone-applications-with-zipapp" title="Link to this heading">¶</a></h2>455<p>Using the <code class="xref py py-mod docutils literal notranslate"><span class="pre">zipapp</span></code> module, it is possible to create self-contained Python456programs, which can be distributed to end users who only need to have a457suitable version of Python installed on their system.  The key to doing this458is to bundle all of the application’s dependencies into the archive, along459with the application code.</p>460<p>The steps to create a standalone archive are as follows:</p>461<ol class="arabic">462<li><p>Create your application in a directory as normal, so you have a <code class="docutils literal notranslate"><span class="pre">myapp</span></code>463directory containing a <code class="docutils literal notranslate"><span class="pre">__main__.py</span></code> file, and any supporting application464code.</p></li>465<li><p>Install all of your application’s dependencies into the <code class="docutils literal notranslate"><span class="pre">myapp</span></code> directory,466using pip:</p>467<div class="highlight-shell-session notranslate"><div class="highlight"><pre><span></span><span class="gp">$ </span>python<span class="w"> </span>-m<span class="w"> </span>pip<span class="w"> </span>install<span class="w"> </span>-r<span class="w"> </span>requirements.txt<span class="w"> </span>--target<span class="w"> </span>myapp468</pre></div>469</div>470<p>(this assumes you have your project requirements in a <code class="docutils literal notranslate"><span class="pre">requirements.txt</span></code>471file - if not, you can just list the dependencies manually on the pip command472line).</p>473</li>474<li><p>Package the application using:</p>475<div class="highlight-shell-session notranslate"><div class="highlight"><pre><span></span><span class="gp">$ </span>python<span class="w"> </span>-m<span class="w"> </span>zipapp<span class="w"> </span>-p<span class="w"> </span><span class="s2">&quot;interpreter&quot;</span><span class="w"> </span>myapp476</pre></div>477</div>478</li>479</ol>480<p>This will produce a standalone executable, which can be run on any machine with481the appropriate interpreter available. See <a class="reference internal" href="#zipapp-specifying-the-interpreter"><span class="std std-ref">Specifying the Interpreter</span></a>482for details. It can be shipped to users as a single file.</p>483<p>On Unix, the <code class="docutils literal notranslate"><span class="pre">myapp.pyz</span></code> file is executable as it stands.  You can rename the484file to remove the <code class="docutils literal notranslate"><span class="pre">.pyz</span></code> extension if you prefer a “plain” command name.  On485Windows, the <code class="docutils literal notranslate"><span class="pre">myapp.pyz[w]</span></code> file is executable by virtue of the fact that486the Python interpreter registers the <code class="docutils literal notranslate"><span class="pre">.pyz</span></code> and <code class="docutils literal notranslate"><span class="pre">.pyzw</span></code> file extensions487when installed.</p>488<section id="caveats">489<h3>Caveats<a class="headerlink" href="#caveats" title="Link to this heading">¶</a></h3>490<p>If your application depends on a package that includes a C extension, that491package cannot be run from a zip file (this is an OS limitation, as executable492code must be present in the filesystem for the OS loader to load it). In this493case, you can exclude that dependency from the zipfile, and either require494your users to have it installed, or ship it alongside your zipfile and add code495to your <code class="docutils literal notranslate"><span class="pre">__main__.py</span></code> to include the directory containing the unzipped496module in <code class="docutils literal notranslate"><span class="pre">sys.path</span></code>. In this case, you will need to make sure to ship497appropriate binaries for your target architecture(s) (and potentially pick the498correct version to add to <code class="docutils literal notranslate"><span class="pre">sys.path</span></code> at runtime, based on the user’s machine).</p>499</section>500</section>501<section id="the-python-zip-application-archive-format">502<h2>The Python Zip Application Archive Format<a class="headerlink" href="#the-python-zip-application-archive-format" title="Link to this heading">¶</a></h2>503<p>Python has been able to execute zip files which contain a <code class="docutils literal notranslate"><span class="pre">__main__.py</span></code> file504since version 2.6.  In order to be executed by Python, an application archive505simply has to be a standard zip file containing a <code class="docutils literal notranslate"><span class="pre">__main__.py</span></code> file which506will be run as the entry point for the application.  As usual for any Python507script, the parent of the script (in this case the zip file) will be placed on508<a class="reference internal" href="sys.html#sys.path" title="sys.path"><code class="xref py py-data docutils literal notranslate"><span class="pre">sys.path</span></code></a> and thus further modules can be imported from the zip file.</p>509<p>The zip file format allows arbitrary data to be prepended to a zip file.  The510zip application format uses this ability to prepend a standard POSIX “shebang”511line to the file (<code class="docutils literal notranslate"><span class="pre">#!/path/to/interpreter</span></code>).</p>512<p>Formally, the Python zip application format is therefore:</p>513<ol class="arabic simple">514<li><p>An optional shebang line, containing the characters <code class="docutils literal notranslate"><span class="pre">b'#!'</span></code> followed by an515interpreter name, and then a newline (<code class="docutils literal notranslate"><span class="pre">b'\n'</span></code>) character.  The interpreter516name can be anything acceptable to the OS “shebang” processing, or the Python517launcher on Windows.  The interpreter should be encoded in UTF-8 on Windows,518and in <a class="reference internal" href="sys.html#sys.getfilesystemencoding" title="sys.getfilesystemencoding"><code class="xref py py-func docutils literal notranslate"><span class="pre">sys.getfilesystemencoding()</span></code></a> on POSIX.</p></li>519<li><p>Standard zipfile data, as generated by the <a class="reference internal" href="zipfile.html#module-zipfile" title="zipfile: Read and write ZIP-format archive files."><code class="xref py py-mod docutils literal notranslate"><span class="pre">zipfile</span></code></a> module.  The520zipfile content <em>must</em> include a file called <code class="docutils literal notranslate"><span class="pre">__main__.py</span></code> (which must be521in the “root” of the zipfile - i.e., it cannot be in a subdirectory).  The522zipfile data can be compressed or uncompressed.</p></li>523</ol>524<p>If an application archive has a shebang line, it may have the executable bit set525on POSIX systems, to allow it to be executed directly.</p>526<p>There is no requirement that the tools in this module are used to create527application archives - the module is a convenience, but archives in the above528format created by any means are acceptable to Python.</p>529</section>530</section>531 532 533            <div class="clearer"></div>534          </div>535        </div>536      </div>537      <div class="sphinxsidebar" role="navigation" aria-label="Main">538        <div class="sphinxsidebarwrapper">539  <div>540    <h3><a href="../contents.html">Table of Contents</a></h3>541    <ul>542<li><a class="reference internal" href="#"><code class="xref py py-mod docutils literal notranslate"><span class="pre">zipapp</span></code> — Manage executable Python zip archives</a><ul>543<li><a class="reference internal" href="#basic-example">Basic Example</a></li>544<li><a class="reference internal" href="#command-line-interface">Command-Line Interface</a></li>545<li><a class="reference internal" href="#python-api">Python API</a></li>546<li><a class="reference internal" href="#examples">Examples</a></li>547<li><a class="reference internal" href="#specifying-the-interpreter">Specifying the Interpreter</a></li>548<li><a class="reference internal" href="#creating-standalone-applications-with-zipapp">Creating Standalone Applications with zipapp</a><ul>549<li><a class="reference internal" href="#caveats">Caveats</a></li>550</ul>551</li>552<li><a class="reference internal" href="#the-python-zip-application-archive-format">The Python Zip Application Archive Format</a></li>553</ul>554</li>555</ul>556 557  </div>558  <div>559    <h4>Previous topic</h4>560    <p class="topless"><a href="venv.html"561                          title="previous chapter"><code class="xref py py-mod docutils literal notranslate"><span class="pre">venv</span></code> — Creation of virtual environments</a></p>562  </div>563  <div>564    <h4>Next topic</h4>565    <p class="topless"><a href="python.html"566                          title="next chapter">Python Runtime Services</a></p>567  </div>568  <script>569    document.addEventListener('DOMContentLoaded', () => {570        const title = document.querySelector('meta[property="og:title"]').content;571        const elements = document.querySelectorAll('.improvepage');572        const pageurl = window.location.href.split('?')[0];573        elements.forEach(element => {574            const url = new URL(element.href.split('?')[0].replace("-nojs", ""));575            url.searchParams.set('pagetitle', title);576            url.searchParams.set('pageurl', pageurl);577            url.searchParams.set('pagesource', "library/zipapp.rst");578            element.href = url.toString();579        });580    });581  </script>582  <div role="note" aria-label="source link">583    <h3>This page</h3>584    <ul class="this-page-menu">585      <li><a href="../bugs.html">Report a bug</a></li>586      <li><a class="improvepage" href="../improve-page-nojs.html">Improve this page</a></li>587      <li>588        <a href="https://github.com/python/cpython/blob/main/Doc/library/zipapp.rst?plain=1"589            rel="nofollow">Show source590        </a>591      </li>592      593    </ul>594  </div>595        </div>596<div id="sidebarbutton" title="Collapse sidebar">597<span>«</span>598</div>599 600      </div>601      <div class="clearer"></div>602    </div>  603    <div class="related" role="navigation" aria-label="Related">604      <h3>Navigation</h3>605      <ul>606        <li class="right" style="margin-right: 10px">607          <a href="../genindex.html" title="General Index"608             >index</a></li>609        <li class="right" >610          <a href="../py-modindex.html" title="Python Module Index"611             >modules</a> |</li>612        <li class="right" >613          <a href="python.html" title="Python Runtime Services"614             >next</a> |</li>615        <li class="right" >616          <a href="venv.html" title="venv — Creation of virtual environments"617             >previous</a> |</li>618 619          <li><img src="../_static/py.svg" alt="Python logo" style="vertical-align: middle; margin-top: -1px"></li>620          <li><a href="https://www.python.org/">Python</a> &#187;</li>621          <li class="switchers">622            <div class="language_switcher_placeholder"></div>623            <div class="version_switcher_placeholder"></div>624          </li>625          <li>626              627          </li>628    <li id="cpython-language-and-version">629      <a href="../index.html">3.15.0a6 Documentation</a> &#187;630    </li>631 632          <li class="nav-item nav-item-1"><a href="index.html" >The Python Standard Library</a> &#187;</li>633          <li class="nav-item nav-item-2"><a href="distribution.html" >Software Packaging and Distribution</a> &#187;</li>634        <li class="nav-item nav-item-this"><a href=""><code class="xref py py-mod docutils literal notranslate"><span class="pre">zipapp</span></code> — Manage executable Python zip archives</a></li>635                <li class="right">636                    637 638    <div class="inline-search" role="search">639        <form class="inline-search" action="../search.html" method="get">640          <input placeholder="Quick search" aria-label="Quick search" type="search" name="q" id="search-box">641          <input type="submit" value="Go">642        </form>643    </div>644                     |645                </li>646            <li class="right">647<label class="theme-selector-label">648    Theme649    <select class="theme-selector" oninput="activateTheme(this.value)">650        <option value="auto" selected>Auto</option>651        <option value="light">Light</option>652        <option value="dark">Dark</option>653    </select>654</label> |</li>655            656      </ul>657    </div>  658    <div class="footer">659    &copy; <a href="../copyright.html">Copyright</a> 2001 Python Software Foundation.660    <br>661    This page is licensed under the Python Software Foundation License Version 2.662    <br>663    Examples, recipes, and other code in the documentation are additionally licensed under the Zero Clause BSD License.664    <br>665    666      See <a href="/license.html">History and License</a> for more information.<br>667    668    669    <br>670 671    The Python Software Foundation is a non-profit corporation.672<a href="https://www.python.org/psf/donations/">Please donate.</a>673<br>674    <br>675      Last updated on Mar 10, 2026 (08:58 UTC).676    677      <a href="/bugs.html">Found a bug</a>?678    679    <br>680 681    Created using <a href="https://www.sphinx-doc.org/">Sphinx</a> 8.2.3.682    </div>683 684  </body>685</html>