1Creation of :ref:`virtual environments <venv-def>` is done by executing the
2command ``venv``::
3
4    python3 -m venv /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 from which the command
9was run.  It also creates a ``bin`` (or ``Scripts`` on Windows) subdirectory
10containing a copy/symlink of the Python binary/binaries (as appropriate for the
11platform or arguments used at environment creation time). It also creates an
12(initially empty) ``lib/pythonX.Y/site-packages`` subdirectory
13(on Windows, this is ``Lib\site-packages``). If an existing
14directory is specified, it will be re-used.
15
16.. deprecated:: 3.6
17   ``pyvenv`` was the recommended tool for creating virtual environments for
18   Python 3.3 and 3.4, and is `deprecated in Python 3.6
19   <https://docs.python.org/dev/whatsnew/3.6.html#deprecated-features>`_.
20
21.. versionchanged:: 3.5
22   The use of ``venv`` is now recommended for creating virtual environments.
23
24.. highlight:: none
25
26On Windows, invoke the ``venv`` command as follows::
27
28    c:\>c:\Python35\python -m venv c:\path\to\myenv
29
30Alternatively, if you configured the ``PATH`` and ``PATHEXT`` variables for
31your :ref:`Python installation <using-on-windows>`::
32
33    c:\>python -m venv c:\path\to\myenv
34
35The command, if run with ``-h``, will show the available options::
36
37    usage: venv [-h] [--system-site-packages] [--symlinks | --copies] [--clear]
38                [--upgrade] [--without-pip] [--prompt PROMPT]
39                ENV_DIR [ENV_DIR ...]
40
41    Creates virtual Python environments in one or more target directories.
42
43    positional arguments:
44      ENV_DIR               A directory to create the environment in.
45
46    optional arguments:
47      -h, --help            show this help message and exit
48      --system-site-packages
49                            Give the virtual environment access to the system
50                            site-packages dir.
51      --symlinks            Try to use symlinks rather than copies, when symlinks
52                            are not the default for the platform.
53      --copies              Try to use copies rather than symlinks, even when
54                            symlinks are the default for the platform.
55      --clear               Delete the contents of the environment directory if it
56                            already exists, before environment creation.
57      --upgrade             Upgrade the environment directory to use this version
58                            of Python, assuming Python has been upgraded in-place.
59      --without-pip         Skips installing or upgrading pip in the virtual
60                            environment (pip is bootstrapped by default)
61      --prompt PROMPT       Provides an alternative prompt prefix for this
62                            environment.
63
64    Once an environment has been created, you may wish to activate it, e.g. by
65    sourcing an activate script in its bin directory.
66
67.. versionchanged:: 3.4
68   Installs pip by default, added the ``--without-pip``  and ``--copies``
69   options
70
71.. versionchanged:: 3.4
72   In earlier versions, if the target directory already existed, an error was
73   raised, unless the ``--clear`` or ``--upgrade`` option was provided.
74
75.. note::
76   While symlinks are supported on Windows, they are not recommended. Of
77   particular note is that double-clicking ``python.exe`` in File Explorer
78   will resolve the symlink eagerly and ignore the virtual environment.
79
80The created ``pyvenv.cfg`` file also includes the
81``include-system-site-packages`` key, set to ``true`` if ``venv`` is
82run with the ``--system-site-packages`` option, ``false`` otherwise.
83
84Unless the ``--without-pip`` option is given, :mod:`ensurepip` will be
85invoked to bootstrap ``pip`` into the virtual environment.
86
87Multiple paths can be given to ``venv``, in which case an identical virtual
88environment will be created, according to the given options, at each provided
89path.
90
91Once a virtual environment has been created, it can be "activated" using a
92script in the virtual environment's binary directory. The invocation of the
93script is platform-specific (`<venv>` must be replaced by the path of the
94directory containing the virtual environment):
95
96+-------------+-----------------+-----------------------------------------+
97| Platform    | Shell           | Command to activate virtual environment |
98+=============+=================+=========================================+
99| Posix       | bash/zsh        | $ source <venv>/bin/activate            |
100+-------------+-----------------+-----------------------------------------+
101|             | fish            | $ . <venv>/bin/activate.fish            |
102+-------------+-----------------+-----------------------------------------+
103|             | csh/tcsh        | $ source <venv>/bin/activate.csh        |
104+-------------+-----------------+-----------------------------------------+
105| Windows     | cmd.exe         | C:\\> <venv>\\Scripts\\activate.bat     |
106+-------------+-----------------+-----------------------------------------+
107|             | PowerShell      | PS C:\\> <venv>\\Scripts\\Activate.ps1  |
108+-------------+-----------------+-----------------------------------------+
109
110You don't specifically *need* to activate an environment; activation just
111prepends the virtual environment's binary directory to your path, so that
112"python" invokes the virtual environment's Python interpreter and you can run
113installed scripts without having to use their full path. However, all scripts
114installed in a virtual environment should be runnable without activating it,
115and run with the virtual environment's Python automatically.
116
117You can deactivate a virtual environment by typing "deactivate" in your shell.
118The exact mechanism is platform-specific: for example, the Bash activation
119script defines a "deactivate" function, whereas on Windows there are separate
120scripts called ``deactivate.bat`` and ``Deactivate.ps1`` which are installed
121when the virtual environment is created.
122
123.. versionadded:: 3.4
124   ``fish`` and ``csh`` activation scripts.
125