path: root/devdocs/python~3.12/tutorial%2Fvenv.html

 <span id="tut-venv"></span><h1> Virtual Environments and Packages</h1> <section id="introduction"> <h2>
<span class="section-number">12.1. </span>Introduction</h2> <p>Python applications will often use packages and modules that don’t come as part of the standard library. Applications will sometimes need a specific version of a library, because the application may require that a particular bug has been fixed or the application may be written using an obsolete version of the library’s interface.</p> <p>This means it may not be possible for one Python installation to meet the requirements of every application. If application A needs version 1.0 of a particular module but application B needs version 2.0, then the requirements are in conflict and installing either version 1.0 or 2.0 will leave one application unable to run.</p> <p>The solution for this problem is to create a <a class="reference internal" href="../glossary#term-virtual-environment"><span class="xref std std-term">virtual environment</span></a>, a self-contained directory tree that contains a Python installation for a particular version of Python, plus a number of additional packages.</p> <p>Different applications can then use different virtual environments. To resolve the earlier example of conflicting requirements, application A can have its own virtual environment with version 1.0 installed while application B has another virtual environment with version 2.0. If application B requires a library be upgraded to version 3.0, this will not affect application A’s environment.</p> </section> <section id="creating-virtual-environments"> <h2>
<span class="section-number">12.2. </span>Creating Virtual Environments</h2> <p>The module used to create and manage virtual environments is called <a class="reference internal" href="../library/venv#module-venv" title="venv: Creation of virtual environments."><code>venv</code></a>. <a class="reference internal" href="../library/venv#module-venv" title="venv: Creation of virtual environments."><code>venv</code></a> will usually install the most recent version of Python that you have available. If you have multiple versions of Python on your system, you can select a specific Python version by running <code>python3</code> or whichever version you want.</p> <p>To create a virtual environment, decide upon a directory where you want to place it, and run the <a class="reference internal" href="../library/venv#module-venv" title="venv: Creation of virtual environments."><code>venv</code></a> module as a script with the directory path:</p> <pre data-language="python">python -m venv tutorial-env
</pre> <p>This will create the <code>tutorial-env</code> directory if it doesn’t exist, and also create directories inside it containing a copy of the Python interpreter and various supporting files.</p> <p>A common directory location for a virtual environment is <code>.venv</code>. This name keeps the directory typically hidden in your shell and thus out of the way while giving it a name that explains why the directory exists. It also prevents clashing with <code>.env</code> environment variable definition files that some tooling supports.</p> <p>Once you’ve created a virtual environment, you may activate it.</p> <p>On Windows, run:</p> <pre data-language="python">tutorial-env\Scripts\activate
</pre> <p>On Unix or MacOS, run:</p> <pre data-language="python">source tutorial-env/bin/activate
</pre> <p>(This script is written for the bash shell. If you use the <strong class="program">csh</strong> or <strong class="program">fish</strong> shells, there are alternate <code>activate.csh</code> and <code>activate.fish</code> scripts you should use instead.)</p> <p>Activating the virtual environment will change your shell’s prompt to show what virtual environment you’re using, and modify the environment so that running <code>python</code> will get you that particular version and installation of Python. For example:</p> <pre data-language="bash">$ source ~/envs/tutorial-env/bin/activate
(tutorial-env) $ python
Python 3.5.1 (default, May  6 2016, 10:59:36)
  ...
&gt;&gt;&gt; import sys
&gt;&gt;&gt; sys.path
['', '/usr/local/lib/python35.zip', ...,
'~/envs/tutorial-env/lib/python3.5/site-packages']
&gt;&gt;&gt;
</pre> <p>To deactivate a virtual environment, type:</p> <pre data-language="python">deactivate
</pre> <p>into the terminal.</p> </section> <section id="managing-packages-with-pip"> <h2>
<span class="section-number">12.3. </span>Managing Packages with pip</h2> <p>You can install, upgrade, and remove packages using a program called <strong class="program">pip</strong>. By default <code>pip</code> will install packages from the <a class="reference external" href="https://pypi.org">Python Package Index</a>. You can browse the Python Package Index by going to it in your web browser.</p> <p><code>pip</code> has a number of subcommands: “install”, “uninstall”, “freeze”, etc. (Consult the <a class="reference internal" href="../installing/index#installing-index"><span class="std std-ref">Installing Python Modules</span></a> guide for complete documentation for <code>pip</code>.)</p> <p>You can install the latest version of a package by specifying a package’s name:</p> <pre data-language="bash">(tutorial-env) $ python -m pip install novas
Collecting novas
  Downloading novas-3.1.1.3.tar.gz (136kB)
