|
| 1 | +.. _tools-and-scripts: |
| 2 | + |
| 3 | +Additional Tools and Scripts |
| 4 | +============================ |
| 5 | + |
| 6 | +pyvenv - Creating virtual environments |
| 7 | +-------------------------------------- |
| 8 | + |
| 9 | +Creation of virtual environments is done by executing the ``pyvenv`` |
| 10 | +script:: |
| 11 | + |
| 12 | + pyvenv /path/to/new/virtual/environment |
| 13 | + |
| 14 | +Running this command creates the target directory (creating any parent |
| 15 | +directories that don't exist already) and places a ``pyvenv.cfg`` file |
| 16 | +in it with a ``home`` key pointing to the Python installation the |
| 17 | +command was run from. It also creates a ``bin`` (or ``Scripts`` on |
| 18 | +Windows) subdirectory containing a copy of the ``python`` binary (or |
| 19 | +binaries, in the case of Windows) and the ``pysetup3`` script (to |
| 20 | +facilitate easy installation of packages from PyPI into the new virtualenv). |
| 21 | +It also creates an (initially empty) ``lib/pythonX.Y/site-packages`` |
| 22 | +subdirectory (on Windows, this is ``Lib\site-packages``). |
| 23 | + |
| 24 | +.. highlight:: none |
| 25 | + |
| 26 | +On Windows, you may have to invoke the ``pyvenv`` script as follows, if you |
| 27 | +don't have the relevant PATH and PATHEXT settings:: |
| 28 | + |
| 29 | + c:\Temp>c:\Python33\python c:\Python33\Tools\Scripts\pyvenv.py myenv |
| 30 | + |
| 31 | +or equivalently:: |
| 32 | + |
| 33 | + c:\Temp>c:\Python33\python -m venv myenv |
| 34 | + |
| 35 | +The command, if run with ``-h``, will show the available options:: |
| 36 | + |
| 37 | + usage: pyvenv [-h] [--system-site-packages] [--symlink] [--clear] |
| 38 | + [--upgrade] ENV_DIR [ENV_DIR ...] |
| 39 | + |
| 40 | + Creates virtual Python environments in one or more target directories. |
| 41 | + |
| 42 | + positional arguments: |
| 43 | + ENV_DIR A directory to create the environment in. |
| 44 | + |
| 45 | + optional arguments: |
| 46 | + -h, --help show this help message and exit |
| 47 | + --system-site-packages Give access to the global site-packages dir to the |
| 48 | + virtual environment. |
| 49 | + --symlink Attempt to symlink rather than copy. |
| 50 | + --clear Delete the environment directory if it already exists. |
| 51 | + If not specified and the directory exists, an error is |
| 52 | + raised. |
| 53 | + --upgrade Upgrade the environment directory to use this version |
| 54 | + of Python, assuming Python has been upgraded in-place. |
| 55 | + |
| 56 | +If the target directory already exists an error will be raised, unless |
| 57 | +the ``--clear`` or ``--upgrade`` option was provided. |
| 58 | + |
| 59 | +The created ``pyvenv.cfg`` file also includes the |
| 60 | +``include-system-site-packages`` key, set to ``true`` if ``venv`` is |
| 61 | +run with the ``--system-site-packages`` option, ``false`` otherwise. |
| 62 | + |
| 63 | +Multiple paths can be given to ``pyvenv``, in which case an identical |
| 64 | +virtualenv will be created, according to the given options, at each |
| 65 | +provided path. |
| 66 | + |
0 commit comments