2012-05-25 23:45:29 -03:00
|
|
|
:mod:`venv` --- Creation of virtual environments
|
|
|
|
================================================
|
|
|
|
|
|
|
|
.. module:: venv
|
|
|
|
:synopsis: Creation of virtual environments.
|
|
|
|
.. moduleauthor:: Vinay Sajip <vinay_sajip@yahoo.co.uk>
|
|
|
|
.. sectionauthor:: Vinay Sajip <vinay_sajip@yahoo.co.uk>
|
|
|
|
|
|
|
|
|
|
|
|
.. index:: pair: Environments; virtual
|
|
|
|
|
|
|
|
.. versionadded:: 3.3
|
|
|
|
|
|
|
|
**Source code:** :source:`Lib/venv.py`
|
|
|
|
|
|
|
|
--------------
|
|
|
|
|
2012-06-24 11:37:59 -03:00
|
|
|
The :mod:`venv` module provides support for creating lightweight "virtual
|
|
|
|
environments" with their own site directories, optionally isolated from system
|
|
|
|
site directories. Each virtual environment has its own Python binary (allowing
|
|
|
|
creation of environments with various Python versions) and can have its own
|
|
|
|
independent set of installed Python packages in its site directories.
|
|
|
|
|
2012-05-25 23:45:29 -03:00
|
|
|
|
|
|
|
Creating virtual environments
|
|
|
|
-----------------------------
|
|
|
|
|
2012-06-24 11:37:59 -03:00
|
|
|
Creation of virtual environments is simplest executing the ``pyvenv`` script::
|
2012-05-25 23:45:29 -03:00
|
|
|
|
|
|
|
pyvenv /path/to/new/virtual/environment
|
|
|
|
|
|
|
|
Running this command creates the target directory (creating any parent
|
2012-06-24 11:37:59 -03:00
|
|
|
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
|
|
|
|
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``
|
2012-05-25 23:45:29 -03:00
|
|
|
subdirectory (on Windows, this is ``Lib\site-packages``).
|
|
|
|
|
|
|
|
.. 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::
|
|
|
|
|
|
|
|
c:\Temp>c:\Python33\python c:\Python33\Tools\Scripts\pyvenv.py myenv
|
|
|
|
|
|
|
|
or equivalently::
|
|
|
|
|
|
|
|
c:\Temp>c:\Python33\python -m venv myenv
|
|
|
|
|
|
|
|
The command, if run with ``-h``, will show the available options::
|
|
|
|
|
2012-07-09 05:24:59 -03:00
|
|
|
usage: pyvenv [-h] [--system-site-packages] [--symlinks] [--clear]
|
2012-05-29 08:52:14 -03:00
|
|
|
[--upgrade] ENV_DIR [ENV_DIR ...]
|
2012-05-25 23:45:29 -03:00
|
|
|
|
|
|
|
Creates virtual Python environments in one or more target directories.
|
|
|
|
|
|
|
|
positional arguments:
|
|
|
|
ENV_DIR A directory to create the environment in.
|
|
|
|
|
|
|
|
optional arguments:
|
|
|
|
-h, --help show this help message and exit
|
|
|
|
--system-site-packages Give access to the global site-packages dir to the
|
|
|
|
virtual environment.
|
2012-07-09 05:24:59 -03:00
|
|
|
--symlinks Try to use symlinks rather than copies, when symlinks
|
|
|
|
are not the default for the platform.
|
2012-05-25 23:45:29 -03:00
|
|
|
--clear Delete the environment directory if it already exists.
|
|
|
|
If not specified and the directory exists, an error is
|
|
|
|
raised.
|
2012-05-29 08:52:14 -03:00
|
|
|
--upgrade Upgrade the environment directory to use this version
|
|
|
|
of Python, assuming Python has been upgraded in-place.
|
2012-05-25 23:45:29 -03:00
|
|
|
|
2012-06-24 11:37:59 -03:00
|
|
|
If the target directory already exists an error will be raised, unless the
|
|
|
|
``--clear`` or ``--upgrade`` option was provided.
|
2012-05-25 23:45:29 -03:00
|
|
|
|
|
|
|
The created ``pyvenv.cfg`` file also includes the
|
2012-06-24 11:37:59 -03:00
|
|
|
``include-system-site-packages`` key, set to ``true`` if ``venv`` is run with
|
|
|
|
the ``--system-site-packages`` option, ``false`` otherwise.
|
2012-05-25 23:45:29 -03:00
|
|
|
|
2012-06-24 11:37:59 -03:00
|
|
|
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.
|
2012-05-25 23:45:29 -03:00
|
|
|
|
2012-07-09 05:24:59 -03:00
|
|
|
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: on
|
|
|
|
a Posix platform, you would typically do::
|
|
|
|
|
|
|
|
$ source <venv>/bin/activate
|
|
|
|
|
|
|
|
whereas on Windows, you might do::
|
|
|
|
|
2012-07-09 06:37:01 -03:00
|
|
|
C:\> <venv>/Scripts/activate
|
2012-07-09 05:24:59 -03:00
|
|
|
|
|
|
|
if you are using the ``cmd.exe`` shell, or perhaps::
|
|
|
|
|
|
|
|
PS C:\> <venv>/Scripts/Activate.ps1
|
|
|
|
|
|
|
|
if you use PowerShell.
|
|
|
|
|
|
|
|
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.
|
|
|
|
|
|
|
|
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.
|
|
|
|
|
2012-07-09 06:37:01 -03:00
|
|
|
.. _venv-def:
|
|
|
|
|
2012-07-09 05:24:59 -03:00
|
|
|
.. 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.
|
|
|
|
|
|
|
|
A venv is a directory tree which contains Python executable files and
|
|
|
|
other files which indicate that it is a venv.
|
|
|
|
|
|
|
|
Common installation tools such as ``distribute`` 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.
|
|
|
|
|
|
|
|
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).
|
|
|
|
|
2012-05-25 23:45:29 -03:00
|
|
|
|
|
|
|
API
|
|
|
|
---
|
|
|
|
|
2012-06-24 11:37:59 -03:00
|
|
|
.. highlight:: python
|
|
|
|
|
2012-05-25 23:45:29 -03:00
|
|
|
The high-level method described above makes use of a simple API which provides
|
2012-06-24 11:37:59 -03:00
|
|
|
mechanisms for third-party virtual environment creators to customize environment
|
|
|
|
creation according to their needs, the :class:`EnvBuilder` class.
|
2012-05-25 23:45:29 -03:00
|
|
|
|
2012-06-24 11:37:59 -03:00
|
|
|
.. class:: EnvBuilder(system_site_packages=False, clear=False, symlinks=False, upgrade=False)
|
2012-05-25 23:45:29 -03:00
|
|
|
|
2012-06-24 11:37:59 -03:00
|
|
|
The :class:`EnvBuilder` class accepts the following keyword arguments on
|
|
|
|
instantiation:
|
2012-05-25 23:45:29 -03:00
|
|
|
|
2012-06-24 11:37:59 -03:00
|
|
|
* ``system_site_packages`` -- a Boolean value indicating that the system Python
|
|
|
|
site-packages should be available to the environment (defaults to ``False``).
|
2012-05-25 23:45:29 -03:00
|
|
|
|
2012-06-24 11:37:59 -03:00
|
|
|
* ``clear`` -- a Boolean value which, if True, will delete any existing target
|
|
|
|
directory instead of raising an exception (defaults to ``False``).
|
2012-05-25 23:45:29 -03:00
|
|
|
|
2012-06-24 11:37:59 -03:00
|
|
|
* ``symlinks`` -- a Boolean value indicating whether to attempt to symlink the
|
|
|
|
Python binary (and any necessary DLLs or other binaries,
|
|
|
|
e.g. ``pythonw.exe``), rather than copying. Defaults to ``True`` on Linux and
|
|
|
|
Unix systems, but ``False`` on Windows and Mac OS X.
|
2012-05-25 23:45:29 -03:00
|
|
|
|
2012-07-09 05:24:59 -03:00
|
|
|
* ``upgrade`` -- a Boolean value which, if True, will upgrade an existing
|
|
|
|
environment with the running Python - for use when that Python has been
|
|
|
|
upgraded in-place (defaults to ``False``).
|
|
|
|
|
2012-05-25 23:45:29 -03:00
|
|
|
|
|
|
|
|
2012-06-24 11:37:59 -03:00
|
|
|
Creators of third-party virtual environment tools will be free to use the
|
|
|
|
provided ``EnvBuilder`` class as a base class.
|
|
|
|
|
|
|
|
The returned env-builder is an object which has a method, ``create``:
|
|
|
|
|
|
|
|
.. method:: create(env_dir)
|
|
|
|
|
|
|
|
This method takes as required argument the path (absolute or relative to
|
|
|
|
the current directory) of the target directory which is to contain the
|
|
|
|
virtual environment. The ``create`` method will either create the
|
|
|
|
environment in the specified directory, or raise an appropriate
|
|
|
|
exception.
|
|
|
|
|
|
|
|
The ``create`` method of the ``EnvBuilder`` class illustrates the hooks
|
|
|
|
available for subclass customization::
|
|
|
|
|
|
|
|
def create(self, env_dir):
|
|
|
|
"""
|
|
|
|
Create a virtualized Python environment in a directory.
|
|
|
|
env_dir is the target directory to create an environment in.
|
|
|
|
"""
|
|
|
|
env_dir = os.path.abspath(env_dir)
|
|
|
|
context = self.create_directories(env_dir)
|
|
|
|
self.create_configuration(context)
|
|
|
|
self.setup_python(context)
|
|
|
|
self.setup_scripts(context)
|
|
|
|
self.post_setup(context)
|
|
|
|
|
|
|
|
Each of the methods :meth:`create_directories`,
|
|
|
|
:meth:`create_configuration`, :meth:`setup_python`,
|
|
|
|
:meth:`setup_scripts` and :meth:`post_setup` can be overridden.
|
|
|
|
|
|
|
|
.. method:: create_directories(env_dir)
|
|
|
|
|
|
|
|
Creates the environment directory and all necessary directories, and
|
|
|
|
returns a context object. This is just a holder for attributes (such as
|
|
|
|
paths), for use by the other methods.
|
|
|
|
|
|
|
|
.. method:: create_configuration(context)
|
|
|
|
|
|
|
|
Creates the ``pyvenv.cfg`` configuration file in the environment.
|
|
|
|
|
|
|
|
.. method:: setup_python(context)
|
|
|
|
|
|
|
|
Creates a copy of the Python executable (and, under Windows, DLLs) in
|
|
|
|
the environment.
|
|
|
|
|
|
|
|
.. method:: setup_scripts(context)
|
|
|
|
|
|
|
|
Installs activation scripts appropriate to the platform into the virtual
|
|
|
|
environment.
|
|
|
|
|
|
|
|
.. method:: post_setup(context)
|
|
|
|
|
|
|
|
A placeholder method which can be overridden in third party
|
|
|
|
implementations to pre-install packages in the virtual environment or
|
|
|
|
perform other post-creation steps.
|
|
|
|
|
|
|
|
In addition, :class:`EnvBuilder` provides this utility method that can be
|
|
|
|
called from :meth:`setup_scripts` or :meth:`post_setup` in subclasses to
|
|
|
|
assist in installing custom scripts into the virtual environment.
|
|
|
|
|
|
|
|
.. method:: install_scripts(context, path)
|
|
|
|
|
|
|
|
*path* is the path to a directory that should contain subdirectories
|
|
|
|
"common", "posix", "nt", each containing scripts destined for the bin
|
|
|
|
directory in the environment. The contents of "common" and the
|
|
|
|
directory corresponding to :data:`os.name` are copied after some text
|
|
|
|
replacement of placeholders:
|
|
|
|
|
|
|
|
* ``__VENV_DIR__`` is replaced with the absolute path of the environment
|
|
|
|
directory.
|
|
|
|
|
|
|
|
* ``__VENV_NAME__`` is replaced with the environment name (final path
|
|
|
|
segment of environment directory).
|
|
|
|
|
|
|
|
* ``__VENV_BIN_NAME__`` is replaced with the name of the bin directory
|
|
|
|
(either ``bin`` or ``Scripts``).
|
|
|
|
|
|
|
|
* ``__VENV_PYTHON__`` is replaced with the absolute path of the
|
|
|
|
environment's executable.
|
|
|
|
|
|
|
|
|
|
|
|
There is also a module-level convenience function:
|
|
|
|
|
|
|
|
.. function:: create(env_dir, system_site_packages=False, clear=False, symlinks=False)
|
|
|
|
|
|
|
|
Create an :class:`EnvBuilder` with the given keyword arguments, and call its
|
|
|
|
:meth:`~EnvBuilder.create` method with the *env_dir* argument.
|