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 (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 `deprecated in Python 3.6 20 <https://docs.python.org/dev/whatsnew/3.6.html#deprecated-features>`_. 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 108Once a virtual environment has been created, it can be "activated" using a 109script in the virtual environment's binary directory. The invocation of the 110script is platform-specific (`<venv>` must be replaced by the path of the 111directory containing the virtual environment): 112 113+-------------+-----------------+-----------------------------------------+ 114| Platform | Shell | Command to activate virtual environment | 115+=============+=================+=========================================+ 116| POSIX | bash/zsh | $ source <venv>/bin/activate | 117+-------------+-----------------+-----------------------------------------+ 118| | fish | $ source <venv>/bin/activate.fish | 119+-------------+-----------------+-----------------------------------------+ 120| | csh/tcsh | $ source <venv>/bin/activate.csh | 121+-------------+-----------------+-----------------------------------------+ 122| | PowerShell Core | $ <venv>/bin/Activate.ps1 | 123+-------------+-----------------+-----------------------------------------+ 124| Windows | cmd.exe | C:\\> <venv>\\Scripts\\activate.bat | 125+-------------+-----------------+-----------------------------------------+ 126| | PowerShell | PS C:\\> <venv>\\Scripts\\Activate.ps1 | 127+-------------+-----------------+-----------------------------------------+ 128 129When a virtual environment is active, the :envvar:`VIRTUAL_ENV` environment 130variable is set to the path of the virtual environment. This can be used to 131check if one is running inside a virtual environment. 132 133You don't specifically *need* to activate an environment; activation just 134prepends the virtual environment's binary directory to your path, so that 135"python" invokes the virtual environment's Python interpreter and you can run 136installed scripts without having to use their full path. However, all scripts 137installed in a virtual environment should be runnable without activating it, 138and run with the virtual environment's Python automatically. 139 140You can deactivate a virtual environment by typing "deactivate" in your shell. 141The exact mechanism is platform-specific and is an internal implementation 142detail (typically a script or shell function will be used). 143 144.. versionadded:: 3.4 145 ``fish`` and ``csh`` activation scripts. 146 147.. versionadded:: 3.8 148 PowerShell activation scripts installed under POSIX for PowerShell Core 149 support. 150