1Creation of :ref:`virtual environments <venv-def>` is done by executing the
2command ``venv``::
3
4    python -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 (a common name for the target directory is ``.venv``).  It also creates
10a ``bin`` (or ``Scripts`` on Windows) subdirectory containing a copy/symlink
11of the Python binary/binaries (as appropriate for the platform or arguments
12used at environment creation time). It also creates an (initially empty)
13``lib/pythonX.Y/site-packages`` subdirectory (on Windows, this is
14``Lib\site-packages``). If an existing directory is specified, it will be
15re-used.
16
17.. deprecated:: 3.6
18   ``pyvenv`` was the recommended tool for creating virtual environments for
19   Python 3.3 and 3.4, and is
20   :ref:`deprecated in Python 3.6 <whatsnew36-venv>`.
21
22.. versionchanged:: 3.5
23   The use of ``venv`` is now recommended for creating virtual environments.
24
25.. highlight:: none
26
27On Windows, invoke the ``venv`` command as follows::
28
29    c:\>c:\Python35\python -m venv c:\path\to\myenv
30
31Alternatively, if you configured the ``PATH`` and ``PATHEXT`` variables for
32your :ref:`Python installation <using-on-windows>`::
33
34    c:\>python -m venv c:\path\to\myenv
35
36The command, if run with ``-h``, will show the available options::
37
38    usage: venv [-h] [--system-site-packages] [--symlinks | --copies] [--clear]
39                [--upgrade] [--without-pip] [--prompt PROMPT] [--upgrade-deps]
40                ENV_DIR [ENV_DIR ...]
41
42    Creates virtual Python environments in one or more target directories.
43
44    positional arguments:
45      ENV_DIR               A directory to create the environment in.
46
47    optional arguments:
48      -h, --help            show this help message and exit
49      --system-site-packages
50                            Give the virtual environment access to the system
51                            site-packages dir.
52      --symlinks            Try to use symlinks rather than copies, when symlinks
53                            are not the default for the platform.
54      --copies              Try to use copies rather than symlinks, even when
55                            symlinks are the default for the platform.
56      --clear               Delete the contents of the environment directory if it
57                            already exists, before environment creation.
58      --upgrade             Upgrade the environment directory to use this version
59                            of Python, assuming Python has been upgraded in-place.
60      --without-pip         Skips installing or upgrading pip in the virtual
61                            environment (pip is bootstrapped by default)
62      --prompt PROMPT       Provides an alternative prompt prefix for this
63                            environment.
64      --upgrade-deps        Upgrade core dependencies: pip setuptools to the
65                            latest version in PyPI
66
67    Once an environment has been created, you may wish to activate it, e.g. by
68    sourcing an activate script in its bin directory.
69
70.. versionchanged:: 3.9
71   Add ``--upgrade-deps`` option to upgrade pip + setuptools to the latest on PyPI
72
73.. versionchanged:: 3.4
74   Installs pip by default, added the ``--without-pip``  and ``--copies``
75   options
76
77.. versionchanged:: 3.4
78   In earlier versions, if the target directory already existed, an error was
79   raised, unless the ``--clear`` or ``--upgrade`` option was provided.
80
81.. note::
82   While symlinks are supported on Windows, they are not recommended. Of
83   particular note is that double-clicking ``python.exe`` in File Explorer
84   will resolve the symlink eagerly and ignore the virtual environment.
85
86.. note::
87   On Microsoft Windows, it may be required to enable the ``Activate.ps1``
88   script by setting the execution policy for the user. You can do this by
89   issuing the following PowerShell command:
90
91   PS C:\> Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser
92
93   See `About Execution Policies
94   <https://go.microsoft.com/fwlink/?LinkID=135170>`_
95   for more information.
96
97The created ``pyvenv.cfg`` file also includes the
98``include-system-site-packages`` key, set to ``true`` if ``venv`` is
99run with the ``--system-site-packages`` option, ``false`` otherwise.
100
101Unless the ``--without-pip`` option is given, :mod:`ensurepip` will be
102invoked to bootstrap ``pip`` into the virtual environment.
103
104Multiple paths can be given to ``venv``, in which case an identical virtual
105environment will be created, according to the given options, at each provided
106path.
107
108