| Server IP : 82.208.35.60 / Your IP : 216.73.216.238 Web Server : Apache/2.4.55 (FreeBSD) OpenSSL/1.1.1q-freebsd PHP/7.3.31 System : FreeBSD server7.d2m.cz 12.4-RELEASE-p9 FreeBSD 12.4-RELEASE-p9 GENERIC amd64 User : studiokobylisy_cz ( 1008) PHP Version : 7.3.31 Disable Function : NONE MySQL : OFF | cURL : ON | WGET : OFF | Perl : OFF | Python : OFF | Sudo : OFF | Pkexec : OFF Directory : /usr/local/share/doc/py36-pip/reference/ |
Upload File : |
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
"http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
<title>pip install — pip 19.1.1 documentation</title>
<link rel="stylesheet" href="../_static/pypa.css" type="text/css" />
<link rel="stylesheet" href="../_static/pygments.css" type="text/css" />
<script type="text/javascript">
var DOCUMENTATION_OPTIONS = {
URL_ROOT: '../',
VERSION: '19.1.1',
COLLAPSE_INDEX: false,
FILE_SUFFIX: '.html',
HAS_SOURCE: true,
SOURCELINK_SUFFIX: '.txt'
};
</script>
<script type="text/javascript" src="../_static/jquery.js"></script>
<script type="text/javascript" src="../_static/underscore.js"></script>
<script type="text/javascript" src="../_static/doctools.js"></script>
<script type="text/javascript" src="../_static/sidebar.js"></script>
<link rel="search" title="Search" href="../search.html" />
<link rel="next" title="pip download" href="pip_download.html" />
<link rel="prev" title="pip" href="pip.html" />
<link rel="shortcut icon" type="image/png" href="../_static/py.png" />
<script type="text/javascript" src="../_static/copybutton.js"></script>
</head>
<body>
<div class="related" role="navigation" aria-label="related navigation">
<h3>Navigation</h3>
<ul>
<li class="right" style="margin-right: 10px">
<a href="pip_download.html" title="pip download"
accesskey="N">next</a></li>
<li class="right" >
<a href="pip.html" title="pip"
accesskey="P">previous</a> |</li>
<li><img src="../_static/py.png" alt=""
style="vertical-align: middle; margin-top: -1px"/></li>
<li><a href="https://pypa.io">PyPA</a> »</li>
<a href="../index.html">pip 19.1.1 documentation</a> »
<li class="nav-item nav-item-1"><a href="index.html" accesskey="U">Reference Guide</a> »</li>
<li class="right">
<div class="inline-search" style="display: none" role="search">
<form class="inline-search" action="../search.html" method="get">
<input placeholder="Quick search" type="text" name="q" />
<input type="submit" value="Go" />
<input type="hidden" name="check_keywords" value="yes" />
<input type="hidden" name="area" value="default" />
</form>
</div>
<script type="text/javascript">$('.inline-search').show(0);</script>
|
</li>
</ul>
</div>
<div class="document">
<div class="documentwrapper">
<div class="bodywrapper">
<div class="body" role="main">
<div class="section" id="pip-install">
<span id="id1"></span><h1><a class="toc-backref" href="#id18">pip install</a><a class="headerlink" href="#pip-install" title="Permalink to this headline">¶</a></h1>
<div class="contents topic" id="contents">
<p class="topic-title first">Contents</p>
<ul class="simple">
<li><a class="reference internal" href="#pip-install" id="id18">pip install</a><ul>
<li><a class="reference internal" href="#usage" id="id19">Usage</a></li>
<li><a class="reference internal" href="#description" id="id20">Description</a><ul>
<li><a class="reference internal" href="#overview" id="id21">Overview</a></li>
<li><a class="reference internal" href="#argument-handling" id="id22">Argument Handling</a></li>
<li><a class="reference internal" href="#working-out-the-name-and-version" id="id23">Working Out the Name and Version</a></li>
<li><a class="reference internal" href="#satisfying-requirements" id="id24">Satisfying Requirements</a></li>
<li><a class="reference internal" href="#installation-order" id="id25">Installation Order</a></li>
<li><a class="reference internal" href="#requirements-file-format" id="id26">Requirements File Format</a><ul>
<li><a class="reference internal" href="#using-environment-variables" id="id27">Using Environment Variables</a></li>
<li><a class="reference internal" href="#example-requirements-file" id="id28">Example Requirements File</a></li>
</ul>
</li>
<li><a class="reference internal" href="#requirement-specifiers" id="id29">Requirement Specifiers</a></li>
<li><a class="reference internal" href="#per-requirement-overrides" id="id30">Per-requirement Overrides</a></li>
<li><a class="reference internal" href="#pre-release-versions" id="id31">Pre-release Versions</a></li>
<li><a class="reference internal" href="#vcs-support" id="id32">VCS Support</a><ul>
<li><a class="reference internal" href="#git" id="id33">Git</a></li>
<li><a class="reference internal" href="#mercurial" id="id34">Mercurial</a></li>
<li><a class="reference internal" href="#subversion" id="id35">Subversion</a></li>
<li><a class="reference internal" href="#bazaar" id="id36">Bazaar</a></li>
<li><a class="reference internal" href="#id10" id="id37">Using Environment Variables</a></li>
</ul>
</li>
<li><a class="reference internal" href="#finding-packages" id="id38">Finding Packages</a></li>
<li><a class="reference internal" href="#ssl-certificate-verification" id="id39">SSL Certificate Verification</a></li>
<li><a class="reference internal" href="#caching" id="id40">Caching</a><ul>
<li><a class="reference internal" href="#wheel-cache" id="id41">Wheel Cache</a></li>
</ul>
</li>
<li><a class="reference internal" href="#hash-checking-mode" id="id42">Hash-Checking Mode</a><ul>
<li><a class="reference internal" href="#hashes-from-pypi" id="id43">Hashes from PyPI</a></li>
</ul>
</li>
<li><a class="reference internal" href="#editable-installs" id="id44">“Editable” Installs</a></li>
<li><a class="reference internal" href="#controlling-setup-requires" id="id45">Controlling setup_requires</a></li>
<li><a class="reference internal" href="#build-system-interface" id="id46">Build System Interface</a></li>
</ul>
</li>
<li><a class="reference internal" href="#options" id="id47">Options</a></li>
<li><a class="reference internal" href="#examples" id="id48">Examples</a></li>
</ul>
</li>
</ul>
</div>
<div class="section" id="usage">
<h2><a class="toc-backref" href="#id19">Usage</a><a class="headerlink" href="#usage" title="Permalink to this headline">¶</a></h2>
<div class="highlight-default"><div class="highlight"><pre><span></span><span class="n">pip</span> <span class="n">install</span> <span class="p">[</span><span class="n">options</span><span class="p">]</span> <span class="o"><</span><span class="n">requirement</span> <span class="n">specifier</span><span class="o">></span> <span class="p">[</span><span class="n">package</span><span class="o">-</span><span class="n">index</span><span class="o">-</span><span class="n">options</span><span class="p">]</span> <span class="o">...</span>
<span class="n">pip</span> <span class="n">install</span> <span class="p">[</span><span class="n">options</span><span class="p">]</span> <span class="o">-</span><span class="n">r</span> <span class="o"><</span><span class="n">requirements</span> <span class="n">file</span><span class="o">></span> <span class="p">[</span><span class="n">package</span><span class="o">-</span><span class="n">index</span><span class="o">-</span><span class="n">options</span><span class="p">]</span> <span class="o">...</span>
<span class="n">pip</span> <span class="n">install</span> <span class="p">[</span><span class="n">options</span><span class="p">]</span> <span class="p">[</span><span class="o">-</span><span class="n">e</span><span class="p">]</span> <span class="o"><</span><span class="n">vcs</span> <span class="n">project</span> <span class="n">url</span><span class="o">></span> <span class="o">...</span>
<span class="n">pip</span> <span class="n">install</span> <span class="p">[</span><span class="n">options</span><span class="p">]</span> <span class="p">[</span><span class="o">-</span><span class="n">e</span><span class="p">]</span> <span class="o"><</span><span class="n">local</span> <span class="n">project</span> <span class="n">path</span><span class="o">></span> <span class="o">...</span>
<span class="n">pip</span> <span class="n">install</span> <span class="p">[</span><span class="n">options</span><span class="p">]</span> <span class="o"><</span><span class="n">archive</span> <span class="n">url</span><span class="o">/</span><span class="n">path</span><span class="o">></span> <span class="o">...</span>
</pre></div>
</div>
</div>
<div class="section" id="description">
<h2><a class="toc-backref" href="#id20">Description</a><a class="headerlink" href="#description" title="Permalink to this headline">¶</a></h2>
<p><p>Install packages from:</p>
<ul class="simple">
<li>PyPI (and other indexes) using requirement specifiers.</li>
<li>VCS project urls.</li>
<li>Local project directories.</li>
<li>Local or remote source archives.</li>
</ul>
<p>pip also supports installing from “requirements files”, which provide
an easy way to specify a whole environment to be installed.</p>
</p>
<div class="section" id="overview">
<h3><a class="toc-backref" href="#id21">Overview</a><a class="headerlink" href="#overview" title="Permalink to this headline">¶</a></h3>
<p>Pip install has several stages:</p>
<ol class="arabic simple">
<li>Identify the base requirements. The user supplied arguments are processed
here.</li>
<li>Resolve dependencies. What will be installed is determined here.</li>
<li>Build wheels. All the dependencies that can be are built into wheels.</li>
<li>Install the packages (and uninstall anything being upgraded/replaced).</li>
</ol>
</div>
<div class="section" id="argument-handling">
<h3><a class="toc-backref" href="#id22">Argument Handling</a><a class="headerlink" href="#argument-handling" title="Permalink to this headline">¶</a></h3>
<p>When looking at the items to be installed, pip checks what type of item
each is, in the following order:</p>
<ol class="arabic simple">
<li>Project or archive URL.</li>
<li>Local directory (which must contain a <code class="docutils literal"><span class="pre">setup.py</span></code>, or pip will report
an error).</li>
<li>Local file (a sdist or wheel format archive, following the naming
conventions for those formats).</li>
<li>A requirement, as specified in <span class="target" id="index-0"></span><a class="pep reference external" href="https://www.python.org/dev/peps/pep-0440"><strong>PEP 440</strong></a>.</li>
</ol>
<p>Each item identified is added to the set of requirements to be satisfied by
the install.</p>
</div>
<div class="section" id="working-out-the-name-and-version">
<h3><a class="toc-backref" href="#id23">Working Out the Name and Version</a><a class="headerlink" href="#working-out-the-name-and-version" title="Permalink to this headline">¶</a></h3>
<p>For each candidate item, pip needs to know the project name and version. For
wheels (identified by the <code class="docutils literal"><span class="pre">.whl</span></code> file extension) this can be obtained from
the filename, as per the Wheel spec. For local directories, or explicitly
specified sdist files, the <code class="docutils literal"><span class="pre">setup.py</span> <span class="pre">egg_info</span></code> command is used to determine
the project metadata. For sdists located via an index, the filename is parsed
for the name and project version (this is in theory slightly less reliable
than using the <code class="docutils literal"><span class="pre">egg_info</span></code> command, but avoids downloading and processing
unnecessary numbers of files).</p>
<p>Any URL may use the <code class="docutils literal"><span class="pre">#egg=name</span></code> syntax (see <a class="reference internal" href="#vcs-support"><span class="std std-ref">VCS Support</span></a>) to
explicitly state the project name.</p>
</div>
<div class="section" id="satisfying-requirements">
<h3><a class="toc-backref" href="#id24">Satisfying Requirements</a><a class="headerlink" href="#satisfying-requirements" title="Permalink to this headline">¶</a></h3>
<p>Once pip has the set of requirements to satisfy, it chooses which version of
each requirement to install using the simple rule that the latest version that
satisfies the given constraints will be installed (but see <a class="reference internal" href="#pre-release-versions"><span class="std std-ref">here</span></a>
for an exception regarding pre-release versions). Where more than one source of
the chosen version is available, it is assumed that any source is acceptable
(as otherwise the versions would differ).</p>
</div>
<div class="section" id="installation-order">
<h3><a class="toc-backref" href="#id25">Installation Order</a><a class="headerlink" href="#installation-order" title="Permalink to this headline">¶</a></h3>
<p>As of v6.1.0, pip installs dependencies before their dependents, i.e. in
“topological order”. This is the only commitment pip currently makes related
to order. While it may be coincidentally true that pip will install things in
the order of the install arguments or in the order of the items in a
requirements file, this is not a promise.</p>
<p>In the event of a dependency cycle (aka “circular dependency”), the current
implementation (which might possibly change later) has it such that the first
encountered member of the cycle is installed last.</p>
<p>For instance, if quux depends on foo which depends on bar which depends on baz,
which depends on foo:</p>
<div class="highlight-default"><div class="highlight"><pre><span></span><span class="n">pip</span> <span class="n">install</span> <span class="n">quux</span>
<span class="o">...</span>
<span class="n">Installing</span> <span class="n">collected</span> <span class="n">packages</span> <span class="n">baz</span><span class="p">,</span> <span class="n">bar</span><span class="p">,</span> <span class="n">foo</span><span class="p">,</span> <span class="n">quux</span>
<span class="n">pip</span> <span class="n">install</span> <span class="n">bar</span>
<span class="o">...</span>
<span class="n">Installing</span> <span class="n">collected</span> <span class="n">packages</span> <span class="n">foo</span><span class="p">,</span> <span class="n">baz</span><span class="p">,</span> <span class="n">bar</span>
</pre></div>
</div>
<p>Prior to v6.1.0, pip made no commitments about install order.</p>
<p>The decision to install topologically is based on the principle that
installations should proceed in a way that leaves the environment usable at each
step. This has two main practical benefits:</p>
<ol class="arabic simple">
<li>Concurrent use of the environment during the install is more likely to work.</li>
<li>A failed install is less likely to leave a broken environment. Although pip
would like to support failure rollbacks eventually, in the mean time, this is
an improvement.</li>
</ol>
<p>Although the new install order is not intended to replace (and does not replace)
the use of <code class="docutils literal"><span class="pre">setup_requires</span></code> to declare build dependencies, it may help certain
projects install from sdist (that might previously fail) that fit the following
profile:</p>
<ol class="arabic simple">
<li>They have build dependencies that are also declared as install dependencies
using <code class="docutils literal"><span class="pre">install_requires</span></code>.</li>
<li><code class="docutils literal"><span class="pre">python</span> <span class="pre">setup.py</span> <span class="pre">egg_info</span></code> works without their build dependencies being
installed.</li>
<li>For whatever reason, they don’t or won’t declare their build dependencies using
<code class="docutils literal"><span class="pre">setup_requires</span></code>.</li>
</ol>
</div>
<div class="section" id="requirements-file-format">
<span id="id2"></span><h3><a class="toc-backref" href="#id26">Requirements File Format</a><a class="headerlink" href="#requirements-file-format" title="Permalink to this headline">¶</a></h3>
<p>Each line of the requirements file indicates something to be installed,
and like arguments to <a class="reference internal" href="#pip-install"><span class="std std-ref">pip install</span></a>, the following forms are supported:</p>
<div class="highlight-default"><div class="highlight"><pre><span></span><span class="p">[[</span><span class="o">--</span><span class="n">option</span><span class="p">]</span><span class="o">...</span><span class="p">]</span>
<span class="o"><</span><span class="n">requirement</span> <span class="n">specifier</span><span class="o">></span> <span class="p">[;</span> <span class="n">markers</span><span class="p">]</span> <span class="p">[[</span><span class="o">--</span><span class="n">option</span><span class="p">]</span><span class="o">...</span><span class="p">]</span>
<span class="o"><</span><span class="n">archive</span> <span class="n">url</span><span class="o">/</span><span class="n">path</span><span class="o">></span>
<span class="p">[</span><span class="o">-</span><span class="n">e</span><span class="p">]</span> <span class="o"><</span><span class="n">local</span> <span class="n">project</span> <span class="n">path</span><span class="o">></span>
<span class="p">[</span><span class="o">-</span><span class="n">e</span><span class="p">]</span> <span class="o"><</span><span class="n">vcs</span> <span class="n">project</span> <span class="n">url</span><span class="o">></span>
</pre></div>
</div>
<p>For details on requirement specifiers, see <a class="reference internal" href="#requirement-specifiers"><span class="std std-ref">Requirement Specifiers</span></a>.</p>
<p>See the <a class="reference internal" href="#pip-install-examples"><span class="std std-ref">pip install Examples</span></a> for examples of all these forms.</p>
<p>A line that begins with <code class="docutils literal"><span class="pre">#</span></code> is treated as a comment and ignored. Whitespace
followed by a <code class="docutils literal"><span class="pre">#</span></code> causes the <code class="docutils literal"><span class="pre">#</span></code> and the remainder of the line to be
treated as a comment.</p>
<p>A line ending in an unescaped <code class="docutils literal"><span class="pre">\</span></code> is treated as a line continuation
and the newline following it is effectively ignored.</p>
<p>Comments are stripped <em>before</em> line continuations are processed.</p>
<p>The following options are supported:</p>
<blockquote>
<div><ul class="simple">
<li><a class="reference internal" href="pip_wheel.html#index-url"><span class="std std-ref">-i, –index-url</span></a></li>
<li><a class="reference internal" href="pip_wheel.html#extra-index-url"><span class="std std-ref">–extra-index-url</span></a></li>
<li><a class="reference internal" href="pip_wheel.html#no-index"><span class="std std-ref">–no-index</span></a></li>
<li><a class="reference internal" href="pip_wheel.html#find-links"><span class="std std-ref">-f, –find-links</span></a></li>
<li><a class="reference internal" href="#install-no-binary"><span class="std std-ref">–no-binary</span></a></li>
<li><a class="reference internal" href="#install-only-binary"><span class="std std-ref">–only-binary</span></a></li>
<li><a class="reference internal" href="#require-hashes"><span class="std std-ref">–require-hashes</span></a></li>
</ul>
</div></blockquote>
<p>For example, to specify <a class="reference internal" href="pip_wheel.html#no-index"><span class="std std-ref">–no-index</span></a> and 2 <a class="reference internal" href="pip_wheel.html#find-links"><span class="std std-ref">–find-links</span></a> locations:</p>
<div class="highlight-default"><div class="highlight"><pre><span></span><span class="o">--</span><span class="n">no</span><span class="o">-</span><span class="n">index</span>
<span class="o">--</span><span class="n">find</span><span class="o">-</span><span class="n">links</span> <span class="o">/</span><span class="n">my</span><span class="o">/</span><span class="n">local</span><span class="o">/</span><span class="n">archives</span>
<span class="o">--</span><span class="n">find</span><span class="o">-</span><span class="n">links</span> <span class="n">http</span><span class="p">:</span><span class="o">//</span><span class="n">some</span><span class="o">.</span><span class="n">archives</span><span class="o">.</span><span class="n">com</span><span class="o">/</span><span class="n">archives</span>
</pre></div>
</div>
<p>If you wish, you can refer to other requirements files, like this:</p>
<div class="highlight-default"><div class="highlight"><pre><span></span><span class="o">-</span><span class="n">r</span> <span class="n">more_requirements</span><span class="o">.</span><span class="n">txt</span>
</pre></div>
</div>
<p>You can also refer to <a class="reference internal" href="../user_guide.html#constraints-files"><span class="std std-ref">constraints files</span></a>, like this:</p>
<div class="highlight-default"><div class="highlight"><pre><span></span><span class="o">-</span><span class="n">c</span> <span class="n">some_constraints</span><span class="o">.</span><span class="n">txt</span>
</pre></div>
</div>
<div class="section" id="using-environment-variables">
<span id="id3"></span><h4><a class="toc-backref" href="#id27">Using Environment Variables</a><a class="headerlink" href="#using-environment-variables" title="Permalink to this headline">¶</a></h4>
<p>Since version 10, pip supports the use of environment variables inside the
requirements file. You can now store sensitive data (tokens, keys, etc.) in
environment variables and only specify the variable name for your requirements,
letting pip lookup the value at runtime. This approach aligns with the commonly
used <a class="reference external" href="https://12factor.net/config">12-factor configuration pattern</a>.</p>
<p>You have to use the POSIX format for variable names including brackets around
the uppercase name as shown in this example: <code class="docutils literal"><span class="pre">${API_TOKEN}</span></code>. pip will attempt
to find the corresponding environment variable defined on the host system at
runtime.</p>
<div class="admonition note">
<p class="first admonition-title">Note</p>
<p class="last">There is no support for other variable expansion syntaxes such as
<code class="docutils literal"><span class="pre">$VARIABLE</span></code> and <code class="docutils literal"><span class="pre">%VARIABLE%</span></code>.</p>
</div>
</div>
<div class="section" id="example-requirements-file">
<span id="id4"></span><h4><a class="toc-backref" href="#id28">Example Requirements File</a><a class="headerlink" href="#example-requirements-file" title="Permalink to this headline">¶</a></h4>
<p>Use <code class="docutils literal"><span class="pre">pip</span> <span class="pre">install</span> <span class="pre">-r</span> <span class="pre">example-requirements.txt</span></code> to install:</p>
<div class="highlight-default"><div class="highlight"><pre><span></span><span class="c1">#</span>
<span class="c1">####### example-requirements.txt #######</span>
<span class="c1">#</span>
<span class="c1">###### Requirements without Version Specifiers ######</span>
<span class="n">nose</span>
<span class="n">nose</span><span class="o">-</span><span class="n">cov</span>
<span class="n">beautifulsoup4</span>
<span class="c1">#</span>
<span class="c1">###### Requirements with Version Specifiers ######</span>
<span class="c1"># See https://www.python.org/dev/peps/pep-0440/#version-specifiers</span>
<span class="n">docopt</span> <span class="o">==</span> <span class="mf">0.6</span><span class="o">.</span><span class="mi">1</span> <span class="c1"># Version Matching. Must be version 0.6.1</span>
<span class="n">keyring</span> <span class="o">>=</span> <span class="mf">4.1</span><span class="o">.</span><span class="mi">1</span> <span class="c1"># Minimum version 4.1.1</span>
<span class="n">coverage</span> <span class="o">!=</span> <span class="mf">3.5</span> <span class="c1"># Version Exclusion. Anything except version 3.5</span>
<span class="n">Mopidy</span><span class="o">-</span><span class="n">Dirble</span> <span class="o">~=</span> <span class="mf">1.1</span> <span class="c1"># Compatible release. Same as >= 1.1, == 1.*</span>
<span class="c1">#</span>
<span class="c1">###### Refer to other requirements files ######</span>
<span class="o">-</span><span class="n">r</span> <span class="n">other</span><span class="o">-</span><span class="n">requirements</span><span class="o">.</span><span class="n">txt</span>
<span class="c1">#</span>
<span class="c1">#</span>
<span class="c1">###### A particular file ######</span>
<span class="o">./</span><span class="n">downloads</span><span class="o">/</span><span class="n">numpy</span><span class="o">-</span><span class="mf">1.9</span><span class="o">.</span><span class="mi">2</span><span class="o">-</span><span class="n">cp34</span><span class="o">-</span><span class="n">none</span><span class="o">-</span><span class="n">win32</span><span class="o">.</span><span class="n">whl</span>
<span class="n">http</span><span class="p">:</span><span class="o">//</span><span class="n">wxpython</span><span class="o">.</span><span class="n">org</span><span class="o">/</span><span class="n">Phoenix</span><span class="o">/</span><span class="n">snapshot</span><span class="o">-</span><span class="n">builds</span><span class="o">/</span><span class="n">wxPython_Phoenix</span><span class="o">-</span><span class="mf">3.0</span><span class="o">.</span><span class="mf">3.</span><span class="n">dev1820</span><span class="o">+</span><span class="mi">49</span><span class="n">a8884</span><span class="o">-</span><span class="n">cp34</span><span class="o">-</span><span class="n">none</span><span class="o">-</span><span class="n">win_amd64</span><span class="o">.</span><span class="n">whl</span>
<span class="c1">#</span>
<span class="c1">###### Additional Requirements without Version Specifiers ######</span>
<span class="c1"># Same as 1st section, just here to show that you can put things in any order.</span>
<span class="n">rejected</span>
<span class="n">green</span>
<span class="c1">#</span>
</pre></div>
</div>
</div>
</div>
<div class="section" id="requirement-specifiers">
<span id="id5"></span><h3><a class="toc-backref" href="#id29">Requirement Specifiers</a><a class="headerlink" href="#requirement-specifiers" title="Permalink to this headline">¶</a></h3>
<p>pip supports installing from a package index using a <span class="xref std std-term">requirement
specifier</span>. Generally speaking, a requirement
specifier is composed of a project name followed by optional <span class="xref std std-term">version
specifiers</span>. <span class="target" id="index-1"></span><a class="pep reference external" href="https://www.python.org/dev/peps/pep-0508"><strong>PEP 508</strong></a> contains a full specification
of the format of a requirement (<code class="docutils literal"><span class="pre">pip</span></code> does not support the <code class="docutils literal"><span class="pre">url_req</span></code> form
of specifier at this time).</p>
<p>Some examples:</p>
<blockquote>
<div><div class="highlight-default"><div class="highlight"><pre><span></span><span class="n">SomeProject</span>
<span class="n">SomeProject</span> <span class="o">==</span> <span class="mf">1.3</span>
<span class="n">SomeProject</span> <span class="o">>=</span><span class="mf">1.2</span><span class="p">,</span><span class="o"><</span><span class="mf">2.0</span>
<span class="n">SomeProject</span><span class="p">[</span><span class="n">foo</span><span class="p">,</span> <span class="n">bar</span><span class="p">]</span>
<span class="n">SomeProject</span><span class="o">~=</span><span class="mf">1.4</span><span class="o">.</span><span class="mi">2</span>
</pre></div>
</div>
</div></blockquote>
<p>Since version 6.0, pip also supports specifiers containing <a class="reference external" href="https://www.python.org/dev/peps/pep-0508/#environment-markers">environment markers</a> like so:</p>
<blockquote>
<div><div class="highlight-default"><div class="highlight"><pre><span></span><span class="n">SomeProject</span> <span class="o">==</span><span class="mf">5.4</span> <span class="p">;</span> <span class="n">python_version</span> <span class="o"><</span> <span class="s1">'2.7'</span>
<span class="n">SomeProject</span><span class="p">;</span> <span class="n">sys_platform</span> <span class="o">==</span> <span class="s1">'win32'</span>
</pre></div>
</div>
</div></blockquote>
<p>Environment markers are supported in the command line and in requirements files.</p>
<div class="admonition note">
<p class="first admonition-title">Note</p>
<p class="last">Use quotes around specifiers in the shell when using <code class="docutils literal"><span class="pre">></span></code>, <code class="docutils literal"><span class="pre"><</span></code>, or when
using environment markers. Don’t use quotes in requirement files. <a class="footnote-reference" href="#id17" id="id6">[1]</a></p>
</div>
</div>
<div class="section" id="per-requirement-overrides">
<span id="id7"></span><h3><a class="toc-backref" href="#id30">Per-requirement Overrides</a><a class="headerlink" href="#per-requirement-overrides" title="Permalink to this headline">¶</a></h3>
<p>Since version 7.0 pip supports controlling the command line options given to
<code class="docutils literal"><span class="pre">setup.py</span></code> via requirements files. This disables the use of wheels (cached or
otherwise) for that package, as <code class="docutils literal"><span class="pre">setup.py</span></code> does not exist for wheels.</p>
<p>The <code class="docutils literal"><span class="pre">--global-option</span></code> and <code class="docutils literal"><span class="pre">--install-option</span></code> options are used to pass
options to <code class="docutils literal"><span class="pre">setup.py</span></code>. For example:</p>
<blockquote>
<div><div class="highlight-default"><div class="highlight"><pre><span></span><span class="n">FooProject</span> <span class="o">>=</span> <span class="mf">1.2</span> <span class="o">--</span><span class="k">global</span><span class="o">-</span><span class="n">option</span><span class="o">=</span><span class="s2">"--no-user-cfg"</span> \
<span class="o">--</span><span class="n">install</span><span class="o">-</span><span class="n">option</span><span class="o">=</span><span class="s2">"--prefix='/usr/local'"</span> \
<span class="o">--</span><span class="n">install</span><span class="o">-</span><span class="n">option</span><span class="o">=</span><span class="s2">"--no-compile"</span>
</pre></div>
</div>
</div></blockquote>
<p>The above translates roughly into running FooProject’s <code class="docutils literal"><span class="pre">setup.py</span></code>
script as:</p>
<blockquote>
<div><div class="highlight-default"><div class="highlight"><pre><span></span><span class="n">python</span> <span class="n">setup</span><span class="o">.</span><span class="n">py</span> <span class="o">--</span><span class="n">no</span><span class="o">-</span><span class="n">user</span><span class="o">-</span><span class="n">cfg</span> <span class="n">install</span> <span class="o">--</span><span class="n">prefix</span><span class="o">=</span><span class="s1">'/usr/local'</span> <span class="o">--</span><span class="n">no</span><span class="o">-</span><span class="nb">compile</span>
</pre></div>
</div>
</div></blockquote>
<p>Note that the only way of giving more than one option to <code class="docutils literal"><span class="pre">setup.py</span></code>
is through multiple <code class="docutils literal"><span class="pre">--global-option</span></code> and <code class="docutils literal"><span class="pre">--install-option</span></code>
options, as shown in the example above. The value of each option is
passed as a single argument to the <code class="docutils literal"><span class="pre">setup.py</span></code> script. Therefore, a
line such as the following is invalid and would result in an
installation error.</p>
<div class="highlight-default"><div class="highlight"><pre><span></span><span class="c1"># Invalid. Please use '--install-option' twice as shown above.</span>
<span class="n">FooProject</span> <span class="o">>=</span> <span class="mf">1.2</span> <span class="o">--</span><span class="n">install</span><span class="o">-</span><span class="n">option</span><span class="o">=</span><span class="s2">"--prefix=/usr/local --no-compile"</span>
</pre></div>
</div>
</div>
<div class="section" id="pre-release-versions">
<span id="id8"></span><h3><a class="toc-backref" href="#id31">Pre-release Versions</a><a class="headerlink" href="#pre-release-versions" title="Permalink to this headline">¶</a></h3>
<p>Starting with v1.4, pip will only install stable versions as specified by
<a class="reference external" href="https://www.python.org/dev/peps/pep-0440/#handling-of-pre-releases">pre-releases</a> by default. If a version cannot be parsed as a compliant <span class="target" id="index-2"></span><a class="pep reference external" href="https://www.python.org/dev/peps/pep-0440"><strong>PEP 440</strong></a>
version then it is assumed to be a pre-release.</p>
<p>If a Requirement specifier includes a pre-release or development version
(e.g. <code class="docutils literal"><span class="pre">>=0.0.dev0</span></code>) then pip will allow pre-release and development versions
for that requirement. This does not include the != flag.</p>
<p>The <code class="docutils literal"><span class="pre">pip</span> <span class="pre">install</span></code> command also supports a <a class="reference internal" href="#install-pre"><span class="std std-ref">–pre</span></a> flag
that enables installation of pre-releases and development releases.</p>
</div>
<div class="section" id="vcs-support">
<span id="id9"></span><h3><a class="toc-backref" href="#id32">VCS Support</a><a class="headerlink" href="#vcs-support" title="Permalink to this headline">¶</a></h3>
<p>pip supports installing from Git, Mercurial, Subversion and Bazaar, and detects
the type of VCS using url prefixes: “git+”, “hg+”, “bzr+”, “svn+”.</p>
<p>pip requires a working VCS command on your path: git, hg, svn, or bzr.</p>
<p>VCS projects can be installed in <a class="reference internal" href="#editable-installs"><span class="std std-ref">editable mode</span></a> (using
the <a class="reference internal" href="#install-editable"><span class="std std-ref">–editable</span></a> option) or not.</p>
<ul class="simple">
<li>For editable installs, the clone location by default is “<venv
path>/src/SomeProject” in virtual environments, and “<cwd>/src/SomeProject”
for global installs. The <a class="reference internal" href="#install-src"><span class="std std-ref">–src</span></a> option can be used to
modify this location.</li>
<li>For non-editable installs, the project is built locally in a temp dir and then
installed normally. Note that if a satisfactory version of the package is
already installed, the VCS source will not overwrite it without an <cite>–upgrade</cite>
flag. VCS requirements pin the package version (specified in the <cite>setup.py</cite>
file) of the target commit, not necessarily the commit itself.</li>
<li>The <a class="reference internal" href="pip_freeze.html#pip-freeze"><span class="std std-ref">pip freeze</span></a> subcommand will record the VCS requirement specifier
(referencing a specific commit) if and only if the install is done using the
editable option.</li>
</ul>
<p>The “project name” component of the url suffix “egg=<project name>”
is used by pip in its dependency logic to identify the project prior
to pip downloading and analyzing the metadata. For projects
where setup.py is not in the root of project, “subdirectory” component
is used. Value of “subdirectory” component should be a path starting from root
of the project to where setup.py is located.</p>
<p>So if your repository layout is:</p>
<blockquote>
<div><ul class="simple">
<li>pkg_dir/<ul>
<li>setup.py # setup.py for package <code class="docutils literal"><span class="pre">pkg</span></code></li>
<li>some_module.py</li>
</ul>
</li>
<li>other_dir/<ul>
<li>some_file</li>
</ul>
</li>
<li>some_other_file</li>
</ul>
</div></blockquote>
<p>You’ll need to use <code class="docutils literal"><span class="pre">pip</span> <span class="pre">install</span> <span class="pre">-e</span> <span class="pre">vcs+protocol://repo_url/#egg=pkg&subdirectory=pkg_dir</span></code>.</p>
<div class="section" id="git">
<h4><a class="toc-backref" href="#id33">Git</a><a class="headerlink" href="#git" title="Permalink to this headline">¶</a></h4>
<p>pip currently supports cloning over <code class="docutils literal"><span class="pre">git</span></code>, <code class="docutils literal"><span class="pre">git+http</span></code>, <code class="docutils literal"><span class="pre">git+https</span></code>,
<code class="docutils literal"><span class="pre">git+ssh</span></code>, <code class="docutils literal"><span class="pre">git+git</span></code> and <code class="docutils literal"><span class="pre">git+file</span></code>:</p>
<p>Here are the supported forms:</p>
<div class="highlight-default"><div class="highlight"><pre><span></span><span class="p">[</span><span class="o">-</span><span class="n">e</span><span class="p">]</span> <span class="n">git</span><span class="p">:</span><span class="o">//</span><span class="n">git</span><span class="o">.</span><span class="n">example</span><span class="o">.</span><span class="n">com</span><span class="o">/</span><span class="n">MyProject</span><span class="c1">#egg=MyProject</span>
<span class="p">[</span><span class="o">-</span><span class="n">e</span><span class="p">]</span> <span class="n">git</span><span class="o">+</span><span class="n">http</span><span class="p">:</span><span class="o">//</span><span class="n">git</span><span class="o">.</span><span class="n">example</span><span class="o">.</span><span class="n">com</span><span class="o">/</span><span class="n">MyProject</span><span class="c1">#egg=MyProject</span>
<span class="p">[</span><span class="o">-</span><span class="n">e</span><span class="p">]</span> <span class="n">git</span><span class="o">+</span><span class="n">https</span><span class="p">:</span><span class="o">//</span><span class="n">git</span><span class="o">.</span><span class="n">example</span><span class="o">.</span><span class="n">com</span><span class="o">/</span><span class="n">MyProject</span><span class="c1">#egg=MyProject</span>
<span class="p">[</span><span class="o">-</span><span class="n">e</span><span class="p">]</span> <span class="n">git</span><span class="o">+</span><span class="n">ssh</span><span class="p">:</span><span class="o">//</span><span class="n">git</span><span class="o">.</span><span class="n">example</span><span class="o">.</span><span class="n">com</span><span class="o">/</span><span class="n">MyProject</span><span class="c1">#egg=MyProject</span>
<span class="p">[</span><span class="o">-</span><span class="n">e</span><span class="p">]</span> <span class="n">git</span><span class="o">+</span><span class="n">git</span><span class="p">:</span><span class="o">//</span><span class="n">git</span><span class="o">.</span><span class="n">example</span><span class="o">.</span><span class="n">com</span><span class="o">/</span><span class="n">MyProject</span><span class="c1">#egg=MyProject</span>
<span class="p">[</span><span class="o">-</span><span class="n">e</span><span class="p">]</span> <span class="n">git</span><span class="o">+</span><span class="n">file</span><span class="p">:</span><span class="o">///</span><span class="n">home</span><span class="o">/</span><span class="n">user</span><span class="o">/</span><span class="n">projects</span><span class="o">/</span><span class="n">MyProject</span><span class="c1">#egg=MyProject</span>
<span class="o">-</span><span class="n">e</span> <span class="n">git</span><span class="o">+</span><span class="n">git</span><span class="nd">@git</span><span class="o">.</span><span class="n">example</span><span class="o">.</span><span class="n">com</span><span class="p">:</span><span class="n">MyProject</span><span class="c1">#egg=MyProject</span>
</pre></div>
</div>
<p>Passing branch names, a commit hash or a tag name is possible like so:</p>
<div class="highlight-default"><div class="highlight"><pre><span></span><span class="p">[</span><span class="o">-</span><span class="n">e</span><span class="p">]</span> <span class="n">git</span><span class="p">:</span><span class="o">//</span><span class="n">git</span><span class="o">.</span><span class="n">example</span><span class="o">.</span><span class="n">com</span><span class="o">/</span><span class="n">MyProject</span><span class="o">.</span><span class="n">git</span><span class="nd">@master</span><span class="c1">#egg=MyProject</span>
<span class="p">[</span><span class="o">-</span><span class="n">e</span><span class="p">]</span> <span class="n">git</span><span class="p">:</span><span class="o">//</span><span class="n">git</span><span class="o">.</span><span class="n">example</span><span class="o">.</span><span class="n">com</span><span class="o">/</span><span class="n">MyProject</span><span class="o">.</span><span class="n">git</span><span class="nd">@v1</span><span class="o">.</span><span class="mi">0</span><span class="c1">#egg=MyProject</span>
<span class="p">[</span><span class="o">-</span><span class="n">e</span><span class="p">]</span> <span class="n">git</span><span class="p">:</span><span class="o">//</span><span class="n">git</span><span class="o">.</span><span class="n">example</span><span class="o">.</span><span class="n">com</span><span class="o">/</span><span class="n">MyProject</span><span class="o">.</span><span class="n">git</span><span class="nd">@da39a3ee5e6b4b0d3255bfef95601890afd80709</span><span class="c1">#egg=MyProject</span>
</pre></div>
</div>
<p>When passing a commit hash, specifying a full hash is preferable to a partial
hash because a full hash allows pip to operate more efficiently (e.g. by
making fewer network calls).</p>
</div>
<div class="section" id="mercurial">
<h4><a class="toc-backref" href="#id34">Mercurial</a><a class="headerlink" href="#mercurial" title="Permalink to this headline">¶</a></h4>
<p>The supported schemes are: <code class="docutils literal"><span class="pre">hg+http</span></code>, <code class="docutils literal"><span class="pre">hg+https</span></code>,
<code class="docutils literal"><span class="pre">hg+static-http</span></code> and <code class="docutils literal"><span class="pre">hg+ssh</span></code>.</p>
<p>Here are the supported forms:</p>
<div class="highlight-default"><div class="highlight"><pre><span></span><span class="p">[</span><span class="o">-</span><span class="n">e</span><span class="p">]</span> <span class="n">hg</span><span class="o">+</span><span class="n">http</span><span class="p">:</span><span class="o">//</span><span class="n">hg</span><span class="o">.</span><span class="n">myproject</span><span class="o">.</span><span class="n">org</span><span class="o">/</span><span class="n">MyProject</span><span class="c1">#egg=MyProject</span>
<span class="p">[</span><span class="o">-</span><span class="n">e</span><span class="p">]</span> <span class="n">hg</span><span class="o">+</span><span class="n">https</span><span class="p">:</span><span class="o">//</span><span class="n">hg</span><span class="o">.</span><span class="n">myproject</span><span class="o">.</span><span class="n">org</span><span class="o">/</span><span class="n">MyProject</span><span class="c1">#egg=MyProject</span>
<span class="p">[</span><span class="o">-</span><span class="n">e</span><span class="p">]</span> <span class="n">hg</span><span class="o">+</span><span class="n">ssh</span><span class="p">:</span><span class="o">//</span><span class="n">hg</span><span class="o">.</span><span class="n">myproject</span><span class="o">.</span><span class="n">org</span><span class="o">/</span><span class="n">MyProject</span><span class="c1">#egg=MyProject</span>
<span class="p">[</span><span class="o">-</span><span class="n">e</span><span class="p">]</span> <span class="n">hg</span><span class="o">+</span><span class="n">file</span><span class="p">:</span><span class="o">///</span><span class="n">home</span><span class="o">/</span><span class="n">user</span><span class="o">/</span><span class="n">projects</span><span class="o">/</span><span class="n">MyProject</span><span class="c1">#egg=MyProject</span>
</pre></div>
</div>
<p>You can also specify a revision number, a revision hash, a tag name or a local
branch name like so:</p>
<div class="highlight-default"><div class="highlight"><pre><span></span><span class="p">[</span><span class="o">-</span><span class="n">e</span><span class="p">]</span> <span class="n">hg</span><span class="o">+</span><span class="n">http</span><span class="p">:</span><span class="o">//</span><span class="n">hg</span><span class="o">.</span><span class="n">example</span><span class="o">.</span><span class="n">com</span><span class="o">/</span><span class="n">MyProject</span><span class="nd">@da39a3ee5e6b</span><span class="c1">#egg=MyProject</span>
<span class="p">[</span><span class="o">-</span><span class="n">e</span><span class="p">]</span> <span class="n">hg</span><span class="o">+</span><span class="n">http</span><span class="p">:</span><span class="o">//</span><span class="n">hg</span><span class="o">.</span><span class="n">example</span><span class="o">.</span><span class="n">com</span><span class="o">/</span><span class="n">MyProject</span><span class="nd">@2019</span><span class="c1">#egg=MyProject</span>
<span class="p">[</span><span class="o">-</span><span class="n">e</span><span class="p">]</span> <span class="n">hg</span><span class="o">+</span><span class="n">http</span><span class="p">:</span><span class="o">//</span><span class="n">hg</span><span class="o">.</span><span class="n">example</span><span class="o">.</span><span class="n">com</span><span class="o">/</span><span class="n">MyProject</span><span class="nd">@v1</span><span class="o">.</span><span class="mi">0</span><span class="c1">#egg=MyProject</span>
<span class="p">[</span><span class="o">-</span><span class="n">e</span><span class="p">]</span> <span class="n">hg</span><span class="o">+</span><span class="n">http</span><span class="p">:</span><span class="o">//</span><span class="n">hg</span><span class="o">.</span><span class="n">example</span><span class="o">.</span><span class="n">com</span><span class="o">/</span><span class="n">MyProject</span><span class="nd">@special_feature</span><span class="c1">#egg=MyProject</span>
</pre></div>
</div>
</div>
<div class="section" id="subversion">
<h4><a class="toc-backref" href="#id35">Subversion</a><a class="headerlink" href="#subversion" title="Permalink to this headline">¶</a></h4>
<p>pip supports the URL schemes <code class="docutils literal"><span class="pre">svn</span></code>, <code class="docutils literal"><span class="pre">svn+svn</span></code>, <code class="docutils literal"><span class="pre">svn+http</span></code>, <code class="docutils literal"><span class="pre">svn+https</span></code>, <code class="docutils literal"><span class="pre">svn+ssh</span></code>.</p>
<p>Here are some of the supported forms:</p>
<div class="highlight-default"><div class="highlight"><pre><span></span><span class="p">[</span><span class="o">-</span><span class="n">e</span><span class="p">]</span> <span class="n">svn</span><span class="o">+</span><span class="n">https</span><span class="p">:</span><span class="o">//</span><span class="n">svn</span><span class="o">.</span><span class="n">example</span><span class="o">.</span><span class="n">com</span><span class="o">/</span><span class="n">MyProject</span><span class="c1">#egg=MyProject</span>
<span class="p">[</span><span class="o">-</span><span class="n">e</span><span class="p">]</span> <span class="n">svn</span><span class="o">+</span><span class="n">ssh</span><span class="p">:</span><span class="o">//</span><span class="n">svn</span><span class="o">.</span><span class="n">example</span><span class="o">.</span><span class="n">com</span><span class="o">/</span><span class="n">MyProject</span><span class="c1">#egg=MyProject</span>
<span class="p">[</span><span class="o">-</span><span class="n">e</span><span class="p">]</span> <span class="n">svn</span><span class="o">+</span><span class="n">ssh</span><span class="p">:</span><span class="o">//</span><span class="n">user</span><span class="nd">@svn</span><span class="o">.</span><span class="n">example</span><span class="o">.</span><span class="n">com</span><span class="o">/</span><span class="n">MyProject</span><span class="c1">#egg=MyProject</span>
</pre></div>
</div>
<p>You can also give specific revisions to an SVN URL, like so:</p>
<div class="highlight-default"><div class="highlight"><pre><span></span><span class="p">[</span><span class="o">-</span><span class="n">e</span><span class="p">]</span> <span class="n">svn</span><span class="o">+</span><span class="n">svn</span><span class="p">:</span><span class="o">//</span><span class="n">svn</span><span class="o">.</span><span class="n">example</span><span class="o">.</span><span class="n">com</span><span class="o">/</span><span class="n">svn</span><span class="o">/</span><span class="n">MyProject</span><span class="c1">#egg=MyProject</span>
<span class="p">[</span><span class="o">-</span><span class="n">e</span><span class="p">]</span> <span class="n">svn</span><span class="o">+</span><span class="n">http</span><span class="p">:</span><span class="o">//</span><span class="n">svn</span><span class="o">.</span><span class="n">example</span><span class="o">.</span><span class="n">com</span><span class="o">/</span><span class="n">svn</span><span class="o">/</span><span class="n">MyProject</span><span class="o">/</span><span class="n">trunk</span><span class="nd">@2019</span><span class="c1">#egg=MyProject</span>
</pre></div>
</div>
<p>which will check out revision 2019. <code class="docutils literal"><span class="pre">@{20080101}</span></code> would also check
out the revision from 2008-01-01. You can only check out specific
revisions using <code class="docutils literal"><span class="pre">-e</span> <span class="pre">svn+...</span></code>.</p>
</div>
<div class="section" id="bazaar">
<h4><a class="toc-backref" href="#id36">Bazaar</a><a class="headerlink" href="#bazaar" title="Permalink to this headline">¶</a></h4>
<p>pip supports Bazaar using the <code class="docutils literal"><span class="pre">bzr+http</span></code>, <code class="docutils literal"><span class="pre">bzr+https</span></code>, <code class="docutils literal"><span class="pre">bzr+ssh</span></code>,
<code class="docutils literal"><span class="pre">bzr+sftp</span></code>, <code class="docutils literal"><span class="pre">bzr+ftp</span></code> and <code class="docutils literal"><span class="pre">bzr+lp</span></code> schemes.</p>
<p>Here are the supported forms:</p>
<div class="highlight-default"><div class="highlight"><pre><span></span><span class="p">[</span><span class="o">-</span><span class="n">e</span><span class="p">]</span> <span class="n">bzr</span><span class="o">+</span><span class="n">http</span><span class="p">:</span><span class="o">//</span><span class="n">bzr</span><span class="o">.</span><span class="n">example</span><span class="o">.</span><span class="n">com</span><span class="o">/</span><span class="n">MyProject</span><span class="o">/</span><span class="n">trunk</span><span class="c1">#egg=MyProject</span>
<span class="p">[</span><span class="o">-</span><span class="n">e</span><span class="p">]</span> <span class="n">bzr</span><span class="o">+</span><span class="n">sftp</span><span class="p">:</span><span class="o">//</span><span class="n">user</span><span class="nd">@example</span><span class="o">.</span><span class="n">com</span><span class="o">/</span><span class="n">MyProject</span><span class="o">/</span><span class="n">trunk</span><span class="c1">#egg=MyProject</span>
<span class="p">[</span><span class="o">-</span><span class="n">e</span><span class="p">]</span> <span class="n">bzr</span><span class="o">+</span><span class="n">ssh</span><span class="p">:</span><span class="o">//</span><span class="n">user</span><span class="nd">@example</span><span class="o">.</span><span class="n">com</span><span class="o">/</span><span class="n">MyProject</span><span class="o">/</span><span class="n">trunk</span><span class="c1">#egg=MyProject</span>
<span class="p">[</span><span class="o">-</span><span class="n">e</span><span class="p">]</span> <span class="n">bzr</span><span class="o">+</span><span class="n">ftp</span><span class="p">:</span><span class="o">//</span><span class="n">user</span><span class="nd">@example</span><span class="o">.</span><span class="n">com</span><span class="o">/</span><span class="n">MyProject</span><span class="o">/</span><span class="n">trunk</span><span class="c1">#egg=MyProject</span>
<span class="p">[</span><span class="o">-</span><span class="n">e</span><span class="p">]</span> <span class="n">bzr</span><span class="o">+</span><span class="n">lp</span><span class="p">:</span><span class="n">MyProject</span><span class="c1">#egg=MyProject</span>
</pre></div>
</div>
<p>Tags or revisions can be installed like so:</p>
<div class="highlight-default"><div class="highlight"><pre><span></span><span class="p">[</span><span class="o">-</span><span class="n">e</span><span class="p">]</span> <span class="n">bzr</span><span class="o">+</span><span class="n">https</span><span class="p">:</span><span class="o">//</span><span class="n">bzr</span><span class="o">.</span><span class="n">example</span><span class="o">.</span><span class="n">com</span><span class="o">/</span><span class="n">MyProject</span><span class="o">/</span><span class="n">trunk</span><span class="nd">@2019</span><span class="c1">#egg=MyProject</span>
<span class="p">[</span><span class="o">-</span><span class="n">e</span><span class="p">]</span> <span class="n">bzr</span><span class="o">+</span><span class="n">http</span><span class="p">:</span><span class="o">//</span><span class="n">bzr</span><span class="o">.</span><span class="n">example</span><span class="o">.</span><span class="n">com</span><span class="o">/</span><span class="n">MyProject</span><span class="o">/</span><span class="n">trunk</span><span class="nd">@v1</span><span class="o">.</span><span class="mi">0</span><span class="c1">#egg=MyProject</span>
</pre></div>
</div>
</div>
<div class="section" id="id10">
<h4><a class="toc-backref" href="#id37">Using Environment Variables</a><a class="headerlink" href="#id10" title="Permalink to this headline">¶</a></h4>
<p>Since version 10, pip also makes it possible to use environment variables which
makes it possible to reference private repositories without having to store
access tokens in the requirements file. For example, a private git repository
allowing Basic Auth for authentication can be refenced like this:</p>
<div class="highlight-default"><div class="highlight"><pre><span></span>[-e] git+http://${AUTH_USER}:${AUTH_PASSWORD}@git.example.com/MyProject#egg=MyProject
[-e] git+https://${AUTH_USER}:${AUTH_PASSWORD}@git.example.com/MyProject#egg=MyProject
</pre></div>
</div>
<div class="admonition note">
<p class="first admonition-title">Note</p>
<p class="last">Only <code class="docutils literal"><span class="pre">${VARIABLE}</span></code> is supported, other formats like <code class="docutils literal"><span class="pre">$VARIABLE</span></code> or
<code class="docutils literal"><span class="pre">%VARIABLE%</span></code> won’t work.</p>
</div>
</div>
</div>
<div class="section" id="finding-packages">
<h3><a class="toc-backref" href="#id38">Finding Packages</a><a class="headerlink" href="#finding-packages" title="Permalink to this headline">¶</a></h3>
<p>pip searches for packages on <a class="reference external" href="https://pypi.org/">PyPI</a> using the
<a class="reference external" href="https://pypi.org/simple/">http simple interface</a>,
which is documented <a class="reference external" href="https://setuptools.readthedocs.io/en/latest/easy_install.html#package-index-api">here</a>
and <a class="reference external" href="https://www.python.org/dev/peps/pep-0301/">there</a></p>
<p>pip offers a number of Package Index Options for modifying how packages are found.</p>
<p>pip looks for packages in a number of places, on PyPI (if not disabled via
<code class="docutils literal"><span class="pre">`--no-index`</span></code>), in the local filesystem, and in any additional repositories
specified via <code class="docutils literal"><span class="pre">`--find-links`</span></code> or <code class="docutils literal"><span class="pre">`--index-url`</span></code>. There is no ordering in
the locations that are searched, rather they are all checked, and the “best”
match for the requirements (in terms of version number - see <span class="target" id="index-3"></span><a class="pep reference external" href="https://www.python.org/dev/peps/pep-0440"><strong>PEP 440</strong></a> for
details) is selected.</p>
<p>See the <a class="reference internal" href="#pip-install-examples"><span class="std std-ref">pip install Examples</span></a>.</p>
</div>
<div class="section" id="ssl-certificate-verification">
<span id="id11"></span><h3><a class="toc-backref" href="#id39">SSL Certificate Verification</a><a class="headerlink" href="#ssl-certificate-verification" title="Permalink to this headline">¶</a></h3>
<p>Starting with v1.3, pip provides SSL certificate verification over https, to
prevent man-in-the-middle attacks against PyPI downloads.</p>
</div>
<div class="section" id="caching">
<span id="id12"></span><h3><a class="toc-backref" href="#id40">Caching</a><a class="headerlink" href="#caching" title="Permalink to this headline">¶</a></h3>
<p>Starting with v6.0, pip provides an on-by-default cache which functions
similarly to that of a web browser. While the cache is on by default and is
designed do the right thing by default you can disable the cache and always
access PyPI by utilizing the <code class="docutils literal"><span class="pre">--no-cache-dir</span></code> option.</p>
<p>When making any HTTP request pip will first check its local cache to determine
if it has a suitable response stored for that request which has not expired. If
it does then it simply returns that response and doesn’t make the request.</p>
<p>If it has a response stored, but it has expired, then it will attempt to make a
conditional request to refresh the cache which will either return an empty
response telling pip to simply use the cached item (and refresh the expiration
timer) or it will return a whole new response which pip can then store in the
cache.</p>
<p>When storing items in the cache, pip will respect the <code class="docutils literal"><span class="pre">CacheControl</span></code> header
if it exists, or it will fall back to the <code class="docutils literal"><span class="pre">Expires</span></code> header if that exists.
This allows pip to function as a browser would, and allows the index server
to communicate to pip how long it is reasonable to cache any particular item.</p>
<p>While this cache attempts to minimize network activity, it does not prevent
network access altogether. If you want a local install solution that
circumvents accessing PyPI, see <a class="reference internal" href="../user_guide.html#installing-from-local-packages"><span class="std std-ref">Installing from local packages</span></a>.</p>
<p>The default location for the cache directory depends on the Operating System:</p>
<dl class="docutils">
<dt>Unix</dt>
<dd><code class="file docutils literal"><span class="pre">~/.cache/pip</span></code> and it respects the <code class="docutils literal"><span class="pre">XDG_CACHE_HOME</span></code> directory.</dd>
<dt>macOS</dt>
<dd><code class="file docutils literal"><span class="pre">~/Library/Caches/pip</span></code>.</dd>
<dt>Windows</dt>
<dd><code class="file docutils literal"><span class="pre"><CSIDL_LOCAL_APPDATA>\pip\Cache</span></code></dd>
</dl>
<div class="section" id="wheel-cache">
<span id="id13"></span><h4><a class="toc-backref" href="#id41">Wheel Cache</a><a class="headerlink" href="#wheel-cache" title="Permalink to this headline">¶</a></h4>
<p>Pip will read from the subdirectory <code class="docutils literal"><span class="pre">wheels</span></code> within the pip cache directory
and use any packages found there. This is disabled via the same
<code class="docutils literal"><span class="pre">--no-cache-dir</span></code> option that disables the HTTP cache. The internal structure
of that is not part of the pip API. As of 7.0, pip makes a subdirectory for
each sdist that wheels are built from and places the resulting wheels inside.</p>
<p>Pip attempts to choose the best wheels from those built in preference to
building a new wheel. Note that this means when a package has both optional
C extensions and builds <cite>py</cite> tagged wheels when the C extension can’t be built
that pip will not attempt to build a better wheel for Pythons that would have
supported it, once any generic wheel is built. To correct this, make sure that
the wheels are built with Python specific tags - e.g. pp on PyPy.</p>
<p>When no wheels are found for an sdist, pip will attempt to build a wheel
automatically and insert it into the wheel cache.</p>
</div>
</div>
<div class="section" id="hash-checking-mode">
<span id="id14"></span><h3><a class="toc-backref" href="#id42">Hash-Checking Mode</a><a class="headerlink" href="#hash-checking-mode" title="Permalink to this headline">¶</a></h3>
<p>Since version 8.0, pip can check downloaded package archives against local
hashes to protect against remote tampering. To verify a package against one or
more hashes, add them to the end of the line:</p>
<div class="highlight-default"><div class="highlight"><pre><span></span><span class="n">FooProject</span> <span class="o">==</span> <span class="mf">1.2</span> <span class="o">--</span><span class="nb">hash</span><span class="o">=</span><span class="n">sha256</span><span class="p">:</span><span class="mi">2</span><span class="n">cf24dba5fb0a30e26e83b2ac5b9e29e1b161e5c1fa7425e73043362938b9824</span> \
<span class="o">--</span><span class="nb">hash</span><span class="o">=</span><span class="n">sha256</span><span class="p">:</span><span class="mi">486</span><span class="n">ea46224d1bb4fb680f34f7c9ad96a8f24ec88be73ea8e5a6c65260e9cb8a7</span>
</pre></div>
</div>
<p>(The ability to use multiple hashes is important when a package has both
binary and source distributions or when it offers binary distributions for a
variety of platforms.)</p>
<p>The recommended hash algorithm at the moment is sha256, but stronger ones are
allowed, including all those supported by <code class="docutils literal"><span class="pre">hashlib</span></code>. However, weaker ones
such as md5, sha1, and sha224 are excluded to avoid giving a false sense of
security.</p>
<p>Hash verification is an all-or-nothing proposition. Specifying a <code class="docutils literal"><span class="pre">--hash</span></code>
against any requirement not only checks that hash but also activates a global
<em>hash-checking mode</em>, which imposes several other security restrictions:</p>
<ul class="simple">
<li>Hashes are required for all requirements. This is because a partially-hashed
requirements file is of little use and thus likely an error: a malicious
actor could slip bad code into the installation via one of the unhashed
requirements. Note that hashes embedded in URL-style requirements via the
<code class="docutils literal"><span class="pre">#md5=...</span></code> syntax suffice to satisfy this rule (regardless of hash
strength, for legacy reasons), though you should use a stronger
hash like sha256 whenever possible.</li>
<li>Hashes are required for all dependencies. An error results if there is a
dependency that is not spelled out and hashed in the requirements file.</li>
<li>Requirements that take the form of project names (rather than URLs or local
filesystem paths) must be pinned to a specific version using <code class="docutils literal"><span class="pre">==</span></code>. This
prevents a surprising hash mismatch upon the release of a new version
that matches the requirement specifier.</li>
<li><code class="docutils literal"><span class="pre">--egg</span></code> is disallowed, because it delegates installation of dependencies
to setuptools, giving up pip’s ability to enforce any of the above.</li>
</ul>
<p id="require-hashes">Hash-checking mode can be forced on with the <code class="docutils literal"><span class="pre">--require-hashes</span></code> command-line
option:</p>
<div class="highlight-default"><div class="highlight"><pre><span></span>$ pip install --require-hashes -r requirements.txt
...
Hashes are required in --require-hashes mode (implicitly on when a hash is
specified for any package). These requirements were missing hashes,
leaving them open to tampering. These are the hashes the downloaded
archives actually had. You can add lines like these to your requirements
files to prevent tampering.
pyelasticsearch==1.0 --hash=sha256:44ddfb1225054d7d6b1d02e9338e7d4809be94edbe9929a2ec0807d38df993fa
more-itertools==2.2 --hash=sha256:93e62e05c7ad3da1a233def6731e8285156701e3419a5fe279017c429ec67ce0
</pre></div>
</div>
<p>This can be useful in deploy scripts, to ensure that the author of the
requirements file provided hashes. It is also a convenient way to bootstrap
your list of hashes, since it shows the hashes of the packages it fetched. It
fetches only the preferred archive for each package, so you may still need to
add hashes for alternatives archives using <a class="reference internal" href="pip_hash.html#pip-hash"><span class="std std-ref">pip hash</span></a>: for instance if
there is both a binary and a source distribution.</p>
<p>The <a class="reference internal" href="#wheel-cache"><span class="std std-ref">wheel cache</span></a> is disabled in hash-checking mode to
prevent spurious hash mismatch errors. These would otherwise occur while
installing sdists that had already been automatically built into cached wheels:
those wheels would be selected for installation, but their hashes would not
match the sdist ones from the requirements file. A further complication is that
locally built wheels are nondeterministic: contemporary modification times make
their way into the archive, making hashes unpredictable across machines and
cache flushes. Compilation of C code adds further nondeterminism, as many
compilers include random-seeded values in their output. However, wheels fetched
from index servers are the same every time. They land in pip’s HTTP cache, not
its wheel cache, and are used normally in hash-checking mode. The only downside
of having the wheel cache disabled is thus extra build time for sdists, and
this can be solved by making sure pre-built wheels are available from the index
server.</p>
<p>Hash-checking mode also works with <a class="reference internal" href="pip_download.html#pip-download"><span class="std std-ref">pip download</span></a> and <a class="reference internal" href="pip_wheel.html#pip-wheel"><span class="std std-ref">pip wheel</span></a>. A
<a class="reference internal" href="../user_guide.html#repeatability"><span class="std std-ref">comparison of hash-checking mode with other repeatability strategies</span></a> is available in the User Guide.</p>
<div class="admonition warning">
<p class="first admonition-title">Warning</p>
<p class="last">Beware of the <code class="docutils literal"><span class="pre">setup_requires</span></code> keyword arg in <code class="file docutils literal"><span class="pre">setup.py</span></code>. The
(rare) packages that use it will cause those dependencies to be downloaded
by setuptools directly, skipping pip’s hash-checking. If you need to use
such a package, see <a class="reference internal" href="#controlling-setup-requires"><span class="std std-ref">Controlling
setup_requires</span></a>.</p>
</div>
<div class="admonition warning">
<p class="first admonition-title">Warning</p>
<p>Be careful not to nullify all your security work when you install your
actual project by using setuptools directly: for example, by calling
<code class="docutils literal"><span class="pre">python</span> <span class="pre">setup.py</span> <span class="pre">install</span></code>, <code class="docutils literal"><span class="pre">python</span> <span class="pre">setup.py</span> <span class="pre">develop</span></code>, or
<code class="docutils literal"><span class="pre">easy_install</span></code>. Setuptools will happily go out and download, unchecked,
anything you missed in your requirements file—and it’s easy to miss things
as your project evolves. To be safe, install your project using pip and
<a class="reference internal" href="#install-no-deps"><span class="std std-ref">–no-deps</span></a>.</p>
<p>Instead of <code class="docutils literal"><span class="pre">python</span> <span class="pre">setup.py</span> <span class="pre">develop</span></code>, use…</p>
<div class="highlight-default"><div class="highlight"><pre><span></span><span class="n">pip</span> <span class="n">install</span> <span class="o">--</span><span class="n">no</span><span class="o">-</span><span class="n">deps</span> <span class="o">-</span><span class="n">e</span> <span class="o">.</span>
</pre></div>
</div>
<p>Instead of <code class="docutils literal"><span class="pre">python</span> <span class="pre">setup.py</span> <span class="pre">install</span></code>, use…</p>
<div class="last highlight-default"><div class="highlight"><pre><span></span><span class="n">pip</span> <span class="n">install</span> <span class="o">--</span><span class="n">no</span><span class="o">-</span><span class="n">deps</span> <span class="o">.</span>
</pre></div>
</div>
</div>
<div class="section" id="hashes-from-pypi">
<h4><a class="toc-backref" href="#id43">Hashes from PyPI</a><a class="headerlink" href="#hashes-from-pypi" title="Permalink to this headline">¶</a></h4>
<p>PyPI provides an MD5 hash in the fragment portion of each package download URL,
like <code class="docutils literal"><span class="pre">#md5=123...</span></code>, which pip checks as a protection against download
corruption. Other hash algorithms that have guaranteed support from <code class="docutils literal"><span class="pre">hashlib</span></code>
are also supported here: sha1, sha224, sha384, sha256, and sha512. Since this
hash originates remotely, it is not a useful guard against tampering and thus
does not satisfy the <code class="docutils literal"><span class="pre">--require-hashes</span></code> demand that every package have a
local hash.</p>
</div>
</div>
<div class="section" id="editable-installs">
<span id="id15"></span><h3><a class="toc-backref" href="#id44">“Editable” Installs</a><a class="headerlink" href="#editable-installs" title="Permalink to this headline">¶</a></h3>
<p>“Editable” installs are fundamentally <a class="reference external" href="https://setuptools.readthedocs.io/en/latest/setuptools.html#development-mode">“setuptools develop mode”</a>
installs.</p>
<p>You can install local projects or VCS projects in “editable” mode:</p>
<div class="highlight-default"><div class="highlight"><pre><span></span>$ pip install -e path/to/SomeProject
$ pip install -e git+http://repo/my_project.git#egg=SomeProject
</pre></div>
</div>
<p>(See the <a class="reference internal" href="#vcs-support"><span class="std std-ref">VCS Support</span></a> section above for more information on VCS-related syntax.)</p>
<p>For local projects, the “SomeProject.egg-info” directory is created relative to
the project path. This is one advantage over just using <code class="docutils literal"><span class="pre">setup.py</span> <span class="pre">develop</span></code>,
which creates the “egg-info” directly relative the current working directory.</p>
</div>
<div class="section" id="controlling-setup-requires">
<span id="id16"></span><h3><a class="toc-backref" href="#id45">Controlling setup_requires</a><a class="headerlink" href="#controlling-setup-requires" title="Permalink to this headline">¶</a></h3>
<p>Setuptools offers the <code class="docutils literal"><span class="pre">setup_requires</span></code> <a class="reference external" href="https://setuptools.readthedocs.io/en/latest/setuptools.html#new-and-changed-setup-keywords">setup() keyword</a>
for specifying dependencies that need to be present in order for the <cite>setup.py</cite>
script to run. Internally, Setuptools uses <code class="docutils literal"><span class="pre">easy_install</span></code> to fulfill these
dependencies.</p>
<p>pip has no way to control how these dependencies are located. None of the
Package Index Options have an effect.</p>
<p>The solution is to configure a “system” or “personal” <a class="reference external" href="https://docs.python.org/3/install/index.html#distutils-configuration-files">Distutils configuration
file</a> to
manage the fulfillment.</p>
<p>For example, to have the dependency located at an alternate index, add this:</p>
<div class="highlight-default"><div class="highlight"><pre><span></span><span class="p">[</span><span class="n">easy_install</span><span class="p">]</span>
<span class="n">index_url</span> <span class="o">=</span> <span class="n">https</span><span class="p">:</span><span class="o">//</span><span class="n">my</span><span class="o">.</span><span class="n">index</span><span class="o">-</span><span class="n">mirror</span><span class="o">.</span><span class="n">com</span>
</pre></div>
</div>
<p>To have the dependency located from a local directory and not crawl PyPI, add this:</p>
<div class="highlight-default"><div class="highlight"><pre><span></span><span class="p">[</span><span class="n">easy_install</span><span class="p">]</span>
<span class="n">allow_hosts</span> <span class="o">=</span> <span class="s1">''</span>
<span class="n">find_links</span> <span class="o">=</span> <span class="n">file</span><span class="p">:</span><span class="o">///</span><span class="n">path</span><span class="o">/</span><span class="n">to</span><span class="o">/</span><span class="n">local</span><span class="o">/</span><span class="n">archives</span><span class="o">/</span>
</pre></div>
</div>
</div>
<div class="section" id="build-system-interface">
<h3><a class="toc-backref" href="#id46">Build System Interface</a><a class="headerlink" href="#build-system-interface" title="Permalink to this headline">¶</a></h3>
<p>In order for pip to install a package from source, <code class="docutils literal"><span class="pre">setup.py</span></code> must implement
the following commands:</p>
<div class="highlight-default"><div class="highlight"><pre><span></span><span class="n">setup</span><span class="o">.</span><span class="n">py</span> <span class="n">egg_info</span> <span class="p">[</span><span class="o">--</span><span class="n">egg</span><span class="o">-</span><span class="n">base</span> <span class="n">XXX</span><span class="p">]</span>
<span class="n">setup</span><span class="o">.</span><span class="n">py</span> <span class="n">install</span> <span class="o">--</span><span class="n">record</span> <span class="n">XXX</span> <span class="p">[</span><span class="o">--</span><span class="n">single</span><span class="o">-</span><span class="n">version</span><span class="o">-</span><span class="n">externally</span><span class="o">-</span><span class="n">managed</span><span class="p">]</span> <span class="p">[</span><span class="o">--</span><span class="n">root</span> <span class="n">XXX</span><span class="p">]</span> <span class="p">[</span><span class="o">--</span><span class="nb">compile</span><span class="o">|--</span><span class="n">no</span><span class="o">-</span><span class="nb">compile</span><span class="p">]</span> <span class="p">[</span><span class="o">--</span><span class="n">install</span><span class="o">-</span><span class="n">headers</span> <span class="n">XXX</span><span class="p">]</span>
</pre></div>
</div>
<p>The <code class="docutils literal"><span class="pre">egg_info</span></code> command should create egg metadata for the package, as
described in the setuptools documentation at
<a class="reference external" href="https://setuptools.readthedocs.io/en/latest/setuptools.html#egg-info-create-egg-metadata-and-set-build-tags">https://setuptools.readthedocs.io/en/latest/setuptools.html#egg-info-create-egg-metadata-and-set-build-tags</a></p>
<p>The <code class="docutils literal"><span class="pre">install</span></code> command should implement the complete process of installing the
package to the target directory XXX.</p>
<p>To install a package in “editable” mode (<code class="docutils literal"><span class="pre">pip</span> <span class="pre">install</span> <span class="pre">-e</span></code>), <code class="docutils literal"><span class="pre">setup.py</span></code> must
implement the following command:</p>
<div class="highlight-default"><div class="highlight"><pre><span></span><span class="n">setup</span><span class="o">.</span><span class="n">py</span> <span class="n">develop</span> <span class="o">--</span><span class="n">no</span><span class="o">-</span><span class="n">deps</span>
</pre></div>
</div>
<p>This should implement the complete process of installing the package in
“editable” mode.</p>
<p>All packages will be attempted to built into wheels:</p>
<div class="highlight-default"><div class="highlight"><pre><span></span><span class="n">setup</span><span class="o">.</span><span class="n">py</span> <span class="n">bdist_wheel</span> <span class="o">-</span><span class="n">d</span> <span class="n">XXX</span>
</pre></div>
</div>
<p>One further <code class="docutils literal"><span class="pre">setup.py</span></code> command is invoked by <code class="docutils literal"><span class="pre">pip</span> <span class="pre">install</span></code>:</p>
<div class="highlight-default"><div class="highlight"><pre><span></span><span class="n">setup</span><span class="o">.</span><span class="n">py</span> <span class="n">clean</span>
</pre></div>
</div>
<p>This command is invoked to clean up temporary commands from the build. (TODO:
Investigate in more detail when this command is required).</p>
<p>No other build system commands are invoked by the <code class="docutils literal"><span class="pre">pip</span> <span class="pre">install</span></code> command.</p>
<p>Installing a package from a wheel does not invoke the build system at all.</p>
</div>
</div>
<div class="section" id="options">
<span id="pip-install-options"></span><h2><a class="toc-backref" href="#id47">Options</a><a class="headerlink" href="#options" title="Permalink to this headline">¶</a></h2>
<p><span class="target" id="install-requirement"></span><dl class="option">
<dt id="cmdoption-r">
<code class="descname">-r</code><code class="descclassname"></code><code class="descclassname">, </code><code class="descname">--requirement</code><code class="descclassname"> <file></code><a class="headerlink" href="#cmdoption-r" title="Permalink to this definition">¶</a></dt>
<dd><p>Install from the given requirements file. This option can be used multiple times.</p>
</dd></dl>
<span class="target" id="install-constraint"></span><dl class="option">
<dt id="cmdoption-c">
<code class="descname">-c</code><code class="descclassname"></code><code class="descclassname">, </code><code class="descname">--constraint</code><code class="descclassname"> <file></code><a class="headerlink" href="#cmdoption-c" title="Permalink to this definition">¶</a></dt>
<dd><p>Constrain versions using the given constraints file. This option can be used multiple times.</p>
</dd></dl>
<span class="target" id="install-no-deps"></span><dl class="option">
<dt id="cmdoption-no-deps">
<code class="descname">--no-deps</code><code class="descclassname"></code><a class="headerlink" href="#cmdoption-no-deps" title="Permalink to this definition">¶</a></dt>
<dd><p>Don’t install package dependencies.</p>
</dd></dl>
<span class="target" id="install-pre"></span><dl class="option">
<dt id="cmdoption-pre">
<code class="descname">--pre</code><code class="descclassname"></code><a class="headerlink" href="#cmdoption-pre" title="Permalink to this definition">¶</a></dt>
<dd><p>Include pre-release and development versions. By default, pip only finds stable versions.</p>
</dd></dl>
<span class="target" id="install-editable"></span><dl class="option">
<dt id="cmdoption-e">
<code class="descname">-e</code><code class="descclassname"></code><code class="descclassname">, </code><code class="descname">--editable</code><code class="descclassname"> <path/url></code><a class="headerlink" href="#cmdoption-e" title="Permalink to this definition">¶</a></dt>
<dd><p>Install a project in editable mode (i.e. setuptools “develop mode”) from a local project path or a VCS url.</p>
</dd></dl>
<span class="target" id="install-target"></span><dl class="option">
<dt id="cmdoption-t">
<code class="descname">-t</code><code class="descclassname"></code><code class="descclassname">, </code><code class="descname">--target</code><code class="descclassname"> <dir></code><a class="headerlink" href="#cmdoption-t" title="Permalink to this definition">¶</a></dt>
<dd><p>Install packages into <dir>. By default this will not replace existing files/folders in <dir>. Use –upgrade to replace existing packages in <dir> with new versions.</p>
</dd></dl>
<span class="target" id="install-platform"></span><dl class="option">
<dt id="cmdoption-platform">
<code class="descname">--platform</code><code class="descclassname"> <platform></code><a class="headerlink" href="#cmdoption-platform" title="Permalink to this definition">¶</a></dt>
<dd><p>Only use wheels compatible with <platform>. Defaults to the platform of the running system.</p>
</dd></dl>
<span class="target" id="install-python-version"></span><dl class="option">
<dt id="cmdoption-python-version">
<code class="descname">--python-version</code><code class="descclassname"> <python_version></code><a class="headerlink" href="#cmdoption-python-version" title="Permalink to this definition">¶</a></dt>
<dd><p>Only use wheels compatible with Python interpreter version <version>. If not specified, then the current system interpreter minor version is used. A major version (e.g. ‘2’) can be specified to match all minor revs of that major version. A minor version (e.g. ‘34’) can also be specified.</p>
</dd></dl>
<span class="target" id="install-implementation"></span><dl class="option">
<dt id="cmdoption-implementation">
<code class="descname">--implementation</code><code class="descclassname"> <implementation></code><a class="headerlink" href="#cmdoption-implementation" title="Permalink to this definition">¶</a></dt>
<dd><p>Only use wheels compatible with Python implementation <implementation>, e.g. ‘pp’, ‘jy’, ‘cp’, or ‘ip’. If not specified, then the current interpreter implementation is used. Use ‘py’ to force implementation-agnostic wheels.</p>
</dd></dl>
<span class="target" id="install-abi"></span><dl class="option">
<dt id="cmdoption-abi">
<code class="descname">--abi</code><code class="descclassname"> <abi></code><a class="headerlink" href="#cmdoption-abi" title="Permalink to this definition">¶</a></dt>
<dd><p>Only use wheels compatible with Python abi <abi>, e.g. ‘pypy_41’. If not specified, then the current interpreter abi tag is used. Generally you will need to specify –implementation, –platform, and –python-version when using this option.</p>
</dd></dl>
<span class="target" id="install-user"></span><dl class="option">
<dt id="cmdoption-user">
<code class="descname">--user</code><code class="descclassname"></code><a class="headerlink" href="#cmdoption-user" title="Permalink to this definition">¶</a></dt>
<dd><p>Install to the Python user install directory for your platform. Typically ~/.local/, or %APPDATA%Python on Windows. (See the Python documentation for site.USER_BASE for full details.)</p>
</dd></dl>
<span class="target" id="install-root"></span><dl class="option">
<dt id="cmdoption-root">
<code class="descname">--root</code><code class="descclassname"> <dir></code><a class="headerlink" href="#cmdoption-root" title="Permalink to this definition">¶</a></dt>
<dd><p>Install everything relative to this alternate root directory.</p>
</dd></dl>
<span class="target" id="install-prefix"></span><dl class="option">
<dt id="cmdoption-prefix">
<code class="descname">--prefix</code><code class="descclassname"> <dir></code><a class="headerlink" href="#cmdoption-prefix" title="Permalink to this definition">¶</a></dt>
<dd><p>Installation prefix where lib, bin and other top-level folders are placed</p>
</dd></dl>
<span class="target" id="install-build"></span><dl class="option">
<dt id="cmdoption-b">
<code class="descname">-b</code><code class="descclassname"></code><code class="descclassname">, </code><code class="descname">--build</code><code class="descclassname"> <dir></code><a class="headerlink" href="#cmdoption-b" title="Permalink to this definition">¶</a></dt>
<dd><p>Directory to unpack packages into and build in. Note that an initial build still takes place in a temporary directory. The location of temporary directories can be controlled by setting the TMPDIR environment variable (TEMP on Windows) appropriately. When passed, build directories are not cleaned in case of failures.</p>
</dd></dl>
<span class="target" id="install-src"></span><dl class="option">
<dt id="cmdoption-src">
<code class="descname">--src</code><code class="descclassname"> <dir></code><a class="headerlink" href="#cmdoption-src" title="Permalink to this definition">¶</a></dt>
<dd><p>Directory to check out editable projects into. The default in a virtualenv is “<venv path>/src”. The default for global installs is “<current dir>/src”.</p>
</dd></dl>
<span class="target" id="install-upgrade"></span><dl class="option">
<dt id="cmdoption-u">
<code class="descname">-U</code><code class="descclassname"></code><code class="descclassname">, </code><code class="descname">--upgrade</code><code class="descclassname"></code><a class="headerlink" href="#cmdoption-u" title="Permalink to this definition">¶</a></dt>
<dd><p>Upgrade all specified packages to the newest available version. The handling of dependencies depends on the upgrade-strategy used.</p>
</dd></dl>
<span class="target" id="install-upgrade-strategy"></span><dl class="option">
<dt id="cmdoption-upgrade-strategy">
<code class="descname">--upgrade-strategy</code><code class="descclassname"> <upgrade_strategy></code><a class="headerlink" href="#cmdoption-upgrade-strategy" title="Permalink to this definition">¶</a></dt>
<dd><p>Determines how dependency upgrading should be handled [default: only-if-needed]. “eager” - dependencies are upgraded regardless of whether the currently installed version satisfies the requirements of the upgraded package(s). “only-if-needed” - are upgraded only when they do not satisfy the requirements of the upgraded package(s).</p>
</dd></dl>
<span class="target" id="install-force-reinstall"></span><dl class="option">
<dt id="cmdoption-force-reinstall">
<code class="descname">--force-reinstall</code><code class="descclassname"></code><a class="headerlink" href="#cmdoption-force-reinstall" title="Permalink to this definition">¶</a></dt>
<dd><p>Reinstall all packages even if they are already up-to-date.</p>
</dd></dl>
<span class="target" id="install-ignore-installed"></span><dl class="option">
<dt id="cmdoption-i">
<code class="descname">-I</code><code class="descclassname"></code><code class="descclassname">, </code><code class="descname">--ignore-installed</code><code class="descclassname"></code><a class="headerlink" href="#cmdoption-i" title="Permalink to this definition">¶</a></dt>
<dd><p>Ignore the installed packages (reinstalling instead).</p>
</dd></dl>
<span class="target" id="install-ignore-requires-python"></span><dl class="option">
<dt id="cmdoption-ignore-requires-python">
<code class="descname">--ignore-requires-python</code><code class="descclassname"></code><a class="headerlink" href="#cmdoption-ignore-requires-python" title="Permalink to this definition">¶</a></dt>
<dd><p>Ignore the Requires-Python information.</p>
</dd></dl>
<span class="target" id="install-no-build-isolation"></span><dl class="option">
<dt id="cmdoption-no-build-isolation">
<code class="descname">--no-build-isolation</code><code class="descclassname"></code><a class="headerlink" href="#cmdoption-no-build-isolation" title="Permalink to this definition">¶</a></dt>
<dd><p>Disable isolation when building a modern source distribution. Build dependencies specified by PEP 518 must be already installed if this option is used.</p>
</dd></dl>
<span class="target" id="install-use-pep517"></span><dl class="option">
<dt id="cmdoption-use-pep517">
<code class="descname">--use-pep517</code><code class="descclassname"></code><a class="headerlink" href="#cmdoption-use-pep517" title="Permalink to this definition">¶</a></dt>
<dd><p>Use PEP 517 for building source distributions (use –no-use-pep517 to force legacy behaviour).</p>
</dd></dl>
<span class="target" id="install-install-option"></span><dl class="option">
<dt id="cmdoption-install-option">
<code class="descname">--install-option</code><code class="descclassname"> <options></code><a class="headerlink" href="#cmdoption-install-option" title="Permalink to this definition">¶</a></dt>
<dd><p>Extra arguments to be supplied to the setup.py install command (use like –install-option=”–install-scripts=<sys.prefix>/bin”). Use multiple –install-option options to pass multiple options to setup.py install. If you are using an option with a directory path, be sure to use absolute path.</p>
</dd></dl>
<span class="target" id="install-global-option"></span><dl class="option">
<dt id="cmdoption-global-option">
<code class="descname">--global-option</code><code class="descclassname"> <options></code><a class="headerlink" href="#cmdoption-global-option" title="Permalink to this definition">¶</a></dt>
<dd><p>Extra global options to be supplied to the setup.py call before the install command.</p>
</dd></dl>
<span class="target" id="install-compile"></span><dl class="option">
<dt id="cmdoption-compile">
<code class="descname">--compile</code><code class="descclassname"></code><a class="headerlink" href="#cmdoption-compile" title="Permalink to this definition">¶</a></dt>
<dd><p>Compile Python source files to bytecode</p>
</dd></dl>
<span class="target" id="install-no-compile"></span><dl class="option">
<dt id="cmdoption-no-compile">
<code class="descname">--no-compile</code><code class="descclassname"></code><a class="headerlink" href="#cmdoption-no-compile" title="Permalink to this definition">¶</a></dt>
<dd><p>Do not compile Python source files to bytecode</p>
</dd></dl>
<span class="target" id="install-no-warn-script-location"></span><dl class="option">
<dt id="cmdoption-no-warn-script-location">
<code class="descname">--no-warn-script-location</code><code class="descclassname"></code><a class="headerlink" href="#cmdoption-no-warn-script-location" title="Permalink to this definition">¶</a></dt>
<dd><p>Do not warn when installing scripts outside PATH</p>
</dd></dl>
<span class="target" id="install-no-warn-conflicts"></span><dl class="option">
<dt id="cmdoption-no-warn-conflicts">
<code class="descname">--no-warn-conflicts</code><code class="descclassname"></code><a class="headerlink" href="#cmdoption-no-warn-conflicts" title="Permalink to this definition">¶</a></dt>
<dd><p>Do not warn about broken dependencies</p>
</dd></dl>
<span class="target" id="install-no-binary"></span><dl class="option">
<dt id="cmdoption-no-binary">
<code class="descname">--no-binary</code><code class="descclassname"> <format_control></code><a class="headerlink" href="#cmdoption-no-binary" title="Permalink to this definition">¶</a></dt>
<dd><p>Do not use binary packages. Can be supplied multiple times, and each time adds to the existing value. Accepts either :all: to disable all binary packages, :none: to empty the set, or one or more package names with commas between them. Note that some packages are tricky to compile and may fail to install when this option is used on them.</p>
</dd></dl>
<span class="target" id="install-only-binary"></span><dl class="option">
<dt id="cmdoption-only-binary">
<code class="descname">--only-binary</code><code class="descclassname"> <format_control></code><a class="headerlink" href="#cmdoption-only-binary" title="Permalink to this definition">¶</a></dt>
<dd><p>Do not use source packages. Can be supplied multiple times, and each time adds to the existing value. Accepts either :all: to disable all source packages, :none: to empty the set, or one or more package names with commas between them. Packages without binary distributions will fail to install when this option is used on them.</p>
</dd></dl>
<span class="target" id="install-prefer-binary"></span><dl class="option">
<dt id="cmdoption-prefer-binary">
<code class="descname">--prefer-binary</code><code class="descclassname"></code><a class="headerlink" href="#cmdoption-prefer-binary" title="Permalink to this definition">¶</a></dt>
<dd><p>Prefer older binary packages over newer source packages.</p>
</dd></dl>
<span class="target" id="install-no-clean"></span><dl class="option">
<dt id="cmdoption-no-clean">
<code class="descname">--no-clean</code><code class="descclassname"></code><a class="headerlink" href="#cmdoption-no-clean" title="Permalink to this definition">¶</a></dt>
<dd><p>Don’t clean up build directories.</p>
</dd></dl>
<span class="target" id="install-require-hashes"></span><dl class="option">
<dt id="cmdoption-require-hashes">
<code class="descname">--require-hashes</code><code class="descclassname"></code><a class="headerlink" href="#cmdoption-require-hashes" title="Permalink to this definition">¶</a></dt>
<dd><p>Require a hash to check each requirement against, for repeatable installs. This option is implied when any package in a requirements file has a –hash option.</p>
</dd></dl>
<span class="target" id="install-progress-bar"></span><dl class="option">
<dt id="cmdoption-progress-bar">
<code class="descname">--progress-bar</code><code class="descclassname"> <progress_bar></code><a class="headerlink" href="#cmdoption-progress-bar" title="Permalink to this definition">¶</a></dt>
<dd><p>Specify type of progress to be displayed [off|on|ascii|pretty|emoji] (default: on)</p>
</dd></dl>
</p>
<p><span class="target" id="index-url"></span><dl class="option">
<dt id="cmdoption-index-url">
<code class="descname">-i</code><code class="descclassname"></code><code class="descclassname">, </code><code class="descname">--index-url</code><code class="descclassname"> <url></code><a class="headerlink" href="#cmdoption-index-url" title="Permalink to this definition">¶</a></dt>
<dd><p>Base URL of Python Package Index (default <a class="reference external" href="https://pypi.org/simple">https://pypi.org/simple</a>). This should point to a repository compliant with PEP 503 (the simple repository API) or a local directory laid out in the same format.</p>
</dd></dl>
<span class="target" id="extra-index-url"></span><dl class="option">
<dt id="cmdoption-extra-index-url">
<code class="descname">--extra-index-url</code><code class="descclassname"> <url></code><a class="headerlink" href="#cmdoption-extra-index-url" title="Permalink to this definition">¶</a></dt>
<dd><p>Extra URLs of package indexes to use in addition to –index-url. Should follow the same rules as –index-url.</p>
</dd></dl>
<span class="target" id="no-index"></span><dl class="option">
<dt id="cmdoption-no-index">
<code class="descname">--no-index</code><code class="descclassname"></code><a class="headerlink" href="#cmdoption-no-index" title="Permalink to this definition">¶</a></dt>
<dd><p>Ignore package index (only looking at –find-links URLs instead).</p>
</dd></dl>
<span class="target" id="find-links"></span><dl class="option">
<dt id="cmdoption-f">
<code class="descname">-f</code><code class="descclassname"></code><code class="descclassname">, </code><code class="descname">--find-links</code><code class="descclassname"> <url></code><a class="headerlink" href="#cmdoption-f" title="Permalink to this definition">¶</a></dt>
<dd><p>If a url or path to an html file, then parse for links to archives. If a local path or <a class="reference external" href="file://">file://</a> url that’s a directory, then look for archives in the directory listing.</p>
</dd></dl>
</p>
</div>
<div class="section" id="examples">
<span id="pip-install-examples"></span><h2><a class="toc-backref" href="#id48">Examples</a><a class="headerlink" href="#examples" title="Permalink to this headline">¶</a></h2>
<ol class="arabic">
<li><p class="first">Install <cite>SomePackage</cite> and its dependencies from <a class="reference external" href="https://pypi.org/">PyPI</a> using <a class="reference internal" href="#requirement-specifiers"><span class="std std-ref">Requirement Specifiers</span></a></p>
<blockquote>
<div><div class="highlight-default"><div class="highlight"><pre><span></span>$ pip install SomePackage # latest version
$ pip install SomePackage==1.0.4 # specific version
$ pip install 'SomePackage>=1.0.4' # minimum version
</pre></div>
</div>
</div></blockquote>
</li>
<li><p class="first">Install a list of requirements specified in a file. See the <a class="reference internal" href="../user_guide.html#requirements-files"><span class="std std-ref">Requirements files</span></a>.</p>
<blockquote>
<div><div class="highlight-default"><div class="highlight"><pre><span></span>$ pip install -r requirements.txt
</pre></div>
</div>
</div></blockquote>
</li>
<li><p class="first">Upgrade an already installed <cite>SomePackage</cite> to the latest from PyPI.</p>
<blockquote>
<div><div class="highlight-default"><div class="highlight"><pre><span></span>$ pip install --upgrade SomePackage
</pre></div>
</div>
</div></blockquote>
</li>
<li><p class="first">Install a local project in “editable” mode. See the section on <a class="reference internal" href="#editable-installs"><span class="std std-ref">Editable Installs</span></a>.</p>
<blockquote>
<div><div class="highlight-default"><div class="highlight"><pre><span></span>$ pip install -e . # project in current directory
$ pip install -e path/to/project # project in another directory
</pre></div>
</div>
</div></blockquote>
</li>
<li><p class="first">Install a project from VCS in “editable” mode. See the sections on <a class="reference internal" href="#vcs-support"><span class="std std-ref">VCS Support</span></a> and <a class="reference internal" href="#editable-installs"><span class="std std-ref">Editable Installs</span></a>.</p>
<blockquote>
<div><div class="highlight-default"><div class="highlight"><pre><span></span>$ pip install -e git+https://git.repo/some_pkg.git#egg=SomePackage # from git
$ pip install -e hg+https://hg.repo/some_pkg.git#egg=SomePackage # from mercurial
$ pip install -e svn+svn://svn.repo/some_pkg/trunk/#egg=SomePackage # from svn
$ pip install -e git+https://git.repo/some_pkg.git@feature#egg=SomePackage # from 'feature' branch
$ pip install -e "git+https://git.repo/some_repo.git#egg=subdir&subdirectory=subdir_path" # install a python package from a repo subdirectory
</pre></div>
</div>
</div></blockquote>
</li>
<li><p class="first">Install a package with <a class="reference external" href="https://setuptools.readthedocs.io/en/latest/setuptools.html#declaring-extras-optional-features-with-their-own-dependencies">setuptools extras</a>.</p>
<blockquote>
<div><div class="highlight-default"><div class="highlight"><pre><span></span>$ pip install SomePackage[PDF]
$ pip install git+https://git.repo/some_pkg.git#egg=SomePackage[PDF]
$ pip install SomePackage[PDF]==3.0
$ pip install -e .[PDF]==3.0 # editable project in current directory
$ pip install SomePackage[PDF,EPUB] # multiple extras
</pre></div>
</div>
</div></blockquote>
</li>
<li><p class="first">Install a particular source archive file.</p>
<blockquote>
<div><div class="highlight-default"><div class="highlight"><pre><span></span>$ pip install ./downloads/SomePackage-1.0.4.tar.gz
$ pip install http://my.package.repo/SomePackage-1.0.4.zip
</pre></div>
</div>
</div></blockquote>
</li>
<li><p class="first">Install from alternative package repositories.</p>
<p>Install from a different index, and not <a class="reference external" href="https://pypi.org/">PyPI</a></p>
<div class="highlight-default"><div class="highlight"><pre><span></span>$ pip install --index-url http://my.package.repo/simple/ SomePackage
</pre></div>
</div>
<p>Search an additional index during install, in addition to <a class="reference external" href="https://pypi.org/">PyPI</a></p>
<div class="highlight-default"><div class="highlight"><pre><span></span>$ pip install --extra-index-url http://my.package.repo/simple SomePackage
</pre></div>
</div>
<p>Install from a local flat directory containing archives (and don’t scan indexes):</p>
<div class="highlight-default"><div class="highlight"><pre><span></span>$ pip install --no-index --find-links=file:///local/dir/ SomePackage
$ pip install --no-index --find-links=/local/dir/ SomePackage
$ pip install --no-index --find-links=relative/dir/ SomePackage
</pre></div>
</div>
</li>
<li><p class="first">Find pre-release and development versions, in addition to stable versions. By default, pip only finds stable versions.</p>
<blockquote>
<div><div class="highlight-default"><div class="highlight"><pre><span></span>$ pip install --pre SomePackage
</pre></div>
</div>
</div></blockquote>
</li>
</ol>
<hr class="docutils" />
<table class="docutils footnote" frame="void" id="id17" rules="none">
<colgroup><col class="label" /><col /></colgroup>
<tbody valign="top">
<tr><td class="label"><a class="fn-backref" href="#id6">[1]</a></td><td>This is true with the exception that pip v7.0 and v7.0.1 required quotes
around specifiers containing environment markers in requirement files.</td></tr>
</tbody>
</table>
</div>
</div>
</div>
</div>
</div>
<div class="sphinxsidebar" role="navigation" aria-label="main navigation">
<div class="sphinxsidebarwrapper">
<h3><a href="../index.html">Table Of Contents</a></h3>
<ul class="current">
<li class="toctree-l1"><a class="reference internal" href="../quickstart.html">Quickstart</a></li>
<li class="toctree-l1"><a class="reference internal" href="../installing.html">Installation</a></li>
<li class="toctree-l1"><a class="reference internal" href="../user_guide.html">User Guide</a></li>
<li class="toctree-l1 current"><a class="reference internal" href="index.html">Reference Guide</a><ul class="current">
<li class="toctree-l2"><a class="reference internal" href="pip.html">pip</a></li>
<li class="toctree-l2 current"><a class="current reference internal" href="#">pip install</a><ul>
<li class="toctree-l3"><a class="reference internal" href="#usage">Usage</a></li>
<li class="toctree-l3"><a class="reference internal" href="#description">Description</a></li>
<li class="toctree-l3"><a class="reference internal" href="#options">Options</a></li>
<li class="toctree-l3"><a class="reference internal" href="#examples">Examples</a></li>
</ul>
</li>
<li class="toctree-l2"><a class="reference internal" href="pip_download.html">pip download</a></li>
<li class="toctree-l2"><a class="reference internal" href="pip_uninstall.html">pip uninstall</a></li>
<li class="toctree-l2"><a class="reference internal" href="pip_freeze.html">pip freeze</a></li>
<li class="toctree-l2"><a class="reference internal" href="pip_list.html">pip list</a></li>
<li class="toctree-l2"><a class="reference internal" href="pip_show.html">pip show</a></li>
<li class="toctree-l2"><a class="reference internal" href="pip_search.html">pip search</a></li>
<li class="toctree-l2"><a class="reference internal" href="pip_check.html">pip check</a></li>
<li class="toctree-l2"><a class="reference internal" href="pip_config.html">pip config</a></li>
<li class="toctree-l2"><a class="reference internal" href="pip_wheel.html">pip wheel</a></li>
<li class="toctree-l2"><a class="reference internal" href="pip_hash.html">pip hash</a></li>
</ul>
</li>
<li class="toctree-l1"><a class="reference internal" href="../development/index.html">Development</a></li>
<li class="toctree-l1"><a class="reference internal" href="../news.html">Release Notes</a></li>
</ul>
<h4>Previous topic</h4>
<p class="topless"><a href="pip.html"
title="previous chapter">pip</a></p>
<h4>Next topic</h4>
<p class="topless"><a href="pip_download.html"
title="next chapter">pip download</a></p>
</div>
</div>
<div class="clearer"></div>
</div>
<div class="related" role="navigation" aria-label="related navigation">
<h3>Navigation</h3>
<ul>
<li class="right" style="margin-right: 10px">
<a href="pip_download.html" title="pip download"
>next</a></li>
<li class="right" >
<a href="pip.html" title="pip"
>previous</a> |</li>
<li><img src="../_static/py.png" alt=""
style="vertical-align: middle; margin-top: -1px"/></li>
<li><a href="https://pypa.io">PyPA</a> »</li>
<a href="../index.html">pip 19.1.1 documentation</a> »
<li class="nav-item nav-item-1"><a href="index.html" >Reference Guide</a> »</li>
<li class="right">
<div class="inline-search" style="display: none" role="search">
<form class="inline-search" action="../search.html" method="get">
<input placeholder="Quick search" type="text" name="q" />
<input type="submit" value="Go" />
<input type="hidden" name="check_keywords" value="yes" />
<input type="hidden" name="area" value="default" />
</form>
</div>
<script type="text/javascript">$('.inline-search').show(0);</script>
|
</li>
</ul>
</div>
<div class="footer">
© <a href="../copyright.html">Copyright</a> 2008-2017, PyPA.
<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 Nov 14, 2019.
<a href="https://github.com/pypa/pip/issues">Found a bug</a>?
<br />
Created using <a href="http://sphinx.pocoo.org/">Sphinx</a> 1.6.5.
</div>
</body>
</html>