Issue #27285: Document the deprecation of the pyvenv script.
As part of the update, the documentation was updated to normalize around the term "virtual environment" instead of relying too heavily on "venv" for the same meaning and leading to inconsistent usage of either. Thanks to Steve Piercy for the patch.
This commit is contained in:
Brett Cannon
parent
53e22bfea5
commit
15552c39e0
|
|
@ -970,7 +970,7 @@ Glossary
|
|||
without interfering with the behaviour of other Python applications
|
||||
running on the same system.
|
||||
|
||||
See also :ref:`scripts-pyvenv`.
|
||||
See also :mod:`venv`.
|
||||
|
||||
virtual machine
|
||||
A computer defined entirely in software. Python's virtual machine
|
||||
|
|
|
|||
|
|
@ -2,9 +2,9 @@
|
|||
|
||||
.. _installing-index:
|
||||
|
||||
*****************************
|
||||
Installing Python Modules
|
||||
*****************************
|
||||
*************************
|
||||
Installing Python Modules
|
||||
*************************
|
||||
|
||||
:Email: distutils-sig@python.org
|
||||
|
||||
|
|
@ -34,24 +34,24 @@ Key terms
|
|||
|
||||
* ``pip`` is the preferred installer program. Starting with Python 3.4, it
|
||||
is included by default with the Python binary installers.
|
||||
* a virtual environment is a semi-isolated Python environment that allows
|
||||
* A *virtual environment* is a semi-isolated Python environment that allows
|
||||
packages to be installed for use by a particular application, rather than
|
||||
being installed system wide
|
||||
* ``pyvenv`` is the standard tool for creating virtual environments, and has
|
||||
being installed system wide.
|
||||
* ``venv`` is the standard tool for creating virtual environments, and has
|
||||
been part of Python since Python 3.3. Starting with Python 3.4, it
|
||||
defaults to installing ``pip`` into all created virtual environments
|
||||
defaults to installing ``pip`` into all created virtual environments.
|
||||
* ``virtualenv`` is a third party alternative (and predecessor) to
|
||||
``pyvenv``. It allows virtual environments to be used on versions of
|
||||
Python prior to 3.4, which either don't provide ``pyvenv`` at all, or
|
||||
``venv``. It allows virtual environments to be used on versions of
|
||||
Python prior to 3.4, which either don't provide ``venv`` at all, or
|
||||
aren't able to automatically install ``pip`` into created environments.
|
||||
* the `Python Packaging Index <https://pypi.python.org/pypi>`__ is a public
|
||||
* The `Python Packaging Index <https://pypi.python.org/pypi>`__ is a public
|
||||
repository of open source licensed packages made available for use by
|
||||
other Python users
|
||||
other Python users.
|
||||
* the `Python Packaging Authority
|
||||
<https://www.pypa.io/en/latest/>`__ are the group of
|
||||
developers and documentation authors responsible for the maintenance and
|
||||
evolution of the standard packaging tools and the associated metadata and
|
||||
file format standards. They maintain a variety of tools, documentation
|
||||
file format standards. They maintain a variety of tools, documentation,
|
||||
and issue trackers on both `GitHub <https://github.com/pypa>`__ and
|
||||
`BitBucket <https://bitbucket.org/pypa/>`__.
|
||||
* ``distutils`` is the original build and distribution system first added to
|
||||
|
|
@ -62,6 +62,19 @@ Key terms
|
|||
of the mailing list used to coordinate Python packaging standards
|
||||
development).
|
||||
|
||||
.. deprecated:: 3.6
|
||||
``pyvenv`` was the recommended tool for creating virtual environments for
|
||||
Python 3.3 and 3.4, and is `deprecated in Python 3.6
|
||||
<https://docs.python.org/dev/whatsnew/3.6.html#deprecated-features>`_.
|
||||
|
||||
.. versionchanged:: 3.5
|
||||
The use of ``venv`` is now recommended for creating virtual environments.
|
||||
|
||||
.. seealso::
|
||||
|
||||
`Python Packaging User Guide: Creating and using virtual environments
|
||||
<https://packaging.python.org/installing/#creating-virtual-environments>`__
|
||||
|
||||
|
||||
Basic usage
|
||||
===========
|
||||
|
|
@ -100,13 +113,14 @@ explicitly::
|
|||
More information and resources regarding ``pip`` and its capabilities can be
|
||||
found in the `Python Packaging User Guide <https://packaging.python.org>`__.
|
||||
|
||||
``pyvenv`` has its own documentation at :ref:`scripts-pyvenv`. Installing
|
||||
into an active virtual environment uses the commands shown above.
|
||||
Creation of virtual environments is done through the :mod:`venv` module.
|
||||
Installing packages into an active virtual environment uses the commands shown
|
||||
above.
|
||||
|
||||
.. seealso::
|
||||
|
||||
`Python Packaging User Guide: Installing Python Distribution Packages
|
||||
<https://packaging.python.org/en/latest/installing/>`__
|
||||
<https://packaging.python.org/installing/>`__
|
||||
|
||||
|
||||
How do I ...?
|
||||
|
|
@ -124,7 +138,7 @@ User Guide.
|
|||
.. seealso::
|
||||
|
||||
`Python Packaging User Guide: Requirements for Installing Packages
|
||||
<https://packaging.python.org/en/latest/installing/#requirements-for-installing-packages>`__
|
||||
<https://packaging.python.org/installing/#requirements-for-installing-packages>`__
|
||||
|
||||
|
||||
.. installing-per-user-installation:
|
||||
|
|
@ -142,20 +156,19 @@ package just for the current user, rather than for all users of the system.
|
|||
A number of scientific Python packages have complex binary dependencies, and
|
||||
aren't currently easy to install using ``pip`` directly. At this point in
|
||||
time, it will often be easier for users to install these packages by
|
||||
`other means
|
||||
<https://packaging.python.org/en/latest/science/>`__
|
||||
`other means <https://packaging.python.org/science/>`__
|
||||
rather than attempting to install them with ``pip``.
|
||||
|
||||
.. seealso::
|
||||
|
||||
`Python Packaging User Guide: Installing Scientific Packages
|
||||
<https://packaging.python.org/en/latest/science/>`__
|
||||
<https://packaging.python.org/science/>`__
|
||||
|
||||
|
||||
... work with multiple versions of Python installed in parallel?
|
||||
----------------------------------------------------------------
|
||||
|
||||
On Linux, Mac OS X and other POSIX systems, use the versioned Python commands
|
||||
On Linux, Mac OS X, and other POSIX systems, use the versioned Python commands
|
||||
in combination with the ``-m`` switch to run the appropriate copy of
|
||||
``pip``::
|
||||
|
||||
|
|
@ -164,7 +177,7 @@ in combination with the ``-m`` switch to run the appropriate copy of
|
|||
python3 -m pip install SomePackage # default Python 3
|
||||
python3.4 -m pip install SomePackage # specifically Python 3.4
|
||||
|
||||
(appropriately versioned ``pip`` commands may also be available)
|
||||
Appropriately versioned ``pip`` commands may also be available.
|
||||
|
||||
On Windows, use the ``py`` Python launcher in combination with the ``-m``
|
||||
switch::
|
||||
|
|
@ -212,11 +225,11 @@ as users are more regularly able to install pre-built extensions rather
|
|||
than needing to build them themselves.
|
||||
|
||||
Some of the solutions for installing `scientific software
|
||||
<https://packaging.python.org/en/latest/science/>`__
|
||||
that is not yet available as pre-built ``wheel`` files may also help with
|
||||
<https://packaging.python.org/science/>`__
|
||||
that are not yet available as pre-built ``wheel`` files may also help with
|
||||
obtaining other binary extensions without needing to build them locally.
|
||||
|
||||
.. seealso::
|
||||
|
||||
`Python Packaging User Guide: Binary Extensions
|
||||
<https://packaging.python.org/en/latest/extensions/>`__
|
||||
<https://packaging.python.org/extensions/>`__
|
||||
|
|
|
|||
|
|
@ -31,44 +31,50 @@ Creating virtual environments
|
|||
|
||||
.. _venv-def:
|
||||
|
||||
.. note:: A virtual environment (also called a ``venv``) is a Python
|
||||
environment such that the Python interpreter, libraries and scripts
|
||||
installed into it are isolated from those installed in other virtual
|
||||
environments, and (by default) any libraries installed in a "system" Python,
|
||||
i.e. one which is installed as part of your operating system.
|
||||
.. note:: A virtual environment is a Python environment such that the Python
|
||||
interpreter, libraries and scripts installed into it are isolated from those
|
||||
installed in other virtual environments, and (by default) any libraries
|
||||
installed in a "system" Python, i.e., one which is installed as part of your
|
||||
operating system.
|
||||
|
||||
A venv is a directory tree which contains Python executable files and
|
||||
other files which indicate that it is a venv.
|
||||
A virtual environment is a directory tree which contains Python executable
|
||||
files and other files which indicate that it is a virtual environment.
|
||||
|
||||
Common installation tools such as ``Setuptools`` and ``pip`` work as
|
||||
expected with venvs - i.e. when a venv is active, they install Python
|
||||
packages into the venv without needing to be told to do so explicitly.
|
||||
expected with virtual environments. In other words, when a virtual
|
||||
environment is active, they install Python packages into the virtual
|
||||
environment without needing to be told to do so explicitly.
|
||||
|
||||
When a venv is active (i.e. the venv's Python interpreter is running), the
|
||||
attributes :attr:`sys.prefix` and :attr:`sys.exec_prefix` point to the base
|
||||
directory of the venv, whereas :attr:`sys.base_prefix` and
|
||||
:attr:`sys.base_exec_prefix` point to the non-venv Python installation
|
||||
which was used to create the venv. If a venv is not active, then
|
||||
:attr:`sys.prefix` is the same as :attr:`sys.base_prefix` and
|
||||
:attr:`sys.exec_prefix` is the same as :attr:`sys.base_exec_prefix` (they
|
||||
all point to a non-venv Python installation).
|
||||
When a virtual environment is active (i.e., the virtual environment's Python
|
||||
interpreter is running), the attributes :attr:`sys.prefix` and
|
||||
:attr:`sys.exec_prefix` point to the base directory of the virtual
|
||||
environment, whereas :attr:`sys.base_prefix` and
|
||||
:attr:`sys.base_exec_prefix` point to the non-virtual environment Python
|
||||
installation which was used to create the virtual environment. If a virtual
|
||||
environment is not active, then :attr:`sys.prefix` is the same as
|
||||
:attr:`sys.base_prefix` and :attr:`sys.exec_prefix` is the same as
|
||||
:attr:`sys.base_exec_prefix` (they all point to a non-virtual environment
|
||||
Python installation).
|
||||
|
||||
When a venv is active, any options that change the installation path will be
|
||||
ignored from all distutils configuration files to prevent projects being
|
||||
inadvertently installed outside of the virtual environment.
|
||||
When a virtual environment is active, any options that change the
|
||||
installation path will be ignored from all distutils configuration files to
|
||||
prevent projects being inadvertently installed outside of the virtual
|
||||
environment.
|
||||
|
||||
When working in a command shell, users can make a venv active by running an
|
||||
``activate`` script in the venv's executables directory (the precise filename
|
||||
is shell-dependent), which prepends the venv's directory for executables to
|
||||
the ``PATH`` environment variable for the running shell. There should be no
|
||||
need in other circumstances to activate a venv -- scripts installed into
|
||||
venvs have a shebang line which points to the venv's Python interpreter. This
|
||||
means that the script will run with that interpreter regardless of the value
|
||||
of ``PATH``. On Windows, shebang line processing is supported if you have the
|
||||
Python Launcher for Windows installed (this was added to Python in 3.3 - see
|
||||
:pep:`397` for more details). Thus, double-clicking an installed script in
|
||||
a Windows Explorer window should run the script with the correct interpreter
|
||||
without there needing to be any reference to its venv in ``PATH``.
|
||||
When working in a command shell, users can make a virtual environment active
|
||||
by running an ``activate`` script in the virtual environment's executables
|
||||
directory (the precise filename is shell-dependent), which prepends the
|
||||
virtual environment's directory for executables to the ``PATH`` environment
|
||||
variable for the running shell. There should be no need in other
|
||||
circumstances to activate a virtual environment—scripts installed into
|
||||
virtual environments have a "shebang" line which points to the virtual
|
||||
environment's Python interpreter. This means that the script will run with
|
||||
that interpreter regardless of the value of ``PATH``. On Windows, "shebang"
|
||||
line processing is supported if you have the Python Launcher for Windows
|
||||
installed (this was added to Python in 3.3 - see :pep:`397` for more
|
||||
details). Thus, double-clicking an installed script in a Windows Explorer
|
||||
window should run the script with the correct interpreter without there
|
||||
needing to be any reference to its virtual environment in ``PATH``.
|
||||
|
||||
|
||||
.. _venv-api:
|
||||
|
|
@ -219,7 +225,7 @@ An example of extending ``EnvBuilder``
|
|||
--------------------------------------
|
||||
|
||||
The following script shows how to extend :class:`EnvBuilder` by implementing a
|
||||
subclass which installs setuptools and pip into a created venv::
|
||||
subclass which installs setuptools and pip into a created virtual environment::
|
||||
|
||||
import os
|
||||
import os.path
|
||||
|
|
@ -233,12 +239,12 @@ subclass which installs setuptools and pip into a created venv::
|
|||
class ExtendedEnvBuilder(venv.EnvBuilder):
|
||||
"""
|
||||
This builder installs setuptools and pip so that you can pip or
|
||||
easy_install other packages into the created environment.
|
||||
easy_install other packages into the created virtual environment.
|
||||
|
||||
:param nodist: If True, setuptools and pip are not installed into the
|
||||
created environment.
|
||||
created virtual environment.
|
||||
:param nopip: If True, pip is not installed into the created
|
||||
environment.
|
||||
virtual environment.
|
||||
:param progress: If setuptools or pip are installed, the progress of the
|
||||
installation can be monitored by passing a progress
|
||||
callable. If specified, it is called with two
|
||||
|
|
@ -264,10 +270,10 @@ subclass which installs setuptools and pip into a created venv::
|
|||
def post_setup(self, context):
|
||||
"""
|
||||
Set up any packages which need to be pre-installed into the
|
||||
environment being created.
|
||||
virtual environment being created.
|
||||
|
||||
:param context: The information for the environment creation request
|
||||
being processed.
|
||||
:param context: The information for the virtual environment
|
||||
creation request being processed.
|
||||
"""
|
||||
os.environ['VIRTUAL_ENV'] = context.env_dir
|
||||
if not self.nodist:
|
||||
|
|
@ -301,7 +307,7 @@ subclass which installs setuptools and pip into a created venv::
|
|||
fn = os.path.split(path)[-1]
|
||||
binpath = context.bin_path
|
||||
distpath = os.path.join(binpath, fn)
|
||||
# Download script into the env's binaries folder
|
||||
# Download script into the virtual environment's binaries folder
|
||||
urlretrieve(url, distpath)
|
||||
progress = self.progress
|
||||
if self.verbose:
|
||||
|
|
@ -313,7 +319,7 @@ subclass which installs setuptools and pip into a created venv::
|
|||
else:
|
||||
sys.stderr.write('Installing %s ...%s' % (name, term))
|
||||
sys.stderr.flush()
|
||||
# Install in the env
|
||||
# Install in the virtual environment
|
||||
args = [context.env_exe, fn]
|
||||
p = Popen(args, stdout=PIPE, stderr=PIPE, cwd=binpath)
|
||||
t1 = Thread(target=self.reader, args=(p.stdout, 'stdout'))
|
||||
|
|
@ -332,10 +338,10 @@ subclass which installs setuptools and pip into a created venv::
|
|||
|
||||
def install_setuptools(self, context):
|
||||
"""
|
||||
Install setuptools in the environment.
|
||||
Install setuptools in the virtual environment.
|
||||
|
||||
:param context: The information for the environment creation request
|
||||
being processed.
|
||||
:param context: The information for the virtual environment
|
||||
creation request being processed.
|
||||
"""
|
||||
url = 'https://bitbucket.org/pypa/setuptools/downloads/ez_setup.py'
|
||||
self.install_script(context, 'setuptools', url)
|
||||
|
|
@ -348,10 +354,10 @@ subclass which installs setuptools and pip into a created venv::
|
|||
|
||||
def install_pip(self, context):
|
||||
"""
|
||||
Install pip in the environment.
|
||||
Install pip in the virtual environment.
|
||||
|
||||
:param context: The information for the environment creation request
|
||||
being processed.
|
||||
:param context: The information for the virtual environment
|
||||
creation request being processed.
|
||||
"""
|
||||
url = 'https://raw.github.com/pypa/pip/master/contrib/get-pip.py'
|
||||
self.install_script(context, 'pip', url)
|
||||
|
|
@ -374,7 +380,8 @@ subclass which installs setuptools and pip into a created venv::
|
|||
'more target '
|
||||
'directories.')
|
||||
parser.add_argument('dirs', metavar='ENV_DIR', nargs='+',
|
||||
help='A directory to create the environment in.')
|
||||
help='A directory in which to create the
|
||||
'virtual environment.')
|
||||
parser.add_argument('--no-setuptools', default=False,
|
||||
action='store_true', dest='nodist',
|
||||
help="Don't install setuptools or pip in the "
|
||||
|
|
@ -398,14 +405,17 @@ subclass which installs setuptools and pip into a created venv::
|
|||
'the platform.')
|
||||
parser.add_argument('--clear', default=False, action='store_true',
|
||||
dest='clear', help='Delete the contents of the '
|
||||
'environment directory if it '
|
||||
'already exists, before '
|
||||
'virtual environment '
|
||||
'directory if it already '
|
||||
'exists, before virtual '
|
||||
'environment creation.')
|
||||
parser.add_argument('--upgrade', default=False, action='store_true',
|
||||
dest='upgrade', help='Upgrade the environment '
|
||||
'directory to use this version '
|
||||
'of Python, assuming Python '
|
||||
'has been upgraded in-place.')
|
||||
dest='upgrade', help='Upgrade the virtual '
|
||||
'environment directory to '
|
||||
'use this version of '
|
||||
'Python, assuming Python '
|
||||
'has been upgraded '
|
||||
'in-place.')
|
||||
parser.add_argument('--verbose', default=False, action='store_true',
|
||||
dest='verbose', help='Display the output '
|
||||
'from the scripts which '
|
||||
|
|
|
|||
|
|
@ -20,15 +20,14 @@ the requirements of every application. If application A needs version
|
|||
the requirements are in conflict and installing either version 1.0 or 2.0
|
||||
will leave one application unable to run.
|
||||
|
||||
The solution for this problem is to create a :term:`virtual
|
||||
environment` (often shortened to "virtualenv"), a self-contained
|
||||
directory tree that contains a Python installation for a particular
|
||||
version of Python, plus a number of additional packages.
|
||||
The solution for this problem is to create a :term:`virtual environment`, a
|
||||
self-contained directory tree that contains a Python installation for a
|
||||
particular version of Python, plus a number of additional packages.
|
||||
|
||||
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 virtualenv with version 2.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.
|
||||
|
||||
|
|
@ -36,29 +35,26 @@ not affect application A's environment.
|
|||
Creating Virtual Environments
|
||||
=============================
|
||||
|
||||
The script used to create and manage virtual environments is called
|
||||
:program:`pyvenv`. :program:`pyvenv` will usually install the most
|
||||
recent version of Python that you have available; the script is also
|
||||
installed with a version number, so if you have multiple versions of
|
||||
Python on your system you can select a specific Python version by
|
||||
running ``pyvenv-3.4`` or whichever version you want.
|
||||
The module used to create and manage virtual environments is called
|
||||
:mod:`venv`. :mod:`venv` 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 ``python3`` or
|
||||
whichever version you want.
|
||||
|
||||
To create a virtualenv, decide upon a directory
|
||||
where you want to place it and run :program:`pyvenv` with the
|
||||
directory path::
|
||||
To create a virtual environment, decide upon a directory where you want to
|
||||
place it, and run the :mod:`venv` module as a script with the directory path::
|
||||
|
||||
pyvenv tutorial-env
|
||||
python3 -m venv tutorial-env
|
||||
|
||||
This will create the ``tutorial-env`` directory if it doesn't exist,
|
||||
and also create directories inside it containing a copy of the Python
|
||||
interpreter, the standard library, and various supporting files.
|
||||
|
||||
Once you've created a virtual environment, you need to
|
||||
activate it.
|
||||
Once you've created a virtual environment, you may activate it.
|
||||
|
||||
On Windows, run::
|
||||
|
||||
tutorial-env/Scripts/activate
|
||||
tutorial-env\Scripts\activate.bat
|
||||
|
||||
On Unix or MacOS, run::
|
||||
|
||||
|
|
@ -69,33 +65,36 @@ On Unix or MacOS, run::
|
|||
``activate.csh`` and ``activate.fish`` scripts you should use
|
||||
instead.)
|
||||
|
||||
Activating the virtualenv will change your shell's prompt to show what
|
||||
virtualenv you're using, and modify the environment so that running
|
||||
``python`` will get you that particular version and installation of
|
||||
Python. For example::
|
||||
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
|
||||
``python`` will get you that particular version and installation of Python.
|
||||
For example:
|
||||
|
||||
-> source ~/envs/tutorial-env/bin/activate
|
||||
(tutorial-env) -> python
|
||||
Python 3.4.3+ (3.4:c7b9645a6f35+, May 22 2015, 09:31:25)
|
||||
.. code-block:: 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/python34.zip', ...,
|
||||
'~/envs/tutorial-env/lib/python3.4/site-packages']
|
||||
['', '/usr/local/lib/python35.zip', ...,
|
||||
'~/envs/tutorial-env/lib/python3.5/site-packages']
|
||||
>>>
|
||||
|
||||
|
||||
Managing Packages with pip
|
||||
==========================
|
||||
|
||||
Once you've activated a virtual environment, you can install, upgrade,
|
||||
and remove packages using a program called :program:`pip`. By default
|
||||
``pip`` will install packages from the Python Package Index,
|
||||
<https://pypi.python.org/pypi>. You can browse the Python Package Index
|
||||
by going to it in your web browser, or you can use ``pip``'s
|
||||
limited search feature::
|
||||
You can install, upgrade, and remove packages using a program called
|
||||
:program:`pip`. By default ``pip`` will install packages from the Python
|
||||
Package Index, <https://pypi.python.org/pypi>. You can browse the Python
|
||||
Package Index by going to it in your web browser, or you can use ``pip``'s
|
||||
limited search feature:
|
||||
|
||||
(tutorial-env) -> pip search astronomy
|
||||
.. code-block:: bash
|
||||
|
||||
(tutorial-env) $ pip search astronomy
|
||||
skyfield - Elegant astronomy for Python
|
||||
gary - Galactic astronomy and gravitational dynamics.
|
||||
novas - The United States Naval Observatory NOVAS astronomy library
|
||||
|
|
@ -107,9 +106,11 @@ limited search feature::
|
|||
"freeze", etc. (Consult the :ref:`installing-index` guide for
|
||||
complete documentation for ``pip``.)
|
||||
|
||||
You can install the latest version of a package by specifying a package's name::
|
||||
You can install the latest version of a package by specifying a package's name:
|
||||
|
||||
-> pip install novas
|
||||
.. code-block:: bash
|
||||
|
||||
(tutorial-env) $ pip install novas
|
||||
Collecting novas
|
||||
Downloading novas-3.1.1.3.tar.gz (136kB)
|
||||
Installing collected packages: novas
|
||||
|
|
@ -117,9 +118,11 @@ You can install the latest version of a package by specifying a package's name::
|
|||
Successfully installed novas-3.1.1.3
|
||||
|
||||
You can also install a specific version of a package by giving the
|
||||
package name followed by ``==`` and the version number::
|
||||
package name followed by ``==`` and the version number:
|
||||
|
||||
-> pip install requests==2.6.0
|
||||
.. code-block:: bash
|
||||
|
||||
(tutorial-env) $ 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
|
||||
|
|
@ -128,9 +131,11 @@ package name followed by ``==`` and the version number::
|
|||
If you re-run this command, ``pip`` 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 ``pip
|
||||
install --upgrade`` to upgrade the package to the latest version::
|
||||
install --upgrade`` to upgrade the package to the latest version:
|
||||
|
||||
-> pip install --upgrade requests
|
||||
.. code-block:: bash
|
||||
|
||||
(tutorial-env) $ pip install --upgrade requests
|
||||
Collecting requests
|
||||
Installing collected packages: requests
|
||||
Found existing installation: requests 2.6.0
|
||||
|
|
@ -141,9 +146,11 @@ install --upgrade`` to upgrade the package to the latest version::
|
|||
``pip uninstall`` followed by one or more package names will remove the
|
||||
packages from the virtual environment.
|
||||
|
||||
``pip show`` will display information about a particular package::
|
||||
``pip show`` will display information about a particular package:
|
||||
|
||||
(tutorial-env) -> pip show requests
|
||||
.. code-block:: bash
|
||||
|
||||
(tutorial-env) $ pip show requests
|
||||
---
|
||||
Metadata-Version: 2.0
|
||||
Name: requests
|
||||
|
|
@ -157,9 +164,11 @@ packages from the virtual environment.
|
|||
Requires:
|
||||
|
||||
``pip list`` will display all of the packages installed in the virtual
|
||||
environment::
|
||||
environment:
|
||||
|
||||
(tutorial-env) -> pip list
|
||||
.. code-block:: bash
|
||||
|
||||
(tutorial-env) $ pip list
|
||||
novas (3.1.1.3)
|
||||
numpy (1.9.2)
|
||||
pip (7.0.3)
|
||||
|
|
@ -168,19 +177,23 @@ environment::
|
|||
|
||||
``pip freeze`` will produce a similar list of the installed packages,
|
||||
but the output uses the format that ``pip install`` expects.
|
||||
A common convention is to put this list in a ``requirements.txt`` file::
|
||||
A common convention is to put this list in a ``requirements.txt`` file:
|
||||
|
||||
(tutorial-env) -> pip freeze > requirements.txt
|
||||
(tutorial-env) -> cat requirements.txt
|
||||
.. code-block:: bash
|
||||
|
||||
(tutorial-env) $ pip freeze > requirements.txt
|
||||
(tutorial-env) $ cat requirements.txt
|
||||
novas==3.1.1.3
|
||||
numpy==1.9.2
|
||||
requests==2.7.0
|
||||
|
||||
The ``requirements.txt`` can then be committed to version control and
|
||||
shipped as part of an application. Users can then install all the
|
||||
necessary packages with ``install -r``::
|
||||
necessary packages with ``install -r``:
|
||||
|
||||
-> pip install -r requirements.txt
|
||||
.. code-block:: bash
|
||||
|
||||
(tutorial-env) $ 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))
|
||||
|
|
|
|||
|
|
@ -17,4 +17,3 @@ interpreter and things that make working with Python easier.
|
|||
unix.rst
|
||||
windows.rst
|
||||
mac.rst
|
||||
scripts.rst
|
||||
|
|
|
|||
|
|
@ -1,12 +0,0 @@
|
|||
.. _tools-and-scripts:
|
||||
|
||||
Additional Tools and Scripts
|
||||
============================
|
||||
|
||||
.. _scripts-pyvenv:
|
||||
|
||||
pyvenv - Creating virtual environments
|
||||
--------------------------------------
|
||||
|
||||
.. include:: venv-create.inc
|
||||
|
||||
|
|
@ -1,31 +1,39 @@
|
|||
Creation of :ref:`virtual environments <venv-def>` is done by executing the
|
||||
``pyvenv`` script::
|
||||
command ``venv``::
|
||||
|
||||
pyvenv /path/to/new/virtual/environment
|
||||
python3 -m venv /path/to/new/virtual/environment
|
||||
|
||||
Running this command creates the target directory (creating any parent
|
||||
directories that don't exist already) and places a ``pyvenv.cfg`` file in it
|
||||
with a ``home`` key pointing to the Python installation the command was run
|
||||
from. It also creates a ``bin`` (or ``Scripts`` on Windows) subdirectory
|
||||
with a ``home`` key pointing to the Python installation from which the command
|
||||
was run. It also creates a ``bin`` (or ``Scripts`` on Windows) subdirectory
|
||||
containing a copy of the ``python`` binary (or binaries, in the case of
|
||||
Windows). It also creates an (initially empty) ``lib/pythonX.Y/site-packages``
|
||||
subdirectory (on Windows, this is ``Lib\site-packages``).
|
||||
|
||||
.. deprecated:: 3.6
|
||||
``pyvenv`` was the recommended tool for creating virtual environments for
|
||||
Python 3.3 and 3.4, and is `deprecated in Python 3.6
|
||||
<https://docs.python.org/dev/whatsnew/3.6.html#deprecated-features>`_.
|
||||
|
||||
.. versionchanged:: 3.5
|
||||
The use of ``venv`` is now recommended for creating virtual environments.
|
||||
|
||||
.. seealso::
|
||||
|
||||
`Python Packaging User Guide: Creating and using virtual environments
|
||||
<https://packaging.python.org/en/latest/installing/#creating-virtual-environments>`__
|
||||
<https://packaging.python.org/installing/#creating-virtual-environments>`__
|
||||
|
||||
.. highlight:: none
|
||||
|
||||
On Windows, you may have to invoke the ``pyvenv`` script as follows, if you
|
||||
don't have the relevant PATH and PATHEXT settings::
|
||||
On Windows, invoke the ``venv`` command as follows::
|
||||
|
||||
c:\Temp>c:\Python35\python c:\Python35\Tools\Scripts\pyvenv.py myenv
|
||||
c:\>c:\Python35\python -m venv c:\path\to\myenv
|
||||
|
||||
or equivalently::
|
||||
Alternatively, if you configured the ``PATH`` and ``PATHEXT`` variables for
|
||||
your :ref:`Python installation <using-on-windows>`::
|
||||
|
||||
c:\Temp>c:\Python35\python -m venv myenv
|
||||
c:\>python -m venv myenv c:\path\to\myenv
|
||||
|
||||
The command, if run with ``-h``, will show the available options::
|
||||
|
||||
|
|
@ -36,25 +44,26 @@ The command, if run with ``-h``, will show the available options::
|
|||
Creates virtual Python environments in one or more target directories.
|
||||
|
||||
positional arguments:
|
||||
ENV_DIR A directory to create the environment in.
|
||||
ENV_DIR A directory to create the environment in.
|
||||
|
||||
optional arguments:
|
||||
-h, --help show this help message and exit
|
||||
--system-site-packages Give the virtual environment access to the system
|
||||
site-packages dir.
|
||||
--symlinks Try to use symlinks rather than copies, when symlinks
|
||||
are not the default for the platform.
|
||||
--copies Try to use copies rather than symlinks, even when
|
||||
symlinks are the default for the platform.
|
||||
--clear Delete the contents of the environment directory if it
|
||||
already exists, before environment creation.
|
||||
--upgrade Upgrade the environment directory to use this version
|
||||
of Python, assuming Python has been upgraded in-place.
|
||||
--without-pip Skips installing or upgrading pip in the virtual
|
||||
environment (pip is bootstrapped by default)
|
||||
-h, --help show this help message and exit
|
||||
--system-site-packages
|
||||
Give the virtual environment access to the system
|
||||
site-packages dir.
|
||||
--symlinks Try to use symlinks rather than copies, when symlinks
|
||||
are not the default for the platform.
|
||||
--copies Try to use copies rather than symlinks, even when
|
||||
symlinks are the default for the platform.
|
||||
--clear Delete the contents of the environment directory if it
|
||||
already exists, before environment creation.
|
||||
--upgrade Upgrade the environment directory to use this version
|
||||
of Python, assuming Python has been upgraded in-place.
|
||||
--without-pip Skips installing or upgrading pip in the virtual
|
||||
environment (pip is bootstrapped by default)
|
||||
|
||||
Depending on how the ``venv`` functionality has been invoked, the usage message
|
||||
may vary slightly, e.g. referencing ``pyvenv`` rather than ``venv``.
|
||||
Once an environment has been created, you may wish to activate it, e.g. by
|
||||
sourcing an activate script in its bin directory.
|
||||
|
||||
.. versionchanged:: 3.4
|
||||
Installs pip by default, added the ``--without-pip`` and ``--copies``
|
||||
|
|
@ -73,12 +82,13 @@ run with the ``--system-site-packages`` option, ``false`` otherwise.
|
|||
Unless the ``--without-pip`` option is given, :mod:`ensurepip` will be
|
||||
invoked to bootstrap ``pip`` into the virtual environment.
|
||||
|
||||
Multiple paths can be given to ``pyvenv``, in which case an identical
|
||||
virtualenv will be created, according to the given options, at each
|
||||
provided path.
|
||||
Multiple paths can be given to ``venv``, in which case an identical virtual
|
||||
environment will be created, according to the given options, at each provided
|
||||
path.
|
||||
|
||||
Once a venv has been created, it can be "activated" using a script in the
|
||||
venv's binary directory. The invocation of the script is platform-specific:
|
||||
Once a virtual environment has been created, it can be "activated" using a
|
||||
script in the virtual environment's binary directory. The invocation of the
|
||||
script is platform-specific:
|
||||
|
||||
+-------------+-----------------+-----------------------------------------+
|
||||
| Platform | Shell | Command to activate virtual environment |
|
||||
|
|
@ -95,16 +105,17 @@ venv's binary directory. The invocation of the script is platform-specific:
|
|||
+-------------+-----------------+-----------------------------------------+
|
||||
|
||||
You don't specifically *need* to activate an environment; activation just
|
||||
prepends the venv's binary directory to your path, so that "python" invokes the
|
||||
venv's Python interpreter and you can run installed scripts without having to
|
||||
use their full path. However, all scripts installed in a venv should be
|
||||
runnable without activating it, and run with the venv's Python automatically.
|
||||
prepends the virtual environment's binary directory to your path, so that
|
||||
"python" invokes the virtual environment's Python interpreter and you can run
|
||||
installed scripts without having to use their full path. However, all scripts
|
||||
installed in a virtual environment should be runnable without activating it,
|
||||
and run with the virtual environment's Python automatically.
|
||||
|
||||
You can deactivate a venv by typing "deactivate" in your shell. The exact
|
||||
mechanism is platform-specific: for example, the Bash activation script defines
|
||||
a "deactivate" function, whereas on Windows there are separate scripts called
|
||||
``deactivate.bat`` and ``Deactivate.ps1`` which are installed when the venv is
|
||||
created.
|
||||
You can deactivate a virtual environment by typing "deactivate" in your shell.
|
||||
The exact mechanism is platform-specific: for example, the Bash activation
|
||||
script defines a "deactivate" function, whereas on Windows there are separate
|
||||
scripts called ``deactivate.bat`` and ``Deactivate.ps1`` which are installed
|
||||
when the virtual environment is created.
|
||||
|
||||
.. versionadded:: 3.4
|
||||
``fish`` and ``csh`` activation scripts.
|
||||
|
|
|
|||
|
|
@ -1150,6 +1150,7 @@ Dusty Phillips
|
|||
Christopher J. Phoenix
|
||||
James Pickering
|
||||
Neale Pickett
|
||||
Steve Piercy
|
||||
Jim St. Pierre
|
||||
Dan Pierson
|
||||
Martijn Pieters
|
||||
|
|
|
|||
|
|
@ -154,6 +154,12 @@ Tools/Demos
|
|||
|
||||
- Issue #27418: Fixed Tools/importbench/importbench.py.
|
||||
|
||||
Documentation
|
||||
-------------
|
||||
|
||||
- Issue #27285: Update documentation to reflect the deprecation of ``pyvenv``
|
||||
and normalize on the term "virtual environment". Patch by Steve Piercy.
|
||||
|
||||
|
||||
What's New in Python 3.6.0 alpha 2
|
||||
==================================
|
||||
|
|
|
|||
Loading…
Reference in New Issue