Vinay Sajip | 7ded1f0 | 2012-05-26 03:45:29 +0100 | [diff] [blame] | 1 | :mod:`venv` --- Creation of virtual environments |
| 2 | ================================================ |
| 3 | |
| 4 | .. module:: venv |
| 5 | :synopsis: Creation of virtual environments. |
| 6 | .. moduleauthor:: Vinay Sajip <vinay_sajip@yahoo.co.uk> |
| 7 | .. sectionauthor:: Vinay Sajip <vinay_sajip@yahoo.co.uk> |
| 8 | |
| 9 | |
| 10 | .. index:: pair: Environments; virtual |
| 11 | |
| 12 | .. versionadded:: 3.3 |
| 13 | |
| 14 | **Source code:** :source:`Lib/venv.py` |
| 15 | |
| 16 | -------------- |
| 17 | |
Georg Brandl | dbab58f | 2012-06-24 16:37:59 +0200 | [diff] [blame] | 18 | The :mod:`venv` module provides support for creating lightweight "virtual |
| 19 | environments" with their own site directories, optionally isolated from system |
| 20 | site directories. Each virtual environment has its own Python binary (allowing |
| 21 | creation of environments with various Python versions) and can have its own |
| 22 | independent set of installed Python packages in its site directories. |
| 23 | |
Vinay Sajip | 7ded1f0 | 2012-05-26 03:45:29 +0100 | [diff] [blame] | 24 | |
| 25 | Creating virtual environments |
| 26 | ----------------------------- |
| 27 | |
Vinay Sajip | c4618e3 | 2012-07-10 08:21:07 +0100 | [diff] [blame] | 28 | .. include:: /using/venv-create.inc |
Vinay Sajip | 7ded1f0 | 2012-05-26 03:45:29 +0100 | [diff] [blame] | 29 | |
Vinay Sajip | a945ad1 | 2012-07-09 09:24:59 +0100 | [diff] [blame] | 30 | |
Vinay Sajip | cd9b746 | 2012-07-09 10:37:01 +0100 | [diff] [blame] | 31 | .. _venv-def: |
| 32 | |
Vinay Sajip | a945ad1 | 2012-07-09 09:24:59 +0100 | [diff] [blame] | 33 | .. note:: A virtual environment (also called a ``venv``) is a Python |
| 34 | environment such that the Python interpreter, libraries and scripts |
| 35 | installed into it are isolated from those installed in other virtual |
| 36 | environments, and (by default) any libraries installed in a "system" Python, |
| 37 | i.e. one which is installed as part of your operating system. |
| 38 | |
| 39 | A venv is a directory tree which contains Python executable files and |
| 40 | other files which indicate that it is a venv. |
| 41 | |
Vinay Sajip | c4618e3 | 2012-07-10 08:21:07 +0100 | [diff] [blame] | 42 | Common installation tools such as ``Distribute`` and ``pip`` work as |
Vinay Sajip | a945ad1 | 2012-07-09 09:24:59 +0100 | [diff] [blame] | 43 | expected with venvs - i.e. when a venv is active, they install Python |
| 44 | packages into the venv without needing to be told to do so explicitly. |
Vinay Sajip | c4618e3 | 2012-07-10 08:21:07 +0100 | [diff] [blame] | 45 | Of course, you need to install them into the venv first: this could be |
| 46 | done by running ``distribute_setup.py`` with the venv activated, |
| 47 | followed by running ``easy_install pip``. Alternatively, you could download |
| 48 | the source tarballs and run ``python setup.py install`` after unpacking, |
| 49 | with the venv activated. |
Vinay Sajip | a945ad1 | 2012-07-09 09:24:59 +0100 | [diff] [blame] | 50 | |
| 51 | When a venv is active (i.e. the venv's Python interpreter is running), the |
| 52 | attributes :attr:`sys.prefix` and :attr:`sys.exec_prefix` point to the base |
| 53 | directory of the venv, whereas :attr:`sys.base_prefix` and |
| 54 | :attr:`sys.base_exec_prefix` point to the non-venv Python installation |
| 55 | which was used to create the venv. If a venv is not active, then |
| 56 | :attr:`sys.prefix` is the same as :attr:`sys.base_prefix` and |
| 57 | :attr:`sys.exec_prefix` is the same as :attr:`sys.base_exec_prefix` (they |
| 58 | all point to a non-venv Python installation). |
| 59 | |
Vinay Sajip | 7ded1f0 | 2012-05-26 03:45:29 +0100 | [diff] [blame] | 60 | |
| 61 | API |
| 62 | --- |
| 63 | |
Vinay Sajip | 7ded1f0 | 2012-05-26 03:45:29 +0100 | [diff] [blame] | 64 | .. highlight:: python |
| 65 | |
Georg Brandl | dbab58f | 2012-06-24 16:37:59 +0200 | [diff] [blame] | 66 | The high-level method described above makes use of a simple API which provides |
| 67 | mechanisms for third-party virtual environment creators to customize environment |
| 68 | creation according to their needs, the :class:`EnvBuilder` class. |
Vinay Sajip | 7ded1f0 | 2012-05-26 03:45:29 +0100 | [diff] [blame] | 69 | |
Georg Brandl | dbab58f | 2012-06-24 16:37:59 +0200 | [diff] [blame] | 70 | .. class:: EnvBuilder(system_site_packages=False, clear=False, symlinks=False, upgrade=False) |
Vinay Sajip | 7ded1f0 | 2012-05-26 03:45:29 +0100 | [diff] [blame] | 71 | |
Georg Brandl | dbab58f | 2012-06-24 16:37:59 +0200 | [diff] [blame] | 72 | The :class:`EnvBuilder` class accepts the following keyword arguments on |
| 73 | instantiation: |
Vinay Sajip | 7ded1f0 | 2012-05-26 03:45:29 +0100 | [diff] [blame] | 74 | |
Georg Brandl | dbab58f | 2012-06-24 16:37:59 +0200 | [diff] [blame] | 75 | * ``system_site_packages`` -- a Boolean value indicating that the system Python |
| 76 | site-packages should be available to the environment (defaults to ``False``). |
Vinay Sajip | 7ded1f0 | 2012-05-26 03:45:29 +0100 | [diff] [blame] | 77 | |
Georg Brandl | dbab58f | 2012-06-24 16:37:59 +0200 | [diff] [blame] | 78 | * ``clear`` -- a Boolean value which, if True, will delete any existing target |
| 79 | directory instead of raising an exception (defaults to ``False``). |
Vinay Sajip | 7ded1f0 | 2012-05-26 03:45:29 +0100 | [diff] [blame] | 80 | |
Georg Brandl | dbab58f | 2012-06-24 16:37:59 +0200 | [diff] [blame] | 81 | * ``symlinks`` -- a Boolean value indicating whether to attempt to symlink the |
| 82 | Python binary (and any necessary DLLs or other binaries, |
| 83 | e.g. ``pythonw.exe``), rather than copying. Defaults to ``True`` on Linux and |
Vinay Sajip | 90db661 | 2012-07-17 17:33:46 +0100 | [diff] [blame] | 84 | Unix systems, but ``False`` on Windows. |
Vinay Sajip | 7ded1f0 | 2012-05-26 03:45:29 +0100 | [diff] [blame] | 85 | |
Vinay Sajip | a945ad1 | 2012-07-09 09:24:59 +0100 | [diff] [blame] | 86 | * ``upgrade`` -- a Boolean value which, if True, will upgrade an existing |
| 87 | environment with the running Python - for use when that Python has been |
| 88 | upgraded in-place (defaults to ``False``). |
| 89 | |
Vinay Sajip | 7ded1f0 | 2012-05-26 03:45:29 +0100 | [diff] [blame] | 90 | |
Vinay Sajip | 7ded1f0 | 2012-05-26 03:45:29 +0100 | [diff] [blame] | 91 | |
Georg Brandl | dbab58f | 2012-06-24 16:37:59 +0200 | [diff] [blame] | 92 | Creators of third-party virtual environment tools will be free to use the |
| 93 | provided ``EnvBuilder`` class as a base class. |
Vinay Sajip | 7ded1f0 | 2012-05-26 03:45:29 +0100 | [diff] [blame] | 94 | |
Georg Brandl | dbab58f | 2012-06-24 16:37:59 +0200 | [diff] [blame] | 95 | The returned env-builder is an object which has a method, ``create``: |
Vinay Sajip | 7ded1f0 | 2012-05-26 03:45:29 +0100 | [diff] [blame] | 96 | |
Georg Brandl | dbab58f | 2012-06-24 16:37:59 +0200 | [diff] [blame] | 97 | .. method:: create(env_dir) |
Vinay Sajip | 7ded1f0 | 2012-05-26 03:45:29 +0100 | [diff] [blame] | 98 | |
Georg Brandl | dbab58f | 2012-06-24 16:37:59 +0200 | [diff] [blame] | 99 | This method takes as required argument the path (absolute or relative to |
| 100 | the current directory) of the target directory which is to contain the |
| 101 | virtual environment. The ``create`` method will either create the |
| 102 | environment in the specified directory, or raise an appropriate |
| 103 | exception. |
Vinay Sajip | 7ded1f0 | 2012-05-26 03:45:29 +0100 | [diff] [blame] | 104 | |
Georg Brandl | dbab58f | 2012-06-24 16:37:59 +0200 | [diff] [blame] | 105 | The ``create`` method of the ``EnvBuilder`` class illustrates the hooks |
| 106 | available for subclass customization:: |
Vinay Sajip | 7ded1f0 | 2012-05-26 03:45:29 +0100 | [diff] [blame] | 107 | |
Georg Brandl | dbab58f | 2012-06-24 16:37:59 +0200 | [diff] [blame] | 108 | def create(self, env_dir): |
| 109 | """ |
| 110 | Create a virtualized Python environment in a directory. |
| 111 | env_dir is the target directory to create an environment in. |
| 112 | """ |
| 113 | env_dir = os.path.abspath(env_dir) |
| 114 | context = self.create_directories(env_dir) |
| 115 | self.create_configuration(context) |
| 116 | self.setup_python(context) |
| 117 | self.setup_scripts(context) |
| 118 | self.post_setup(context) |
Vinay Sajip | 7ded1f0 | 2012-05-26 03:45:29 +0100 | [diff] [blame] | 119 | |
Georg Brandl | dbab58f | 2012-06-24 16:37:59 +0200 | [diff] [blame] | 120 | Each of the methods :meth:`create_directories`, |
| 121 | :meth:`create_configuration`, :meth:`setup_python`, |
| 122 | :meth:`setup_scripts` and :meth:`post_setup` can be overridden. |
| 123 | |
| 124 | .. method:: create_directories(env_dir) |
| 125 | |
| 126 | Creates the environment directory and all necessary directories, and |
| 127 | returns a context object. This is just a holder for attributes (such as |
| 128 | paths), for use by the other methods. |
| 129 | |
| 130 | .. method:: create_configuration(context) |
| 131 | |
| 132 | Creates the ``pyvenv.cfg`` configuration file in the environment. |
| 133 | |
| 134 | .. method:: setup_python(context) |
| 135 | |
| 136 | Creates a copy of the Python executable (and, under Windows, DLLs) in |
| 137 | the environment. |
| 138 | |
| 139 | .. method:: setup_scripts(context) |
| 140 | |
| 141 | Installs activation scripts appropriate to the platform into the virtual |
| 142 | environment. |
| 143 | |
| 144 | .. method:: post_setup(context) |
| 145 | |
| 146 | A placeholder method which can be overridden in third party |
| 147 | implementations to pre-install packages in the virtual environment or |
| 148 | perform other post-creation steps. |
| 149 | |
| 150 | In addition, :class:`EnvBuilder` provides this utility method that can be |
| 151 | called from :meth:`setup_scripts` or :meth:`post_setup` in subclasses to |
| 152 | assist in installing custom scripts into the virtual environment. |
| 153 | |
| 154 | .. method:: install_scripts(context, path) |
| 155 | |
| 156 | *path* is the path to a directory that should contain subdirectories |
| 157 | "common", "posix", "nt", each containing scripts destined for the bin |
| 158 | directory in the environment. The contents of "common" and the |
| 159 | directory corresponding to :data:`os.name` are copied after some text |
| 160 | replacement of placeholders: |
| 161 | |
| 162 | * ``__VENV_DIR__`` is replaced with the absolute path of the environment |
| 163 | directory. |
| 164 | |
| 165 | * ``__VENV_NAME__`` is replaced with the environment name (final path |
| 166 | segment of environment directory). |
| 167 | |
| 168 | * ``__VENV_BIN_NAME__`` is replaced with the name of the bin directory |
| 169 | (either ``bin`` or ``Scripts``). |
| 170 | |
| 171 | * ``__VENV_PYTHON__`` is replaced with the absolute path of the |
| 172 | environment's executable. |
| 173 | |
| 174 | |
| 175 | There is also a module-level convenience function: |
| 176 | |
| 177 | .. function:: create(env_dir, system_site_packages=False, clear=False, symlinks=False) |
| 178 | |
| 179 | Create an :class:`EnvBuilder` with the given keyword arguments, and call its |
| 180 | :meth:`~EnvBuilder.create` method with the *env_dir* argument. |