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 |
Brett Cannon | 15552c3 | 2016-07-08 10:46:21 -0700 | [diff] [blame] | 2 | command ``venv``:: |
Vinay Sajip | c4618e3 | 2012-07-10 08:21:07 +0100 | [diff] [blame] | 3 | |
Brett Cannon | 15552c3 | 2016-07-08 10:46:21 -0700 | [diff] [blame] | 4 | python3 -m venv /path/to/new/virtual/environment |
Vinay Sajip | c4618e3 | 2012-07-10 08:21:07 +0100 | [diff] [blame] | 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 |
Brett Cannon | 15552c3 | 2016-07-08 10:46:21 -0700 | [diff] [blame] | 8 | with a ``home`` key pointing to the Python installation from which the command |
| 9 | was run. It also creates a ``bin`` (or ``Scripts`` on Windows) subdirectory |
Vinay Sajip | c4618e3 | 2012-07-10 08:21:07 +0100 | [diff] [blame] | 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`` |
TROUVERIE Joachim | e8eb972 | 2018-02-18 17:52:36 +0100 | [diff] [blame] | 12 | subdirectory (on Windows, this is ``Lib\site-packages``). If an existing |
| 13 | directory is specified, it will be re-used. |
Vinay Sajip | c4618e3 | 2012-07-10 08:21:07 +0100 | [diff] [blame] | 14 | |
Brett Cannon | 15552c3 | 2016-07-08 10:46:21 -0700 | [diff] [blame] | 15 | .. deprecated:: 3.6 |
| 16 | ``pyvenv`` was the recommended tool for creating virtual environments for |
| 17 | Python 3.3 and 3.4, and is `deprecated in Python 3.6 |
| 18 | <https://docs.python.org/dev/whatsnew/3.6.html#deprecated-features>`_. |
| 19 | |
| 20 | .. versionchanged:: 3.5 |
| 21 | The use of ``venv`` is now recommended for creating virtual environments. |
| 22 | |
Larry Hastings | 3732ed2 | 2014-03-15 21:13:56 -0700 | [diff] [blame] | 23 | .. seealso:: |
| 24 | |
| 25 | `Python Packaging User Guide: Creating and using virtual environments |
Brett Cannon | 15552c3 | 2016-07-08 10:46:21 -0700 | [diff] [blame] | 26 | <https://packaging.python.org/installing/#creating-virtual-environments>`__ |
Larry Hastings | 3732ed2 | 2014-03-15 21:13:56 -0700 | [diff] [blame] | 27 | |
Vinay Sajip | c4618e3 | 2012-07-10 08:21:07 +0100 | [diff] [blame] | 28 | .. highlight:: none |
| 29 | |
Brett Cannon | 15552c3 | 2016-07-08 10:46:21 -0700 | [diff] [blame] | 30 | On Windows, invoke the ``venv`` command as follows:: |
Vinay Sajip | c4618e3 | 2012-07-10 08:21:07 +0100 | [diff] [blame] | 31 | |
Brett Cannon | 15552c3 | 2016-07-08 10:46:21 -0700 | [diff] [blame] | 32 | c:\>c:\Python35\python -m venv c:\path\to\myenv |
Vinay Sajip | c4618e3 | 2012-07-10 08:21:07 +0100 | [diff] [blame] | 33 | |
Brett Cannon | 15552c3 | 2016-07-08 10:46:21 -0700 | [diff] [blame] | 34 | Alternatively, if you configured the ``PATH`` and ``PATHEXT`` variables for |
| 35 | your :ref:`Python installation <using-on-windows>`:: |
Vinay Sajip | c4618e3 | 2012-07-10 08:21:07 +0100 | [diff] [blame] | 36 | |
cocoatomo | d609b0c | 2017-10-27 13:42:11 +0900 | [diff] [blame] | 37 | c:\>python -m venv c:\path\to\myenv |
Vinay Sajip | c4618e3 | 2012-07-10 08:21:07 +0100 | [diff] [blame] | 38 | |
| 39 | The command, if run with ``-h``, will show the available options:: |
| 40 | |
Berker Peksag | a9744ae | 2016-01-30 12:17:10 +0200 | [diff] [blame] | 41 | usage: venv [-h] [--system-site-packages] [--symlinks | --copies] [--clear] |
| 42 | [--upgrade] [--without-pip] |
| 43 | ENV_DIR [ENV_DIR ...] |
Vinay Sajip | c4618e3 | 2012-07-10 08:21:07 +0100 | [diff] [blame] | 44 | |
| 45 | Creates virtual Python environments in one or more target directories. |
| 46 | |
| 47 | positional arguments: |
Brett Cannon | 15552c3 | 2016-07-08 10:46:21 -0700 | [diff] [blame] | 48 | ENV_DIR A directory to create the environment in. |
Vinay Sajip | c4618e3 | 2012-07-10 08:21:07 +0100 | [diff] [blame] | 49 | |
| 50 | optional arguments: |
Brett Cannon | 15552c3 | 2016-07-08 10:46:21 -0700 | [diff] [blame] | 51 | -h, --help show this help message and exit |
| 52 | --system-site-packages |
| 53 | Give the virtual environment access to the system |
| 54 | site-packages dir. |
| 55 | --symlinks Try to use symlinks rather than copies, when symlinks |
| 56 | are not the default for the platform. |
| 57 | --copies Try to use copies rather than symlinks, even when |
| 58 | symlinks are the default for the platform. |
| 59 | --clear Delete the contents of the environment directory if it |
| 60 | already exists, before environment creation. |
| 61 | --upgrade Upgrade the environment directory to use this version |
| 62 | of Python, assuming Python has been upgraded in-place. |
| 63 | --without-pip Skips installing or upgrading pip in the virtual |
| 64 | environment (pip is bootstrapped by default) |
Nick Coghlan | 8fbdb09 | 2013-11-23 00:30:34 +1000 | [diff] [blame] | 65 | |
Brett Cannon | 15552c3 | 2016-07-08 10:46:21 -0700 | [diff] [blame] | 66 | Once an environment has been created, you may wish to activate it, e.g. by |
| 67 | sourcing an activate script in its bin directory. |
Vinay Sajip | c7e34fb | 2015-02-07 10:52:02 +0000 | [diff] [blame] | 68 | |
Nick Coghlan | 8fbdb09 | 2013-11-23 00:30:34 +1000 | [diff] [blame] | 69 | .. versionchanged:: 3.4 |
Larry Hastings | 3732ed2 | 2014-03-15 21:13:56 -0700 | [diff] [blame] | 70 | Installs pip by default, added the ``--without-pip`` and ``--copies`` |
| 71 | options |
Vinay Sajip | c4618e3 | 2012-07-10 08:21:07 +0100 | [diff] [blame] | 72 | |
Vinay Sajip | 71e7296 | 2015-01-23 19:35:12 +0000 | [diff] [blame] | 73 | .. versionchanged:: 3.4 |
| 74 | In earlier versions, if the target directory already existed, an error was |
TROUVERIE Joachim | e8eb972 | 2018-02-18 17:52:36 +0100 | [diff] [blame] | 75 | raised, unless the ``--clear`` or ``--upgrade`` option was provided. |
Vinay Sajip | c4618e3 | 2012-07-10 08:21:07 +0100 | [diff] [blame] | 76 | |
| 77 | The created ``pyvenv.cfg`` file also includes the |
| 78 | ``include-system-site-packages`` key, set to ``true`` if ``venv`` is |
| 79 | run with the ``--system-site-packages`` option, ``false`` otherwise. |
| 80 | |
Nick Coghlan | 8fbdb09 | 2013-11-23 00:30:34 +1000 | [diff] [blame] | 81 | Unless the ``--without-pip`` option is given, :mod:`ensurepip` will be |
| 82 | invoked to bootstrap ``pip`` into the virtual environment. |
| 83 | |
Brett Cannon | 15552c3 | 2016-07-08 10:46:21 -0700 | [diff] [blame] | 84 | Multiple paths can be given to ``venv``, in which case an identical virtual |
| 85 | environment will be created, according to the given options, at each provided |
| 86 | path. |
Vinay Sajip | c4618e3 | 2012-07-10 08:21:07 +0100 | [diff] [blame] | 87 | |
Brett Cannon | 15552c3 | 2016-07-08 10:46:21 -0700 | [diff] [blame] | 88 | Once a virtual environment has been created, it can be "activated" using a |
| 89 | script in the virtual environment's binary directory. The invocation of the |
| 90 | script is platform-specific: |
Vinay Sajip | c4618e3 | 2012-07-10 08:21:07 +0100 | [diff] [blame] | 91 | |
Andrew Svetlov | 65e9c57 | 2012-10-04 21:48:58 +0300 | [diff] [blame] | 92 | +-------------+-----------------+-----------------------------------------+ |
| 93 | | Platform | Shell | Command to activate virtual environment | |
| 94 | +=============+=================+=========================================+ |
| 95 | | Posix | bash/zsh | $ source <venv>/bin/activate | |
| 96 | +-------------+-----------------+-----------------------------------------+ |
| 97 | | | fish | $ . <venv>/bin/activate.fish | |
| 98 | +-------------+-----------------+-----------------------------------------+ |
| 99 | | | csh/tcsh | $ source <venv>/bin/activate.csh | |
| 100 | +-------------+-----------------+-----------------------------------------+ |
Berker Peksag | 6803f35 | 2016-06-27 13:10:47 +0300 | [diff] [blame] | 101 | | Windows | cmd.exe | C:\\> <venv>\\Scripts\\activate.bat | |
Andrew Svetlov | 65e9c57 | 2012-10-04 21:48:58 +0300 | [diff] [blame] | 102 | +-------------+-----------------+-----------------------------------------+ |
Berker Peksag | 6803f35 | 2016-06-27 13:10:47 +0300 | [diff] [blame] | 103 | | | PowerShell | PS C:\\> <venv>\\Scripts\\Activate.ps1 | |
Andrew Svetlov | 65e9c57 | 2012-10-04 21:48:58 +0300 | [diff] [blame] | 104 | +-------------+-----------------+-----------------------------------------+ |
Vinay Sajip | c4618e3 | 2012-07-10 08:21:07 +0100 | [diff] [blame] | 105 | |
| 106 | You don't specifically *need* to activate an environment; activation just |
Brett Cannon | 15552c3 | 2016-07-08 10:46:21 -0700 | [diff] [blame] | 107 | prepends the virtual environment's binary directory to your path, so that |
| 108 | "python" invokes the virtual environment's Python interpreter and you can run |
| 109 | installed scripts without having to use their full path. However, all scripts |
| 110 | installed in a virtual environment should be runnable without activating it, |
| 111 | and run with the virtual environment's Python automatically. |
Vinay Sajip | c4618e3 | 2012-07-10 08:21:07 +0100 | [diff] [blame] | 112 | |
Brett Cannon | 15552c3 | 2016-07-08 10:46:21 -0700 | [diff] [blame] | 113 | You can deactivate a virtual environment by typing "deactivate" in your shell. |
| 114 | The exact mechanism is platform-specific: for example, the Bash activation |
| 115 | script defines a "deactivate" function, whereas on Windows there are separate |
| 116 | scripts called ``deactivate.bat`` and ``Deactivate.ps1`` which are installed |
| 117 | when the virtual environment is created. |
Vinay Sajip | c4618e3 | 2012-07-10 08:21:07 +0100 | [diff] [blame] | 118 | |
R David Murray | 575fb31 | 2013-12-25 23:21:03 -0500 | [diff] [blame] | 119 | .. versionadded:: 3.4 |
| 120 | ``fish`` and ``csh`` activation scripts. |