<!DOCTYPE html> <!--[if IE 8]><html class="no-js lt-ie9" lang="en" > <![endif]--> <!--[if gt IE 8]><!--> <html class="no-js" lang="en" > <!--<![endif]--> <head> <meta charset="utf-8"> <meta name="viewport" content="width=device-width, initial-scale=1.0"> <title>Reference Guide — virtualenv dev documentation</title> <link rel="stylesheet" href="_static/css/theme.css" type="text/css" /> <link rel="stylesheet" href="_static/pygments.css" type="text/css" /> <link rel="index" title="Index" href="genindex.html" /> <link rel="search" title="Search" href="search.html" /> <link rel="next" title="Development" href="development.html" /> <link rel="prev" title="User Guide" href="userguide.html" /> <script src="_static/js/modernizr.min.js"></script> </head> <body class="wy-body-for-nav"> <div class="wy-grid-for-nav"> <nav data-toggle="wy-nav-shift" class="wy-nav-side"> <div class="wy-side-scroll"> <div class="wy-side-nav-search"> <a href="index.html" class="icon icon-home"> virtualenv </a> <div class="version"> dev </div> <div role="search"> <form id="rtd-search-form" class="wy-form" action="search.html" method="get"> <input type="text" name="q" placeholder="Search docs" /> <input type="hidden" name="check_keywords" value="yes" /> <input type="hidden" name="area" value="default" /> </form> </div> </div> <div class="wy-menu wy-menu-vertical" data-spy="affix" role="navigation" aria-label="main navigation"> <ul class="current"> <li class="toctree-l1"><a class="reference internal" href="installation.html">Installation</a></li> <li class="toctree-l1"><a class="reference internal" href="userguide.html">User Guide</a></li> <li class="toctree-l1 current"><a class="current reference internal" href="#">Reference Guide</a><ul> <li class="toctree-l2"><a class="reference internal" href="#virtualenv-command"><code class="docutils literal notranslate"><span class="pre">virtualenv</span></code> Command</a><ul> <li class="toctree-l3"><a class="reference internal" href="#usage">Usage</a></li> <li class="toctree-l3"><a class="reference internal" href="#options">Options</a></li> </ul> </li> <li class="toctree-l2"><a class="reference internal" href="#configuration">Configuration</a><ul> <li class="toctree-l3"><a class="reference internal" href="#environment-variables">Environment Variables</a></li> <li class="toctree-l3"><a class="reference internal" href="#configuration-file">Configuration File</a></li> </ul> </li> <li class="toctree-l2"><a class="reference internal" href="#extending-virtualenv">Extending Virtualenv</a><ul> <li class="toctree-l3"><a class="reference internal" href="#creating-your-own-bootstrap-scripts">Creating Your Own Bootstrap Scripts</a></li> <li class="toctree-l3"><a class="reference internal" href="#bootstrap-example">Bootstrap Example</a></li> </ul> </li> </ul> </li> <li class="toctree-l1"><a class="reference internal" href="development.html">Development</a></li> <li class="toctree-l1"><a class="reference internal" href="changes.html">Release History</a></li> </ul> </div> </div> </nav> <section data-toggle="wy-nav-shift" class="wy-nav-content-wrap"> <nav class="wy-nav-top" aria-label="top navigation"> <i data-toggle="wy-nav-top" class="fa fa-bars"></i> <a href="index.html">virtualenv</a> </nav> <div class="wy-nav-content"> <div class="rst-content"> <div role="navigation" aria-label="breadcrumbs navigation"> <ul class="wy-breadcrumbs"> <li><a href="index.html">Docs</a> »</li> <li>Reference Guide</li> <li class="wy-breadcrumbs-aside"> <a href="_sources/reference.rst.txt" rel="nofollow"> View page source</a> </li> </ul> <hr/> </div> <div role="main" class="document" itemscope="itemscope" itemtype="http://schema.org/Article"> <div itemprop="articleBody"> <div class="section" id="reference-guide"> <h1>Reference Guide<a class="headerlink" href="#reference-guide" title="Permalink to this headline">¶</a></h1> <div class="section" id="virtualenv-command"> <h2><code class="docutils literal notranslate"><span class="pre">virtualenv</span></code> Command<a class="headerlink" href="#virtualenv-command" title="Permalink to this headline">¶</a></h2> <div class="section" id="usage"> <span id="id1"></span><h3>Usage<a class="headerlink" href="#usage" title="Permalink to this headline">¶</a></h3> <p><strong class="command">virtualenv [OPTIONS] ENV_DIR</strong></p> <blockquote> <div>Where <code class="docutils literal notranslate"><span class="pre">ENV_DIR</span></code> is an absolute or relative path to a directory to create the virtual environment in.</div></blockquote> </div> <div class="section" id="options"> <span id="id2"></span><h3>Options<a class="headerlink" href="#options" title="Permalink to this headline">¶</a></h3> <dl class="option"> <dt id="cmdoption-version"> <code class="descname">--version</code><code class="descclassname"></code><a class="headerlink" href="#cmdoption-version" title="Permalink to this definition">¶</a></dt> <dd><p>show program’s version number and exit</p> </dd></dl> <dl class="option"> <dt id="cmdoption-h"> <code class="descname">-h</code><code class="descclassname"></code><code class="descclassname">, </code><code class="descname">--help</code><code class="descclassname"></code><a class="headerlink" href="#cmdoption-h" title="Permalink to this definition">¶</a></dt> <dd><p>show this help message and exit</p> </dd></dl> <dl class="option"> <dt id="cmdoption-v"> <code class="descname">-v</code><code class="descclassname"></code><code class="descclassname">, </code><code class="descname">--verbose</code><code class="descclassname"></code><a class="headerlink" href="#cmdoption-v" title="Permalink to this definition">¶</a></dt> <dd><p>Increase verbosity.</p> </dd></dl> <dl class="option"> <dt id="cmdoption-q"> <code class="descname">-q</code><code class="descclassname"></code><code class="descclassname">, </code><code class="descname">--quiet</code><code class="descclassname"></code><a class="headerlink" href="#cmdoption-q" title="Permalink to this definition">¶</a></dt> <dd><p>Decrease verbosity.</p> </dd></dl> <dl class="option"> <dt id="cmdoption-p"> <code class="descname">-p</code><code class="descclassname"> PYTHON_EXE</code><code class="descclassname">, </code><code class="descname">--python</code><code class="descclassname">=PYTHON_EXE</code><a class="headerlink" href="#cmdoption-p" title="Permalink to this definition">¶</a></dt> <dd><p>The Python interpreter to use, e.g., –python=python2.5 will use the python2.5 interpreter to create the new environment. The default is the interpreter that virtualenv was installed with (like <code class="docutils literal notranslate"><span class="pre">/usr/bin/python</span></code>)</p> </dd></dl> <dl class="option"> <dt id="cmdoption-clear"> <code class="descname">--clear</code><code class="descclassname"></code><a class="headerlink" href="#cmdoption-clear" title="Permalink to this definition">¶</a></dt> <dd><p>Clear out the non-root install and start from scratch.</p> </dd></dl> <dl class="option"> <dt id="cmdoption-system-site-packages"> <code class="descname">--system-site-packages</code><code class="descclassname"></code><a class="headerlink" href="#cmdoption-system-site-packages" title="Permalink to this definition">¶</a></dt> <dd><p>Give the virtual environment access to the global site-packages.</p> </dd></dl> <dl class="option"> <dt id="cmdoption-always-copy"> <code class="descname">--always-copy</code><code class="descclassname"></code><a class="headerlink" href="#cmdoption-always-copy" title="Permalink to this definition">¶</a></dt> <dd><p>Always copy files rather than symlinking.</p> </dd></dl> <dl class="option"> <dt id="cmdoption-relocatable"> <code class="descname">--relocatable</code><code class="descclassname"></code><a class="headerlink" href="#cmdoption-relocatable" title="Permalink to this definition">¶</a></dt> <dd><p>Make an EXISTING virtualenv environment relocatable. This fixes up scripts and makes all .pth files relative.</p> </dd></dl> <dl class="option"> <dt id="cmdoption-unzip-setuptools"> <code class="descname">--unzip-setuptools</code><code class="descclassname"></code><a class="headerlink" href="#cmdoption-unzip-setuptools" title="Permalink to this definition">¶</a></dt> <dd><p>Unzip Setuptools when installing it.</p> </dd></dl> <dl class="option"> <dt id="cmdoption-no-setuptools"> <code class="descname">--no-setuptools</code><code class="descclassname"></code><a class="headerlink" href="#cmdoption-no-setuptools" title="Permalink to this definition">¶</a></dt> <dd><p>Do not install setuptools in the new virtualenv.</p> </dd></dl> <dl class="option"> <dt id="cmdoption-no-pip"> <code class="descname">--no-pip</code><code class="descclassname"></code><a class="headerlink" href="#cmdoption-no-pip" title="Permalink to this definition">¶</a></dt> <dd><p>Do not install pip in the new virtualenv.</p> </dd></dl> <dl class="option"> <dt id="cmdoption-no-wheel"> <code class="descname">--no-wheel</code><code class="descclassname"></code><a class="headerlink" href="#cmdoption-no-wheel" title="Permalink to this definition">¶</a></dt> <dd><p>Do not install wheel in the new virtualenv.</p> </dd></dl> <dl class="option"> <dt id="cmdoption-extra-search-dir"> <code class="descname">--extra-search-dir</code><code class="descclassname">=DIR</code><a class="headerlink" href="#cmdoption-extra-search-dir" title="Permalink to this definition">¶</a></dt> <dd><p>Directory to look for setuptools/pip distributions in. This option can be specified multiple times.</p> </dd></dl> <dl class="option"> <dt id="cmdoption-prompt"> <code class="descname">--prompt</code><code class="descclassname">=PROMPT</code><a class="headerlink" href="#cmdoption-prompt" title="Permalink to this definition">¶</a></dt> <dd><p>Provides an alternative prompt prefix for this environment.</p> </dd></dl> <dl class="option"> <dt id="cmdoption-download"> <code class="descname">--download</code><code class="descclassname"></code><a class="headerlink" href="#cmdoption-download" title="Permalink to this definition">¶</a></dt> <dd><p>Download preinstalled packages from PyPI.</p> </dd></dl> <dl class="option"> <dt id="cmdoption-no-download"> <code class="descname">--no-download</code><code class="descclassname"></code><a class="headerlink" href="#cmdoption-no-download" title="Permalink to this definition">¶</a></dt> <dd><p>Do not download preinstalled packages from PyPI.</p> </dd></dl> <dl class="option"> <dt id="cmdoption-no-site-packages"> <code class="descname">--no-site-packages</code><code class="descclassname"></code><a class="headerlink" href="#cmdoption-no-site-packages" title="Permalink to this definition">¶</a></dt> <dd><p>DEPRECATED. Retained only for backward compatibility. Not having access to global site-packages is now the default behavior.</p> </dd></dl> <dl class="option"> <dt id="cmdoption-distribute"> <code class="descname">--distribute</code><code class="descclassname"></code><a class="headerlink" href="#cmdoption-distribute" title="Permalink to this definition">¶</a></dt> <dd></dd></dl> <dl class="option"> <dt id="cmdoption-setuptools"> <code class="descname">--setuptools</code><code class="descclassname"></code><a class="headerlink" href="#cmdoption-setuptools" title="Permalink to this definition">¶</a></dt> <dd><p>Legacy; now have no effect. Before version 1.10 these could be used to choose whether to install <a class="reference external" href="https://pypi.org/project/distribute">Distribute</a> or <a class="reference external" href="https://pypi.org/project/setuptools">Setuptools</a> into the created virtualenv. Distribute has now been merged into Setuptools, and the latter is always installed.</p> </dd></dl> </div> </div> <div class="section" id="configuration"> <h2>Configuration<a class="headerlink" href="#configuration" title="Permalink to this headline">¶</a></h2> <div class="section" id="environment-variables"> <h3>Environment Variables<a class="headerlink" href="#environment-variables" title="Permalink to this headline">¶</a></h3> <p>Each command line option is automatically used to look for environment variables with the name format <code class="docutils literal notranslate"><span class="pre">VIRTUALENV_<UPPER_NAME></span></code>. That means the name of the command line options are capitalized and have dashes (<code class="docutils literal notranslate"><span class="pre">'-'</span></code>) replaced with underscores (<code class="docutils literal notranslate"><span class="pre">'_'</span></code>).</p> <p>For example, to automatically use a custom Python binary instead of the one virtualenv is run with you can also set an environment variable:</p> <div class="highlight-default notranslate"><div class="highlight"><pre><span></span>$ export VIRTUALENV_PYTHON=/opt/python-3.3/bin/python $ virtualenv ENV </pre></div> </div> <p>It’s the same as passing the option to virtualenv directly:</p> <div class="highlight-default notranslate"><div class="highlight"><pre><span></span>$ virtualenv --python=/opt/python-3.3/bin/python ENV </pre></div> </div> <p>This also works for appending command line options, like <code class="docutils literal notranslate"><span class="pre">--find-links</span></code>. Just leave an empty space between the passed values, e.g.:</p> <div class="highlight-default notranslate"><div class="highlight"><pre><span></span>$ export VIRTUALENV_EXTRA_SEARCH_DIR="/path/to/dists /path/to/other/dists" $ virtualenv ENV </pre></div> </div> <p>is the same as calling:</p> <div class="highlight-default notranslate"><div class="highlight"><pre><span></span>$ virtualenv --extra-search-dir=/path/to/dists --extra-search-dir=/path/to/other/dists ENV </pre></div> </div> <dl class="envvar"> <dt id="envvar-VIRTUAL_ENV_DISABLE_PROMPT"> <code class="descname">VIRTUAL_ENV_DISABLE_PROMPT</code><a class="headerlink" href="#envvar-VIRTUAL_ENV_DISABLE_PROMPT" title="Permalink to this definition">¶</a></dt> <dd><p>Any virtualenv created when this is set to a non-empty value will not have it’s <a class="reference internal" href="userguide.html#activate"><span class="std std-ref">activate script</span></a> modify the shell prompt.</p> </dd></dl> </div> <div class="section" id="configuration-file"> <h3>Configuration File<a class="headerlink" href="#configuration-file" title="Permalink to this headline">¶</a></h3> <p>virtualenv also looks for a standard ini config file. On Unix and Mac OS X that’s <code class="docutils literal notranslate"><span class="pre">$HOME/.virtualenv/virtualenv.ini</span></code> and on Windows, it’s <code class="docutils literal notranslate"><span class="pre">%APPDATA%\virtualenv\virtualenv.ini</span></code>.</p> <p>The names of the settings are derived from the long command line option, e.g. the option <a class="reference internal" href="#cmdoption-p"><code class="xref std std-option docutils literal notranslate"><span class="pre">--python</span></code></a> would look like this:</p> <div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="p">[</span><span class="n">virtualenv</span><span class="p">]</span> <span class="n">python</span> <span class="o">=</span> <span class="o">/</span><span class="n">opt</span><span class="o">/</span><span class="n">python</span><span class="o">-</span><span class="mf">3.3</span><span class="o">/</span><span class="nb">bin</span><span class="o">/</span><span class="n">python</span> </pre></div> </div> <p>Appending options like <a class="reference internal" href="#cmdoption-extra-search-dir"><code class="xref std std-option docutils literal notranslate"><span class="pre">--extra-search-dir</span></code></a> can be written on multiple lines:</p> <div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="p">[</span><span class="n">virtualenv</span><span class="p">]</span> <span class="n">extra</span><span class="o">-</span><span class="n">search</span><span class="o">-</span><span class="nb">dir</span> <span class="o">=</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">dists</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">other</span><span class="o">/</span><span class="n">dists</span> </pre></div> </div> <p>Please have a look at the output of <a class="reference internal" href="#cmdoption-h"><code class="xref std std-option docutils literal notranslate"><span class="pre">--help</span></code></a> for a full list of supported options.</p> </div> </div> <div class="section" id="extending-virtualenv"> <h2>Extending Virtualenv<a class="headerlink" href="#extending-virtualenv" title="Permalink to this headline">¶</a></h2> <div class="section" id="creating-your-own-bootstrap-scripts"> <h3>Creating Your Own Bootstrap Scripts<a class="headerlink" href="#creating-your-own-bootstrap-scripts" title="Permalink to this headline">¶</a></h3> <p>While this creates an environment, it doesn’t put anything into the environment. Developers may find it useful to distribute a script that sets up a particular environment, for example a script that installs a particular web application.</p> <div class="admonition note"> <p class="first admonition-title">Note</p> <p class="last">A bootstrap script requires a <code class="docutils literal notranslate"><span class="pre">virtualenv_support</span></code> directory containing <code class="docutils literal notranslate"><span class="pre">pip</span></code> and <code class="docutils literal notranslate"><span class="pre">setuptools</span></code> wheels alongside it, just like the actual virtualenv script. Running a bootstrap script without a <code class="docutils literal notranslate"><span class="pre">virtualenv_support</span></code> directory is unsupported (but if you use <code class="docutils literal notranslate"><span class="pre">--no-setuptools</span></code> and manually install <code class="docutils literal notranslate"><span class="pre">pip</span></code> and <code class="docutils literal notranslate"><span class="pre">setuptools</span></code> in your virtualenv, it will work).</p> </div> <p>To create a script like this, call <code class="xref py py-func docutils literal notranslate"><span class="pre">virtualenv.create_bootstrap_script()</span></code>, and write the result to your new bootstrapping script.</p> <dl class="function"> <dt id="create_bootstrap_script"> <code class="descname">create_bootstrap_script</code><span class="sig-paren">(</span><em>extra_text</em><span class="sig-paren">)</span><a class="headerlink" href="#create_bootstrap_script" title="Permalink to this definition">¶</a></dt> <dd><p>Creates a bootstrap script from <code class="docutils literal notranslate"><span class="pre">extra_text</span></code>, which is like this script but with extend_parser, adjust_options, and after_install hooks.</p> </dd></dl> <p>This returns a string that (written to disk of course) can be used as a bootstrap script with your own customizations. The script will be the standard virtualenv.py script, with your extra text added (your extra text should be Python code).</p> <p>If you include these functions, they will be called:</p> <dl class="function"> <dt id="extend_parser"> <code class="descname">extend_parser</code><span class="sig-paren">(</span><em>optparse_parser</em><span class="sig-paren">)</span><a class="headerlink" href="#extend_parser" title="Permalink to this definition">¶</a></dt> <dd><p>You can add or remove options from the parser here.</p> </dd></dl> <dl class="function"> <dt id="adjust_options"> <code class="descname">adjust_options</code><span class="sig-paren">(</span><em>options</em>, <em>args</em><span class="sig-paren">)</span><a class="headerlink" href="#adjust_options" title="Permalink to this definition">¶</a></dt> <dd><p>You can change options here, or change the args (if you accept different kinds of arguments, be sure you modify <code class="docutils literal notranslate"><span class="pre">args</span></code> so it is only <code class="docutils literal notranslate"><span class="pre">[DEST_DIR]</span></code>).</p> </dd></dl> <dl class="function"> <dt id="after_install"> <code class="descname">after_install</code><span class="sig-paren">(</span><em>options</em>, <em>home_dir</em><span class="sig-paren">)</span><a class="headerlink" href="#after_install" title="Permalink to this definition">¶</a></dt> <dd><p>After everything is installed, this function is called. This is probably the function you are most likely to use. An example would be:</p> <div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="k">def</span> <span class="nf">after_install</span><span class="p">(</span><span class="n">options</span><span class="p">,</span> <span class="n">home_dir</span><span class="p">):</span> <span class="k">if</span> <span class="n">sys</span><span class="o">.</span><span class="n">platform</span> <span class="o">==</span> <span class="s1">'win32'</span><span class="p">:</span> <span class="nb">bin</span> <span class="o">=</span> <span class="s1">'Scripts'</span> <span class="k">else</span><span class="p">:</span> <span class="nb">bin</span> <span class="o">=</span> <span class="s1">'bin'</span> <span class="n">subprocess</span><span class="o">.</span><span class="n">call</span><span class="p">([</span><span class="n">join</span><span class="p">(</span><span class="n">home_dir</span><span class="p">,</span> <span class="nb">bin</span><span class="p">,</span> <span class="s1">'easy_install'</span><span class="p">),</span> <span class="s1">'MyPackage'</span><span class="p">])</span> <span class="n">subprocess</span><span class="o">.</span><span class="n">call</span><span class="p">([</span><span class="n">join</span><span class="p">(</span><span class="n">home_dir</span><span class="p">,</span> <span class="nb">bin</span><span class="p">,</span> <span class="s1">'my-package-script'</span><span class="p">),</span> <span class="s1">'setup'</span><span class="p">,</span> <span class="n">home_dir</span><span class="p">])</span> </pre></div> </div> <p>This example immediately installs a package, and runs a setup script from that package.</p> </dd></dl> </div> <div class="section" id="bootstrap-example"> <h3>Bootstrap Example<a class="headerlink" href="#bootstrap-example" title="Permalink to this headline">¶</a></h3> <p>Here’s a more concrete example of how you could use this:</p> <div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="kn">import</span> <span class="nn">virtualenv</span><span class="o">,</span> <span class="nn">textwrap</span> <span class="n">output</span> <span class="o">=</span> <span class="n">virtualenv</span><span class="o">.</span><span class="n">create_bootstrap_script</span><span class="p">(</span><span class="n">textwrap</span><span class="o">.</span><span class="n">dedent</span><span class="p">(</span><span class="s2">"""</span> <span class="s2">import os, subprocess</span> <span class="s2">def after_install(options, home_dir):</span> <span class="s2"> etc = join(home_dir, 'etc')</span> <span class="s2"> if not os.path.exists(etc):</span> <span class="s2"> os.makedirs(etc)</span> <span class="s2"> subprocess.call([join(home_dir, 'bin', 'easy_install'),</span> <span class="s2"> 'BlogApplication'])</span> <span class="s2"> subprocess.call([join(home_dir, 'bin', 'paster'),</span> <span class="s2"> 'make-config', 'BlogApplication',</span> <span class="s2"> join(etc, 'blog.ini')])</span> <span class="s2"> subprocess.call([join(home_dir, 'bin', 'paster'),</span> <span class="s2"> 'setup-app', join(etc, 'blog.ini')])</span> <span class="s2">"""</span><span class="p">))</span> <span class="n">f</span> <span class="o">=</span> <span class="nb">open</span><span class="p">(</span><span class="s1">'blog-bootstrap.py'</span><span class="p">,</span> <span class="s1">'w'</span><span class="p">)</span><span class="o">.</span><span class="n">write</span><span class="p">(</span><span class="n">output</span><span class="p">)</span> </pre></div> </div> <p>Another example is available <a class="reference external" href="https://github.com/socialplanning/fassembler/blob/master/fassembler/create-venv-script.py">here</a>.</p> </div> </div> </div> </div> </div> <footer> <div class="rst-footer-buttons" role="navigation" aria-label="footer navigation"> <a href="development.html" class="btn btn-neutral float-right" title="Development" accesskey="n" rel="next">Next <span class="fa fa-arrow-circle-right"></span></a> <a href="userguide.html" class="btn btn-neutral" title="User Guide" accesskey="p" rel="prev"><span class="fa fa-arrow-circle-left"></span> Previous</a> </div> <hr/> <div role="contentinfo"> <p> © Copyright 2007-2018, Ian Bicking, The Open Planning Project, PyPA Last updated on Jan 07, 2019. </p> </div> Built with <a href="http://sphinx-doc.org/">Sphinx</a> using a <a href="https://github.com/rtfd/sphinx_rtd_theme">theme</a> provided by <a href="https://readthedocs.org">Read the Docs</a>. </footer> </div> </div> </section> </div> <script type="text/javascript" id="documentation_options" data-url_root="./" src="_static/documentation_options.js"></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/language_data.js"></script> <script type="text/javascript" src="_static/js/theme.js"></script> <script type="text/javascript"> jQuery(function () { SphinxRtdTheme.Navigation.enable(true); }); </script> </body> </html>