blob: 5fc46d245beb734aed823e158df3a9598f0c293a [file] [log] [blame]
Vinay Sajipc4618e32012-07-10 08:21:07 +01001Creation of :ref:`virtual environments <venv-def>` is done by executing the
2``pyvenv`` script::
3
4 pyvenv /path/to/new/virtual/environment
5
6Running this command creates the target directory (creating any parent
7directories that don't exist already) and places a ``pyvenv.cfg`` file in it
8with a ``home`` key pointing to the Python installation the command was run
9from. It also creates a ``bin`` (or ``Scripts`` on Windows) subdirectory
10containing a copy of the ``python`` binary (or binaries, in the case of
11Windows). It also creates an (initially empty) ``lib/pythonX.Y/site-packages``
12subdirectory (on Windows, this is ``Lib\site-packages``).
13
Larry Hastings3732ed22014-03-15 21:13:56 -070014.. seealso::
15
16 `Python Packaging User Guide: Creating and using virtual environments
Georg Brandl525d3552014-10-29 10:26:56 +010017 <https://packaging.python.org/en/latest/installing.html#virtual-environments>`__
Larry Hastings3732ed22014-03-15 21:13:56 -070018
Vinay Sajipc4618e32012-07-10 08:21:07 +010019.. highlight:: none
20
21On Windows, you may have to invoke the ``pyvenv`` script as follows, if you
22don't have the relevant PATH and PATHEXT settings::
23
24 c:\Temp>c:\Python33\python c:\Python33\Tools\Scripts\pyvenv.py myenv
25
26or equivalently::
27
28 c:\Temp>c:\Python33\python -m venv myenv
29
30The command, if run with ``-h``, will show the available options::
31
32 usage: pyvenv [-h] [--system-site-packages] [--symlinks] [--clear]
Nick Coghlan8fbdb092013-11-23 00:30:34 +100033 [--upgrade] [--without-pip] ENV_DIR [ENV_DIR ...]
Vinay Sajipc4618e32012-07-10 08:21:07 +010034
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 Hastings3732ed22014-03-15 21:13:56 -070046 --copies Try to use copies rather than symlinks, even when
47 symlinks are the default for the platform.
Vinay Sajipc4618e32012-07-10 08:21:07 +010048 --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 Coghlan8fbdb092013-11-23 00:30:34 +100053 --without-pip Skips installing or upgrading pip in the virtual
54 environment (pip is bootstrapped by default)
55
56.. versionchanged:: 3.4
Larry Hastings3732ed22014-03-15 21:13:56 -070057 Installs pip by default, added the ``--without-pip`` and ``--copies``
58 options
Vinay Sajipc4618e32012-07-10 08:21:07 +010059
Vinay Sajip71e72962015-01-23 19:35:12 +000060.. versionchanged:: 3.4
61 In earlier versions, if the target directory already existed, an error was
62 raised, unless the ``--clear`` or ``--upgrade`` option was provided. Now,
63 if an existing directory is specified, its contents are removed and
64 the directory is processed as if it had been newly created.
Vinay Sajipc4618e32012-07-10 08:21:07 +010065
66The created ``pyvenv.cfg`` file also includes the
67``include-system-site-packages`` key, set to ``true`` if ``venv`` is
68run with the ``--system-site-packages`` option, ``false`` otherwise.
69
Nick Coghlan8fbdb092013-11-23 00:30:34 +100070Unless the ``--without-pip`` option is given, :mod:`ensurepip` will be
71invoked to bootstrap ``pip`` into the virtual environment.
72
Vinay Sajipc4618e32012-07-10 08:21:07 +010073Multiple paths can be given to ``pyvenv``, in which case an identical
74virtualenv will be created, according to the given options, at each
75provided path.
76
77Once a venv has been created, it can be "activated" using a script in the
Andrew Svetlov65e9c572012-10-04 21:48:58 +030078venv's binary directory. The invocation of the script is platform-specific:
Vinay Sajipc4618e32012-07-10 08:21:07 +010079
Andrew Svetlov65e9c572012-10-04 21:48:58 +030080+-------------+-----------------+-----------------------------------------+
81| Platform | Shell | Command to activate virtual environment |
82+=============+=================+=========================================+
83| Posix | bash/zsh | $ source <venv>/bin/activate |
84+-------------+-----------------+-----------------------------------------+
85| | fish | $ . <venv>/bin/activate.fish |
86+-------------+-----------------+-----------------------------------------+
87| | csh/tcsh | $ source <venv>/bin/activate.csh |
88+-------------+-----------------+-----------------------------------------+
89| Windows | cmd.exe | C:\> <venv>/Scripts/activate.bat |
90+-------------+-----------------+-----------------------------------------+
91| | PowerShell | PS C:\> <venv>/Scripts/Activate.ps1 |
92+-------------+-----------------+-----------------------------------------+
Vinay Sajipc4618e32012-07-10 08:21:07 +010093
94You don't specifically *need* to activate an environment; activation just
95prepends the venv's binary directory to your path, so that "python" invokes the
96venv's Python interpreter and you can run installed scripts without having to
97use their full path. However, all scripts installed in a venv should be
98runnable without activating it, and run with the venv's Python automatically.
99
100You can deactivate a venv by typing "deactivate" in your shell. The exact
101mechanism is platform-specific: for example, the Bash activation script defines
102a "deactivate" function, whereas on Windows there are separate scripts called
103``deactivate.bat`` and ``Deactivate.ps1`` which are installed when the venv is
104created.
105
R David Murray575fb312013-12-25 23:21:03 -0500106.. versionadded:: 3.4
107 ``fish`` and ``csh`` activation scripts.