diff options
Diffstat (limited to 'devdocs/python~3.12/tutorial%2Fvenv.html')
| -rw-r--r-- | devdocs/python~3.12/tutorial%2Fvenv.html | 74 |
1 files changed, 74 insertions, 0 deletions
diff --git a/devdocs/python~3.12/tutorial%2Fvenv.html b/devdocs/python~3.12/tutorial%2Fvenv.html new file mode 100644 index 00000000..577209f9 --- /dev/null +++ b/devdocs/python~3.12/tutorial%2Fvenv.html @@ -0,0 +1,74 @@ + <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) + ... +>>> import sys +>>> sys.path +['', '/usr/local/lib/python35.zip', ..., +'~/envs/tutorial-env/lib/python3.5/site-packages'] +>>> +</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 > 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"> + © 2001–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> |