| 1 |
:mod:`!venv` --- Creation of virtual environments |
| 2 |
================================================= |
| 3 |
|
| 4 |
.. module:: venv |
| 5 |
:synopsis: Creation of virtual environments. |
| 6 |
|
| 7 |
.. moduleauthor:: Vinay Sajip <[email protected]> |
| 8 |
.. sectionauthor:: Vinay Sajip <[email protected]> |
| 9 |
|
| 10 |
.. versionadded:: 3.3 |
| 11 |
|
| 12 |
**Source code:** :source:`Lib/venv/` |
| 13 |
|
| 14 |
.. index:: pair: Environments; virtual |
| 15 |
|
| 16 |
-------------- |
| 17 |
|
| 18 |
.. _venv-def: |
| 19 |
.. _venv-intro: |
| 20 |
|
| 21 |
The :mod:`!venv` module supports creating lightweight "virtual environments", |
| 22 |
each with their own independent set of Python packages installed in |
| 23 |
their :mod:`site` directories. |
| 24 |
A virtual environment is created on top of an existing |
| 25 |
Python installation, known as the virtual environment's "base" Python, and by |
| 26 |
default is isolated from the packages in the base environment, |
| 27 |
so that only those explicitly installed in the virtual environment are |
| 28 |
available. See :ref:`sys-path-init-virtual-environments` and :mod:`site`'s |
| 29 |
:ref:`virtual environments documentation <site-virtual-environments-configuration>` |
| 30 |
for more information. |
| 31 |
|
| 32 |
When used from within a virtual environment, common installation tools such as |
| 33 |
:pypi:`pip` will install Python packages into a virtual environment |
| 34 |
without needing to be told to do so explicitly. |
| 35 |
|
| 36 |
A virtual environment is (amongst other things): |
| 37 |
|
| 38 |
* Used to contain a specific Python interpreter and software libraries and |
| 39 |
binaries which are needed to support a project (library or application). These |
| 40 |
are by default isolated from software in other virtual environments and Python |
| 41 |
interpreters and libraries installed in the operating system. |
| 42 |
|
| 43 |
* Contained in a directory, conventionally named ``.venv`` or ``venv`` in |
| 44 |
the project directory, or under a container directory for lots of virtual |
| 45 |
environments, such as ``~/.virtualenvs``. |
| 46 |
|
| 47 |
* Not checked into source control systems such as Git. |
| 48 |
|
| 49 |
* Considered as disposable -- it should be simple to delete and recreate it from |
| 50 |
scratch. You don't place any project code in the environment. |
| 51 |
|
| 52 |
* Not considered as movable or copyable -- you just recreate the same |
| 53 |
environment in the target location. |
| 54 |
|
| 55 |
See :pep:`405` for more background on Python virtual environments. |
| 56 |
|
| 57 |
.. seealso:: |
| 58 |
|
| 59 |
`Python Packaging User Guide: Creating and using virtual environments |
| 60 |
<https://packaging.python.org/guides/installing-using-pip-and-virtual-environments/#create-and-use-virtual-environments>`__ |
| 61 |
|
| 62 |
.. include:: ../includes/wasm-mobile-notavail.rst |
| 63 |
|
| 64 |
Creating virtual environments |
| 65 |
----------------------------- |
| 66 |
|
| 67 |
:ref:`Virtual environments <venv-def>` are created by executing the ``venv`` |
| 68 |
module: |
| 69 |
|
| 70 |
.. code-block:: shell |
| 71 |
|
| 72 |
python -m venv /path/to/new/virtual/environment |
| 73 |
|
| 74 |
This creates the target directory (including parent directories as needed) |
| 75 |
and places a :file:`pyvenv.cfg` file in it with a ``home`` key |
| 76 |
pointing to the Python installation from which the command was run. |
| 77 |
It also creates a :file:`bin` (or :file:`Scripts` on Windows) subdirectory |
| 78 |
containing a copy or symlink of the Python executable |
| 79 |
(as appropriate for the platform or arguments used at environment creation time). |
| 80 |
It also creates a :file:`lib/pythonX.Y/site-packages` subdirectory |
| 81 |
(on Windows, this is :file:`Lib\\site-packages`). |
| 82 |
If an existing directory is specified, it will be re-used. |
| 83 |
|
| 84 |
.. versionchanged:: 3.5 |
| 85 |
The use of ``venv`` is now recommended for creating virtual environments. |
| 86 |
|
| 87 |
.. deprecated-removed:: 3.6 3.8 |
| 88 |
:program:`pyvenv` was the recommended tool for creating virtual environments |
| 89 |
for Python 3.3 and 3.4, and replaced in 3.5 by executing ``venv`` directly. |
| 90 |
|
| 91 |
.. highlight:: none |
| 92 |
|
| 93 |
On Windows, invoke the ``venv`` command as follows: |
| 94 |
|
| 95 |
.. code-block:: ps1con |
| 96 |
|
| 97 |
PS> python -m venv C:\path\to\new\virtual\environment |
| 98 |
|
| 99 |
The command, if run with ``-h``, will show the available options:: |
| 100 |
|
| 101 |
usage: venv [-h] [--system-site-packages] [--symlinks | --copies] [--clear] |
| 102 |
[--upgrade] [--without-pip] [--prompt PROMPT] [--upgrade-deps] |
| 103 |
[--without-scm-ignore-files] |
| 104 |
ENV_DIR [ENV_DIR ...] |
| 105 |
|
| 106 |
Creates virtual Python environments in one or more target directories. |
| 107 |
|
| 108 |
Once an environment has been created, you may wish to activate it, e.g. by |
| 109 |
sourcing an activate script in its bin directory. |
| 110 |
|
| 111 |
.. _venv-cli: |
| 112 |
.. program:: venv |
| 113 |
|
| 114 |
.. option:: ENV_DIR |
| 115 |
|
| 116 |
A required argument specifying the directory to create the environment in. |
| 117 |
|
| 118 |
.. option:: --system-site-packages |
| 119 |
|
| 120 |
Give the virtual environment access to the system site-packages directory. |
| 121 |
|
| 122 |
.. option:: --symlinks |
| 123 |
|
| 124 |
Try to use symlinks rather than copies, when symlinks are not the default for the platform. |
| 125 |
|
| 126 |
.. option:: --copies |
| 127 |
|
| 128 |
Try to use copies rather than symlinks, even when symlinks are the default for the platform. |
| 129 |
|
| 130 |
.. option:: --clear |
| 131 |
|
| 132 |
Delete the contents of the environment directory if it already exists, before environment creation. |
| 133 |
|
| 134 |
.. option:: --upgrade |
| 135 |
|
| 136 |
Upgrade the environment directory to use this version of Python, assuming Python has been upgraded in-place. |
| 137 |
|
| 138 |
.. option:: --without-pip |
| 139 |
|
| 140 |
Skips installing or upgrading pip in the virtual environment (pip is bootstrapped by default). |
| 141 |
|
| 142 |
.. option:: --prompt <PROMPT> |
| 143 |
|
| 144 |
Provides an alternative prompt prefix for this environment. |
| 145 |
|
| 146 |
.. option:: --upgrade-deps |
| 147 |
|
| 148 |
Upgrade core dependencies (pip) to the latest version in PyPI. |
| 149 |
|
| 150 |
.. option:: --without-scm-ignore-files |
| 151 |
|
| 152 |
Skips adding SCM ignore files to the environment directory (Git is supported by default). |
| 153 |
|
| 154 |
|
| 155 |
.. versionchanged:: 3.4 |
| 156 |
Installs pip by default, added the ``--without-pip`` and ``--copies`` |
| 157 |
options. |
| 158 |
|
| 159 |
.. versionchanged:: 3.4 |
| 160 |
In earlier versions, if the target directory already existed, an error was |
| 161 |
raised, unless the ``--clear`` or ``--upgrade`` option was provided. |
| 162 |
|
| 163 |
.. versionchanged:: 3.9 |
| 164 |
Add ``--upgrade-deps`` option to upgrade pip + setuptools to the latest on PyPI. |
| 165 |
|
| 166 |
.. versionchanged:: 3.12 |
| 167 |
|
| 168 |
``setuptools`` is no longer a core venv dependency. |
| 169 |
|
| 170 |
.. versionchanged:: 3.13 |
| 171 |
|
| 172 |
Added the ``--without-scm-ignore-files`` option. |
| 173 |
.. versionchanged:: 3.13 |
| 174 |
``venv`` now creates a :file:`.gitignore` file for Git by default. |
| 175 |
|
| 176 |
.. note:: |
| 177 |
While symlinks are supported on Windows, they are not recommended. Of |
| 178 |
particular note is that double-clicking ``python.exe`` in File Explorer |
| 179 |
will resolve the symlink eagerly and ignore the virtual environment. |
| 180 |
|
| 181 |
.. note:: |
| 182 |
On Microsoft Windows, it may be required to enable the ``Activate.ps1`` |
| 183 |
script by setting the execution policy for the user. You can do this by |
| 184 |
issuing the following PowerShell command: |
| 185 |
|
| 186 |
.. code-block:: powershell |
| 187 |
|
| 188 |
PS C:\> Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser |
| 189 |
|
| 190 |
See `About Execution Policies |
| 191 |
<https://go.microsoft.com/fwlink/?LinkID=135170>`_ |
| 192 |
for more information. |
| 193 |
|
| 194 |
The created :file:`pyvenv.cfg` file also includes the |
| 195 |
``include-system-site-packages`` key, set to ``true`` if ``venv`` is |
| 196 |
run with the ``--system-site-packages`` option, ``false`` otherwise. |
| 197 |
|
| 198 |
Unless the ``--without-pip`` option is given, :mod:`ensurepip` will be |
| 199 |
invoked to bootstrap ``pip`` into the virtual environment. |
| 200 |
|
| 201 |
Multiple paths can be given to ``venv``, in which case an identical virtual |
| 202 |
environment will be created, according to the given options, at each provided |
| 203 |
path. |
| 204 |
|
| 205 |
.. _venv-explanation: |
| 206 |
|
| 207 |
How venvs work |
| 208 |
-------------- |
| 209 |
|
| 210 |
When a Python interpreter is running from a virtual environment, |
| 211 |
:data:`sys.prefix` and :data:`sys.exec_prefix` |
| 212 |
point to the directories of the virtual environment, |
| 213 |
whereas :data:`sys.base_prefix` and :data:`sys.base_exec_prefix` |
| 214 |
point to those of the base Python used to create the environment. |
| 215 |
It is sufficient to check |
| 216 |
``sys.prefix != sys.base_prefix`` to determine if the current interpreter is |
| 217 |
running from a virtual environment. |
| 218 |
|
| 219 |
A virtual environment may be "activated" using a script in its binary directory |
| 220 |
(``bin`` on POSIX; ``Scripts`` on Windows). |
| 221 |
This will prepend that directory to your :envvar:`PATH`, so that running |
| 222 |
:program:`python` will invoke the environment's Python interpreter |
| 223 |
and you can run installed scripts without having to use their full path. |
| 224 |
The invocation of the activation script is platform-specific |
| 225 |
(:samp:`{<venv>}` must be replaced by the path to the directory |
| 226 |
containing the virtual environment): |
| 227 |
|
| 228 |
+-------------+------------+--------------------------------------------------+ |
| 229 |
| Platform | Shell | Command to activate virtual environment | |
| 230 |
+=============+============+==================================================+ |
| 231 |
| POSIX | bash/zsh | :samp:`$ source {<venv>}/bin/activate` | |
| 232 |
| +------------+--------------------------------------------------+ |
| 233 |
| | fish | :samp:`$ source {<venv>}/bin/activate.fish` | |
| 234 |
| +------------+--------------------------------------------------+ |
| 235 |
| | csh/tcsh | :samp:`$ source {<venv>}/bin/activate.csh` | |
| 236 |
| +------------+--------------------------------------------------+ |
| 237 |
| | pwsh | :samp:`$ {<venv>}/bin/Activate.ps1` | |
| 238 |
+-------------+------------+--------------------------------------------------+ |
| 239 |
| Windows | cmd.exe | :samp:`C:\\> {<venv>}\\Scripts\\activate.bat` | |
| 240 |
| +------------+--------------------------------------------------+ |
| 241 |
| | PowerShell | :samp:`PS C:\\> {<venv>}\\Scripts\\Activate.ps1` | |
| 242 |
+-------------+------------+--------------------------------------------------+ |
| 243 |
|
| 244 |
.. versionadded:: 3.4 |
| 245 |
:program:`fish` and :program:`csh` activation scripts. |
| 246 |
|
| 247 |
.. versionadded:: 3.8 |
| 248 |
PowerShell activation scripts installed under POSIX for PowerShell Core |
| 249 |
support. |
| 250 |
|
| 251 |
You don't specifically *need* to activate a virtual environment, |
| 252 |
as you can just specify the full path to that environment's |
| 253 |
Python interpreter when invoking Python. |
| 254 |
Furthermore, all scripts installed in the environment |
| 255 |
should be runnable without activating it. |
| 256 |
|
| 257 |
In order to achieve this, scripts installed into virtual environments have |
| 258 |
a "shebang" line which points to the environment's Python interpreter, |
| 259 |
:samp:`#!/{<path-to-venv>}/bin/python`. |
| 260 |
This means that the script will run with that interpreter regardless of the |
| 261 |
value of :envvar:`PATH`. On Windows, "shebang" line processing is supported if |
| 262 |
you have the :ref:`launcher` installed. Thus, double-clicking an installed |
| 263 |
script in a Windows Explorer window should run it with the correct interpreter |
| 264 |
without the environment needing to be activated or on the :envvar:`PATH`. |
| 265 |
|
| 266 |
When a virtual environment has been activated, the :envvar:`!VIRTUAL_ENV` |
| 267 |
environment variable is set to the path of the environment. |
| 268 |
Since explicitly activating a virtual environment is not required to use it, |
| 269 |
:envvar:`!VIRTUAL_ENV` cannot be relied upon to determine |
| 270 |
whether a virtual environment is being used. |
| 271 |
|
| 272 |
.. warning:: Because scripts installed in environments should not expect the |
| 273 |
environment to be activated, their shebang lines contain the absolute paths |
| 274 |
to their environment's interpreters. Because of this, environments are |
| 275 |
inherently non-portable, in the general case. You should always have a |
| 276 |
simple means of recreating an environment (for example, if you have a |
| 277 |
requirements file ``requirements.txt``, you can invoke ``pip install -r |
| 278 |
requirements.txt`` using the environment's ``pip`` to install all of the |
| 279 |
packages needed by the environment). If for any reason you need to move the |
| 280 |
environment to a new location, you should recreate it at the desired |
| 281 |
location and delete the one at the old location. If you move an environment |
| 282 |
because you moved a parent directory of it, you should recreate the |
| 283 |
environment in its new location. Otherwise, software installed into the |
| 284 |
environment may not work as expected. |
| 285 |
|
| 286 |
You can deactivate a virtual environment by typing ``deactivate`` in your shell. |
| 287 |
The exact mechanism is platform-specific and is an internal implementation |
| 288 |
detail (typically, a script or shell function will be used). |
| 289 |
|
| 290 |
|
| 291 |
.. _venv-api: |
| 292 |
|
| 293 |
API |
| 294 |
--- |
| 295 |
|
| 296 |
.. highlight:: python |
| 297 |
|
| 298 |
The high-level method described above makes use of a simple API which provides |
| 299 |
mechanisms for third-party virtual environment creators to customize environment |
| 300 |
creation according to their needs, the :class:`EnvBuilder` class. |
| 301 |
|
| 302 |
.. class:: EnvBuilder(system_site_packages=False, clear=False, \ |
| 303 |
symlinks=False, upgrade=False, with_pip=False, \ |
| 304 |
prompt=None, upgrade_deps=False, \ |
| 305 |
*, scm_ignore_files=frozenset()) |
| 306 |
|
| 307 |
The :class:`EnvBuilder` class accepts the following keyword arguments on |
| 308 |
instantiation: |
| 309 |
|
| 310 |
* *system_site_packages* -- a boolean value indicating that the system Python |
| 311 |
site-packages should be available to the environment (defaults to ``False``). |
| 312 |
|
| 313 |
* *clear* -- a boolean value which, if true, will delete the contents of |
| 314 |
any existing target directory, before creating the environment. |
| 315 |
|
| 316 |
* *symlinks* -- a boolean value indicating whether to attempt to symlink the |
| 317 |
Python binary rather than copying. |
| 318 |
|
| 319 |
* *upgrade* -- a boolean value which, if true, will upgrade an existing |
| 320 |
environment with the running Python - for use when that Python has been |
| 321 |
upgraded in-place (defaults to ``False``). |
| 322 |
|
| 323 |
* *with_pip* -- a boolean value which, if true, ensures pip is |
| 324 |
installed in the virtual environment. This uses :mod:`ensurepip` with |
| 325 |
the ``--default-pip`` option. |
| 326 |
|
| 327 |
* *prompt* -- a string to be used after virtual environment is activated |
| 328 |
(defaults to ``None`` which means directory name of the environment would |
| 329 |
be used). If the special string ``"."`` is provided, the basename of the |
| 330 |
current directory is used as the prompt. |
| 331 |
|
| 332 |
* *upgrade_deps* -- Update the base venv modules to the latest on PyPI |
| 333 |
|
| 334 |
* *scm_ignore_files* -- Create ignore files based for the specified source |
| 335 |
control managers (SCM) in the iterable. Support is defined by having a |
| 336 |
method named ``create_{scm}_ignore_file``. The only value supported by |
| 337 |
default is ``"git"`` via :meth:`create_git_ignore_file`. |
| 338 |
|
| 339 |
|
| 340 |
.. versionchanged:: 3.4 |
| 341 |
Added the ``with_pip`` parameter |
| 342 |
|
| 343 |
.. versionchanged:: 3.6 |
| 344 |
Added the ``prompt`` parameter |
| 345 |
|
| 346 |
.. versionchanged:: 3.9 |
| 347 |
Added the ``upgrade_deps`` parameter |
| 348 |
|
| 349 |
.. versionchanged:: 3.13 |
| 350 |
Added the ``scm_ignore_files`` parameter |
| 351 |
|
| 352 |
:class:`EnvBuilder` may be used as a base class. |
| 353 |
|
| 354 |
.. method:: create(env_dir) |
| 355 |
|
| 356 |
Create a virtual environment by specifying the target directory |
| 357 |
(absolute or relative to the current directory) which is to contain the |
| 358 |
virtual environment. The ``create`` method will either create the |
| 359 |
environment in the specified directory, or raise an appropriate |
| 360 |
exception. |
| 361 |
|
| 362 |
The ``create`` method of the :class:`EnvBuilder` class illustrates the |
| 363 |
hooks available for subclass customization:: |
| 364 |
|
| 365 |
def create(self, env_dir): |
| 366 |
""" |
| 367 |
Create a virtualized Python environment in a directory. |
| 368 |
env_dir is the target directory to create an environment in. |
| 369 |
""" |
| 370 |
env_dir = os.path.abspath(env_dir) |
| 371 |
context = self.ensure_directories(env_dir) |
| 372 |
self.create_configuration(context) |
| 373 |
self.setup_python(context) |
| 374 |
self.setup_scripts(context) |
| 375 |
self.post_setup(context) |
| 376 |
|
| 377 |
Each of the methods :meth:`ensure_directories`, |
| 378 |
:meth:`create_configuration`, :meth:`setup_python`, |
| 379 |
:meth:`setup_scripts` and :meth:`post_setup` can be overridden. |
| 380 |
|
| 381 |
.. method:: ensure_directories(env_dir) |
| 382 |
|
| 383 |
Creates the environment directory and all necessary subdirectories that |
| 384 |
don't already exist, and returns a context object. This context object |
| 385 |
is just a holder for attributes (such as paths) for use by the other |
| 386 |
methods. If the :class:`EnvBuilder` is created with the arg |
| 387 |
``clear=True``, contents of the environment directory will be cleared |
| 388 |
and then all necessary subdirectories will be recreated. |
| 389 |
|
| 390 |
The returned context object is a :class:`types.SimpleNamespace` with the |
| 391 |
following attributes: |
| 392 |
|
| 393 |
* ``env_dir`` - The location of the virtual environment. Used for |
| 394 |
``__VENV_DIR__`` in activation scripts (see :meth:`install_scripts`). |
| 395 |
|
| 396 |
* ``env_name`` - The name of the virtual environment. Used for |
| 397 |
``__VENV_NAME__`` in activation scripts (see :meth:`install_scripts`). |
| 398 |
|
| 399 |
* ``prompt`` - The prompt to be used by the activation scripts. Used for |
| 400 |
``__VENV_PROMPT__`` in activation scripts (see :meth:`install_scripts`). |
| 401 |
|
| 402 |
* ``executable`` - The underlying Python executable used by the virtual |
| 403 |
environment. This takes into account the case where a virtual environment |
| 404 |
is created from another virtual environment. |
| 405 |
|
| 406 |
* ``inc_path`` - The include path for the virtual environment. |
| 407 |
|
| 408 |
* ``lib_path`` - The purelib path for the virtual environment. |
| 409 |
|
| 410 |
* ``bin_path`` - The script path for the virtual environment. |
| 411 |
|
| 412 |
* ``bin_name`` - The name of the script path relative to the virtual |
| 413 |
environment location. Used for ``__VENV_BIN_NAME__`` in activation |
| 414 |
scripts (see :meth:`install_scripts`). |
| 415 |
|
| 416 |
* ``env_exe`` - The name of the Python interpreter in the virtual |
| 417 |
environment. Used for ``__VENV_PYTHON__`` in activation scripts |
| 418 |
(see :meth:`install_scripts`). |
| 419 |
|
| 420 |
* ``env_exec_cmd`` - The name of the Python interpreter, taking into |
| 421 |
account filesystem redirections. This can be used to run Python in |
| 422 |
the virtual environment. |
| 423 |
|
| 424 |
|
| 425 |
.. versionchanged:: 3.11 |
| 426 |
The *venv* |
| 427 |
:ref:`sysconfig installation scheme <installation_paths>` |
| 428 |
is used to construct the paths of the created directories. |
| 429 |
|
| 430 |
.. versionchanged:: 3.12 |
| 431 |
The attribute ``lib_path`` was added to the context, and the context |
| 432 |
object was documented. |
| 433 |
|
| 434 |
.. method:: create_configuration(context) |
| 435 |
|
| 436 |
Creates the ``pyvenv.cfg`` configuration file in the environment. |
| 437 |
|
| 438 |
.. method:: setup_python(context) |
| 439 |
|
| 440 |
Creates a copy or symlink to the Python executable in the environment. |
| 441 |
On POSIX systems, if a specific executable ``python3.x`` was used, |
| 442 |
symlinks to ``python`` and ``python3`` will be created pointing to that |
| 443 |
executable, unless files with those names already exist. |
| 444 |
|
| 445 |
.. method:: setup_scripts(context) |
| 446 |
|
| 447 |
Installs activation scripts appropriate to the platform into the virtual |
| 448 |
environment. |
| 449 |
|
| 450 |
.. method:: upgrade_dependencies(context) |
| 451 |
|
| 452 |
Upgrades the core venv dependency packages (currently :pypi:`pip`) |
| 453 |
in the environment. This is done by shelling out to the |
| 454 |
``pip`` executable in the environment. |
| 455 |
|
| 456 |
.. versionadded:: 3.9 |
| 457 |
.. versionchanged:: 3.12 |
| 458 |
|
| 459 |
:pypi:`setuptools` is no longer a core venv dependency. |
| 460 |
|
| 461 |
.. method:: post_setup(context) |
| 462 |
|
| 463 |
A placeholder method which can be overridden in third party |
| 464 |
implementations to pre-install packages in the virtual environment or |
| 465 |
perform other post-creation steps. |
| 466 |
|
| 467 |
.. method:: install_scripts(context, path) |
| 468 |
|
| 469 |
This method can be |
| 470 |
called from :meth:`setup_scripts` or :meth:`post_setup` in subclasses to |
| 471 |
assist in installing custom scripts into the virtual environment. |
| 472 |
|
| 473 |
*path* is the path to a directory that should contain subdirectories |
| 474 |
``common``, ``posix``, ``nt``; each containing scripts destined for the |
| 475 |
``bin`` directory in the environment. The contents of ``common`` and the |
| 476 |
directory corresponding to :data:`os.name` are copied after some text |
| 477 |
replacement of placeholders: |
| 478 |
|
| 479 |
* ``__VENV_DIR__`` is replaced with the absolute path of the environment |
| 480 |
directory. |
| 481 |
|
| 482 |
* ``__VENV_NAME__`` is replaced with the environment name (final path |
| 483 |
segment of environment directory). |
| 484 |
|
| 485 |
* ``__VENV_PROMPT__`` is replaced with the prompt (the environment |
| 486 |
name surrounded by parentheses and with a following space) |
| 487 |
|
| 488 |
* ``__VENV_BIN_NAME__`` is replaced with the name of the bin directory |
| 489 |
(either ``bin`` or ``Scripts``). |
| 490 |
|
| 491 |
* ``__VENV_PYTHON__`` is replaced with the absolute path of the |
| 492 |
environment's executable. |
| 493 |
|
| 494 |
The directories are allowed to exist (for when an existing environment |
| 495 |
is being upgraded). |
| 496 |
|
| 497 |
.. method:: create_git_ignore_file(context) |
| 498 |
|
| 499 |
Creates a ``.gitignore`` file within the virtual environment that causes |
| 500 |
the entire directory to be ignored by the Git source control manager. |
| 501 |
|
| 502 |
.. versionadded:: 3.13 |
| 503 |
|
| 504 |
.. versionchanged:: 3.7.2 |
| 505 |
Windows now uses redirector scripts for ``python[w].exe`` instead of |
| 506 |
copying the actual binaries. In 3.7.2 only :meth:`setup_python` does |
| 507 |
nothing unless running from a build in the source tree. |
| 508 |
|
| 509 |
.. versionchanged:: 3.7.3 |
| 510 |
Windows copies the redirector scripts as part of :meth:`setup_python` |
| 511 |
instead of :meth:`setup_scripts`. This was not the case in 3.7.2. |
| 512 |
When using symlinks, the original executables will be linked. |
| 513 |
|
| 514 |
There is also a module-level convenience function: |
| 515 |
|
| 516 |
.. function:: create(env_dir, system_site_packages=False, clear=False, \ |
| 517 |
symlinks=False, with_pip=False, prompt=None, \ |
| 518 |
upgrade_deps=False, *, scm_ignore_files=frozenset()) |
| 519 |
|
| 520 |
Create an :class:`EnvBuilder` with the given keyword arguments, and call its |
| 521 |
:meth:`~EnvBuilder.create` method with the *env_dir* argument. |
| 522 |
|
| 523 |
.. versionadded:: 3.3 |
| 524 |
|
| 525 |
.. versionchanged:: 3.4 |
| 526 |
Added the *with_pip* parameter |
| 527 |
|
| 528 |
.. versionchanged:: 3.6 |
| 529 |
Added the *prompt* parameter |
| 530 |
|
| 531 |
.. versionchanged:: 3.9 |
| 532 |
Added the *upgrade_deps* parameter |
| 533 |
|
| 534 |
.. versionchanged:: 3.13 |
| 535 |
Added the *scm_ignore_files* parameter |
| 536 |
|
| 537 |
An example of extending ``EnvBuilder`` |
| 538 |
-------------------------------------- |
| 539 |
|
| 540 |
The following script shows how to extend :class:`EnvBuilder` by implementing a |
| 541 |
subclass which installs setuptools and pip into a created virtual environment:: |
| 542 |
|
| 543 |
import os |
| 544 |
import os.path |
| 545 |
from subprocess import Popen, PIPE |
| 546 |
import sys |
| 547 |
from threading import Thread |
| 548 |
from urllib.parse import urlsplit |
| 549 |
from urllib.request import urlretrieve |
| 550 |
import venv |
| 551 |
|
| 552 |
class ExtendedEnvBuilder(venv.EnvBuilder): |
| 553 |
""" |
| 554 |
This builder installs setuptools and pip so that you can pip or |
| 555 |
easy_install other packages into the created virtual environment. |
| 556 |
|
| 557 |
:param nodist: If true, setuptools and pip are not installed into the |
| 558 |
created virtual environment. |
| 559 |
:param nopip: If true, pip is not installed into the created |
| 560 |
virtual environment. |
| 561 |
:param progress: If setuptools or pip are installed, the progress of the |
| 562 |
installation can be monitored by passing a progress |
| 563 |
callable. If specified, it is called with two |
| 564 |
arguments: a string indicating some progress, and a |
| 565 |
context indicating where the string is coming from. |
| 566 |
The context argument can have one of three values: |
| 567 |
'main', indicating that it is called from virtualize() |
| 568 |
itself, and 'stdout' and 'stderr', which are obtained |
| 569 |
by reading lines from the output streams of a subprocess |
| 570 |
which is used to install the app. |
| 571 |
|
| 572 |
If a callable is not specified, default progress |
| 573 |
information is output to sys.stderr. |
| 574 |
""" |
| 575 |
|
| 576 |
def __init__(self, *args, **kwargs): |
| 577 |
self.nodist = kwargs.pop('nodist', False) |
| 578 |
self.nopip = kwargs.pop('nopip', False) |
| 579 |
self.progress = kwargs.pop('progress', None) |
| 580 |
self.verbose = kwargs.pop('verbose', False) |
| 581 |
super().__init__(*args, **kwargs) |
| 582 |
|
| 583 |
def post_setup(self, context): |
| 584 |
""" |
| 585 |
Set up any packages which need to be pre-installed into the |
| 586 |
virtual environment being created. |
| 587 |
|
| 588 |
:param context: The information for the virtual environment |
| 589 |
creation request being processed. |
| 590 |
""" |
| 591 |
os.environ['VIRTUAL_ENV'] = context.env_dir |
| 592 |
if not self.nodist: |
| 593 |
self.install_setuptools(context) |
| 594 |
# Can't install pip without setuptools |
| 595 |
if not self.nopip and not self.nodist: |
| 596 |
self.install_pip(context) |
| 597 |
|
| 598 |
def reader(self, stream, context): |
| 599 |
""" |
| 600 |
Read lines from a subprocess' output stream and either pass to a progress |
| 601 |
callable (if specified) or write progress information to sys.stderr. |
| 602 |
""" |
| 603 |
progress = self.progress |
| 604 |
while True: |
| 605 |
s = stream.readline() |
| 606 |
if not s: |
| 607 |
break |
| 608 |
if progress is not None: |
| 609 |
progress(s, context) |
| 610 |
else: |
| 611 |
if not self.verbose: |
| 612 |
sys.stderr.write('.') |
| 613 |
else: |
| 614 |
sys.stderr.write(s.decode('utf-8')) |
| 615 |
sys.stderr.flush() |
| 616 |
stream.close() |
| 617 |
|
| 618 |
def install_script(self, context, name, url): |
| 619 |
_, _, path, _, _ = urlsplit(url) |
| 620 |
fn = os.path.split(path)[-1] |
| 621 |
binpath = context.bin_path |
| 622 |
distpath = os.path.join(binpath, fn) |
| 623 |
# Download script into the virtual environment's binaries folder |
| 624 |
urlretrieve(url, distpath) |
| 625 |
progress = self.progress |
| 626 |
if self.verbose: |
| 627 |
term = '\n' |
| 628 |
else: |
| 629 |
term = '' |
| 630 |
if progress is not None: |
| 631 |
progress('Installing %s ...%s' % (name, term), 'main') |
| 632 |
else: |
| 633 |
sys.stderr.write('Installing %s ...%s' % (name, term)) |
| 634 |
sys.stderr.flush() |
| 635 |
# Install in the virtual environment |
| 636 |
args = [context.env_exe, fn] |
| 637 |
p = Popen(args, stdout=PIPE, stderr=PIPE, cwd=binpath) |
| 638 |
t1 = Thread(target=self.reader, args=(p.stdout, 'stdout')) |
| 639 |
t1.start() |
| 640 |
t2 = Thread(target=self.reader, args=(p.stderr, 'stderr')) |
| 641 |
t2.start() |
| 642 |
p.wait() |
| 643 |
t1.join() |
| 644 |
t2.join() |
| 645 |
if progress is not None: |
| 646 |
progress('done.', 'main') |
| 647 |
else: |
| 648 |
sys.stderr.write('done.\n') |
| 649 |
# Clean up - no longer needed |
| 650 |
os.unlink(distpath) |
| 651 |
|
| 652 |
def install_setuptools(self, context): |
| 653 |
""" |
| 654 |
Install setuptools in the virtual environment. |
| 655 |
|
| 656 |
:param context: The information for the virtual environment |
| 657 |
creation request being processed. |
| 658 |
""" |
| 659 |
url = "https://bootstrap.pypa.io/ez_setup.py" |
| 660 |
self.install_script(context, 'setuptools', url) |
| 661 |
# clear up the setuptools archive which gets downloaded |
| 662 |
pred = lambda o: o.startswith('setuptools-') and o.endswith('.tar.gz') |
| 663 |
files = filter(pred, os.listdir(context.bin_path)) |
| 664 |
for f in files: |
| 665 |
f = os.path.join(context.bin_path, f) |
| 666 |
os.unlink(f) |
| 667 |
|
| 668 |
def install_pip(self, context): |
| 669 |
""" |
| 670 |
Install pip in the virtual environment. |
| 671 |
|
| 672 |
:param context: The information for the virtual environment |
| 673 |
creation request being processed. |
| 674 |
""" |
| 675 |
url = 'https://bootstrap.pypa.io/get-pip.py' |
| 676 |
self.install_script(context, 'pip', url) |
| 677 |
|
| 678 |
|
| 679 |
def main(args=None): |
| 680 |
import argparse |
| 681 |
|
| 682 |
parser = argparse.ArgumentParser(prog=__name__, |
| 683 |
description='Creates virtual Python ' |
| 684 |
'environments in one or ' |
| 685 |
'more target ' |
| 686 |
'directories.') |
| 687 |
parser.add_argument('dirs', metavar='ENV_DIR', nargs='+', |
| 688 |
help='A directory in which to create the ' |
| 689 |
'virtual environment.') |
| 690 |
parser.add_argument('--no-setuptools', default=False, |
| 691 |
action='store_true', dest='nodist', |
| 692 |
help="Don't install setuptools or pip in the " |
| 693 |
"virtual environment.") |
| 694 |
parser.add_argument('--no-pip', default=False, |
| 695 |
action='store_true', dest='nopip', |
| 696 |
help="Don't install pip in the virtual " |
| 697 |
"environment.") |
| 698 |
parser.add_argument('--system-site-packages', default=False, |
| 699 |
action='store_true', dest='system_site', |
| 700 |
help='Give the virtual environment access to the ' |
| 701 |
'system site-packages dir.') |
| 702 |
if os.name == 'nt': |
| 703 |
use_symlinks = False |
| 704 |
else: |
| 705 |
use_symlinks = True |
| 706 |
parser.add_argument('--symlinks', default=use_symlinks, |
| 707 |
action='store_true', dest='symlinks', |
| 708 |
help='Try to use symlinks rather than copies, ' |
| 709 |
'when symlinks are not the default for ' |
| 710 |
'the platform.') |
| 711 |
parser.add_argument('--clear', default=False, action='store_true', |
| 712 |
dest='clear', help='Delete the contents of the ' |
| 713 |
'virtual environment ' |
| 714 |
'directory if it already ' |
| 715 |
'exists, before virtual ' |
| 716 |
'environment creation.') |
| 717 |
parser.add_argument('--upgrade', default=False, action='store_true', |
| 718 |
dest='upgrade', help='Upgrade the virtual ' |
| 719 |
'environment directory to ' |
| 720 |
'use this version of ' |
| 721 |
'Python, assuming Python ' |
| 722 |
'has been upgraded ' |
| 723 |
'in-place.') |
| 724 |
parser.add_argument('--verbose', default=False, action='store_true', |
| 725 |
dest='verbose', help='Display the output ' |
| 726 |
'from the scripts which ' |
| 727 |
'install setuptools and pip.') |
| 728 |
options = parser.parse_args(args) |
| 729 |
if options.upgrade and options.clear: |
| 730 |
raise ValueError('you cannot supply --upgrade and --clear together.') |
| 731 |
builder = ExtendedEnvBuilder(system_site_packages=options.system_site, |
| 732 |
clear=options.clear, |
| 733 |
symlinks=options.symlinks, |
| 734 |
upgrade=options.upgrade, |
| 735 |
nodist=options.nodist, |
| 736 |
nopip=options.nopip, |
| 737 |
verbose=options.verbose) |
| 738 |
for d in options.dirs: |
| 739 |
builder.create(d) |
| 740 |
|
| 741 |
if __name__ == '__main__': |
| 742 |
rc = 1 |
| 743 |
try: |
| 744 |
main() |
| 745 |
rc = 0 |
| 746 |
except Exception as e: |
| 747 |
print('Error: %s' % e, file=sys.stderr) |
| 748 |
sys.exit(rc) |
| 749 |
|
| 750 |
|
| 751 |
This script is also available for download `online |
| 752 |
<https://gist.github.com/vsajip/4673395>`_. |