1 Creation of :ref:`virtual environments <venv-def>` is done by executing the 2 command ``venv``:: 3 4 python3 -m venv /path/to/new/virtual/environment 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 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 10 containing a copy/symlink of the Python binary/binaries (as appropriate for the 11 platform 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 14 directory 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 26 On Windows, invoke the ``venv`` command as follows:: 27 28 c:\>c:\Python35\python -m venv c:\path\to\myenv 29 30 Alternatively, if you configured the ``PATH`` and ``PATHEXT`` variables for 31 your :ref:`Python installation <using-on-windows>`:: 32 33 c:\>python -m venv c:\path\to\myenv 34 35 The 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 80 The created ``pyvenv.cfg`` file also includes the 81 ``include-system-site-packages`` key, set to ``true`` if ``venv`` is 82 run with the ``--system-site-packages`` option, ``false`` otherwise. 83 84 Unless the ``--without-pip`` option is given, :mod:`ensurepip` will be 85 invoked to bootstrap ``pip`` into the virtual environment. 86 87 Multiple paths can be given to ``venv``, in which case an identical virtual 88 environment will be created, according to the given options, at each provided 89 path. 90 91 Once a virtual environment has been created, it can be "activated" using a 92 script in the virtual environment's binary directory. The invocation of the 93 script is platform-specific (`<venv>` must be replaced by the path of the 94 directory 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 110 You don't specifically *need* to activate an environment; activation just 111 prepends the virtual environment's binary directory to your path, so that 112 "python" invokes the virtual environment's Python interpreter and you can run 113 installed scripts without having to use their full path. However, all scripts 114 installed in a virtual environment should be runnable without activating it, 115 and run with the virtual environment's Python automatically. 116 117 You can deactivate a virtual environment by typing "deactivate" in your shell. 118 The exact mechanism is platform-specific: for example, the Bash activation 119 script defines a "deactivate" function, whereas on Windows there are separate 120 scripts called ``deactivate.bat`` and ``Deactivate.ps1`` which are installed 121 when the virtual environment is created. 122 123 .. versionadded:: 3.4 124 ``fish`` and ``csh`` activation scripts. 125