Installing collected packages: novas
  Running setup.py install for novas
Successfully installed novas-3.1.1.3
</pre> <p>You can also install a specific version of a package by giving the package name followed by <code>==</code> and the version number:</p> <pre data-language="bash">(tutorial-env) $ python -m pip install requests==2.6.0
Collecting requests==2.6.0
  Using cached requests-2.6.0-py2.py3-none-any.whl
Installing collected packages: requests
Successfully installed requests-2.6.0
</pre> <p>If you re-run this command, <code>pip</code> will notice that the requested version is already installed and do nothing. You can supply a different version number to get that version, or you can run <code>python
-m pip install --upgrade</code> to upgrade the package to the latest version:</p> <pre data-language="bash">(tutorial-env) $ python -m pip install --upgrade requests
Collecting requests
Installing collected packages: requests
  Found existing installation: requests 2.6.0
    Uninstalling requests-2.6.0:
      Successfully uninstalled requests-2.6.0
Successfully installed requests-2.7.0
</pre> <p><code>python -m pip uninstall</code> followed by one or more package names will remove the packages from the virtual environment.</p> <p><code>python -m pip show</code> will display information about a particular package:</p> <pre data-language="bash">(tutorial-env) $ python -m pip show requests
---
Metadata-Version: 2.0
Name: requests
Version: 2.7.0
Summary: Python HTTP for Humans.
Home-page: http://python-requests.org
Author: Kenneth Reitz
Author-email: me@kennethreitz.com
License: Apache 2.0
Location: /Users/akuchling/envs/tutorial-env/lib/python3.4/site-packages
Requires:
</pre> <p><code>python -m pip list</code> will display all of the packages installed in the virtual environment:</p> <pre data-language="bash">(tutorial-env) $ python -m pip list
novas (3.1.1.3)
numpy (1.9.2)
pip (7.0.3)
requests (2.7.0)
setuptools (16.0)
</pre> <p><code>python -m pip freeze</code> will produce a similar list of the installed packages, but the output uses the format that <code>python -m pip install</code> expects. A common convention is to put this list in a <code>requirements.txt</code> file:</p> <pre data-language="bash">(tutorial-env) $ python -m pip freeze &gt; requirements.txt
(tutorial-env) $ cat requirements.txt
novas==3.1.1.3
numpy==1.9.2
requests==2.7.0
</pre> <p>The <code>requirements.txt</code> can then be committed to version control and shipped as part of an application. Users can then install all the necessary packages with <code>install -r</code>:</p> <pre data-language="bash">(tutorial-env) $ python -m pip install -r requirements.txt
Collecting novas==3.1.1.3 (from -r requirements.txt (line 1))
  ...
Collecting numpy==1.9.2 (from -r requirements.txt (line 2))
  ...
Collecting requests==2.7.0 (from -r requirements.txt (line 3))
  ...
Installing collected packages: novas, numpy, requests
  Running setup.py install for novas
Successfully installed novas-3.1.1.3 numpy-1.9.2 requests-2.7.0
</pre> <p><code>pip</code> has many more options. Consult the <a class="reference internal" href="../installing/index#installing-index"><span class="std std-ref">Installing Python Modules</span></a> guide for complete documentation for <code>pip</code>. When you’ve written a package and want to make it available on the Python Package Index, consult the <a class="reference external" href="https://packaging.python.org/en/latest/tutorials/packaging-projects/">Python packaging user guide</a>.</p> </section> <div class="_attribution">
  <p class="_attribution-p">
    &copy; 2001&ndash;2023 Python Software Foundation<br>Licensed under the PSF License.<br>
    <a href="https://docs.python.org/3.12/tutorial/venv.html" class="_attribution-link">https://docs.python.org/3.12/tutorial/venv.html</a>
  </p>
</div>