Vinay Sajip | c4618e3 | 2012-07-10 08:21:07 +0100 | [diff] [blame] | 1 | Creation of :ref:`virtual environments <venv-def>` is done by executing the |
| 2 | ``pyvenv`` script:: |
| 3 | |
| 4 | pyvenv /path/to/new/virtual/environment |
| 5 | |
| 6 | Running this command creates the target directory (creating any parent |
| 7 | directories that don't exist already) and places a ``pyvenv.cfg`` file in it |
| 8 | with a ``home`` key pointing to the Python installation the command was run |
| 9 | from. It also creates a ``bin`` (or ``Scripts`` on Windows) subdirectory |
| 10 | containing a copy of the ``python`` binary (or binaries, in the case of |
| 11 | Windows). It also creates an (initially empty) ``lib/pythonX.Y/site-packages`` |
| 12 | subdirectory (on Windows, this is ``Lib\site-packages``). |
| 13 | |
Larry Hastings | 3732ed2 | 2014-03-15 21:13:56 -0700 | [diff] [blame] | 14 | .. seealso:: |
| 15 | |
| 16 | `Python Packaging User Guide: Creating and using virtual environments |
| 17 | <http://packaging.python.org/en/latest/tutorial.html#creating-and-using-virtual-environments>`__ |
| 18 | |
Vinay Sajip | c4618e3 | 2012-07-10 08:21:07 +0100 | [diff] [blame] | 19 | .. highlight:: none |
| 20 | |
| 21 | On Windows, you may have to invoke the ``pyvenv`` script as follows, if you |
| 22 | don't have the relevant PATH and PATHEXT settings:: |
| 23 | |
| 24 | c:\Temp>c:\Python33\python c:\Python33\Tools\Scripts\pyvenv.py myenv |
| 25 | |
| 26 | or equivalently:: |
| 27 | |
| 28 | c:\Temp>c:\Python33\python -m venv myenv |
| 29 | |
| 30 | The command, if run with ``-h``, will show the available options:: |
| 31 | |
| 32 | usage: pyvenv [-h] [--system-site-packages] [--symlinks] [--clear] |
Nick Coghlan | 8fbdb09 | 2013-11-23 00:30:34 +1000 | [diff] [blame] | 33 | [--upgrade] [--without-pip] ENV_DIR [ENV_DIR ...] |
Vinay Sajip | c4618e3 | 2012-07-10 08:21:07 +0100 | [diff] [blame] | 34 | |
| 35 | Creates virtual Python environments in one or more target directories. |
| 36 | |
| 37 | positional arguments: |
| 38 | ENV_DIR A directory to create the environment in. |
| 39 | |
| 40 | optional arguments: |
| 41 | -h, --help show this help message and exit |
| 42 | --system-site-packages Give access to the global site-packages dir to the |
| 43 | virtual environment. |
| 44 | --symlinks Try to use symlinks rather than copies, when symlinks |
| 45 | are not the default for the platform. |
Larry Hastings | 3732ed2 | 2014-03-15 21:13:56 -0700 | [diff] [blame] | 46 | --copies Try to use copies rather than symlinks, even when |
| 47 | symlinks are the default for the platform. |
Vinay Sajip | c4618e3 | 2012-07-10 08:21:07 +0100 | [diff] [blame] | 48 | --clear Delete the environment directory if it already exists. |
| 49 | If not specified and the directory exists, an error is |
| 50 | raised. |
| 51 | --upgrade Upgrade the environment directory to use this version |
| 52 | of Python, assuming Python has been upgraded in-place. |
Nick Coghlan | 8fbdb09 | 2013-11-23 00:30:34 +1000 | [diff] [blame] | 53 | --without-pip Skips installing or upgrading pip in the virtual |
| 54 | environment (pip is bootstrapped by default) |
| 55 | |
| 56 | .. versionchanged:: 3.4 |
Larry Hastings | 3732ed2 | 2014-03-15 21:13:56 -0700 | [diff] [blame] | 57 | Installs pip by default, added the ``--without-pip`` and ``--copies`` |
| 58 | options |
Vinay Sajip | c4618e3 | 2012-07-10 08:21:07 +0100 | [diff] [blame] | 59 | |
| 60 | If the target directory already exists an error will be raised, unless |
| 61 | the ``--clear`` or ``--upgrade`` option was provided. |
| 62 | |
| 63 | The created ``pyvenv.cfg`` file also includes the |
| 64 | ``include-system-site-packages`` key, set to ``true`` if ``venv`` is |
| 65 | run with the ``--system-site-packages`` option, ``false`` otherwise. |
| 66 | |
Nick Coghlan | 8fbdb09 | 2013-11-23 00:30:34 +1000 | [diff] [blame] | 67 | Unless the ``--without-pip`` option is given, :mod:`ensurepip` will be |
| 68 | invoked to bootstrap ``pip`` into the virtual environment. |
| 69 | |
Vinay Sajip | c4618e3 | 2012-07-10 08:21:07 +0100 | [diff] [blame] | 70 | Multiple paths can be given to ``pyvenv``, in which case an identical |
| 71 | virtualenv will be created, according to the given options, at each |
| 72 | provided path. |
| 73 | |
| 74 | Once a venv has been created, it can be "activated" using a script in the |
Andrew Svetlov | 65e9c57 | 2012-10-04 21:48:58 +0300 | [diff] [blame] | 75 | venv's binary directory. The invocation of the script is platform-specific: |
Vinay Sajip | c4618e3 | 2012-07-10 08:21:07 +0100 | [diff] [blame] | 76 | |
Andrew Svetlov | 65e9c57 | 2012-10-04 21:48:58 +0300 | [diff] [blame] | 77 | +-------------+-----------------+-----------------------------------------+ |
| 78 | | Platform | Shell | Command to activate virtual environment | |
| 79 | +=============+=================+=========================================+ |
| 80 | | Posix | bash/zsh | $ source <venv>/bin/activate | |
| 81 | +-------------+-----------------+-----------------------------------------+ |
| 82 | | | fish | $ . <venv>/bin/activate.fish | |
| 83 | +-------------+-----------------+-----------------------------------------+ |
| 84 | | | csh/tcsh | $ source <venv>/bin/activate.csh | |
| 85 | +-------------+-----------------+-----------------------------------------+ |
| 86 | | Windows | cmd.exe | C:\> <venv>/Scripts/activate.bat | |
| 87 | +-------------+-----------------+-----------------------------------------+ |
| 88 | | | PowerShell | PS C:\> <venv>/Scripts/Activate.ps1 | |
| 89 | +-------------+-----------------+-----------------------------------------+ |
Vinay Sajip | c4618e3 | 2012-07-10 08:21:07 +0100 | [diff] [blame] | 90 | |
| 91 | You don't specifically *need* to activate an environment; activation just |
| 92 | prepends the venv's binary directory to your path, so that "python" invokes the |
| 93 | venv's Python interpreter and you can run installed scripts without having to |
| 94 | use their full path. However, all scripts installed in a venv should be |
| 95 | runnable without activating it, and run with the venv's Python automatically. |
| 96 | |
| 97 | You can deactivate a venv by typing "deactivate" in your shell. The exact |
| 98 | mechanism is platform-specific: for example, the Bash activation script defines |
| 99 | a "deactivate" function, whereas on Windows there are separate scripts called |
| 100 | ``deactivate.bat`` and ``Deactivate.ps1`` which are installed when the venv is |
| 101 | created. |
| 102 | |
R David Murray | 575fb31 | 2013-12-25 23:21:03 -0500 | [diff] [blame] | 103 | .. versionadded:: 3.4 |
| 104 | ``fish`` and ``csh`` activation scripts. |