Lines Matching +full:environment +full:- +full:file
1 :mod:`!venv` --- Creation of virtual environments
16 --------------
18 .. _venv-def:
19 .. _venv-intro:
24 A virtual environment is created on top of an existing
25 Python installation, known as the virtual environment's "base" Python, and may
26 optionally be isolated from the packages in the base environment,
27 so only those explicitly installed in the virtual environment are available.
29 When used from within a virtual environment, common installation tools such as
30 :pypi:`pip` will install Python packages into a virtual environment
33 A virtual environment is (amongst other things):
46 * Considered as disposable -- it should be simple to delete and recreate it from
47 scratch. You don't place any project code in the environment.
49 * Not considered as movable or copyable -- you just recreate the same
50 environment in the target location.
57 …https://packaging.python.org/guides/installing-using-pip-and-virtual-environments/#create-and-use-…
59 .. include:: ../includes/wasm-mobile-notavail.rst
62 -----------------------------
64 :ref:`Virtual environments <venv-def>` are created by executing the ``venv``
67 .. code-block:: shell
69 python -m venv /path/to/new/virtual/environment
72 and places a :file:`pyvenv.cfg` file in it with a ``home`` key
74 It also creates a :file:`bin` (or :file:`Scripts` on Windows) subdirectory
76 (as appropriate for the platform or arguments used at environment creation time).
77 It also creates a :file:`lib/pythonX.Y/site-packages` subdirectory
78 (on Windows, this is :file:`Lib\site-packages`).
79 If an existing directory is specified, it will be re-used.
84 .. deprecated-removed:: 3.6 3.8
92 .. code-block:: ps1con
94 PS> python -m venv C:\path\to\new\virtual\environment
96 The command, if run with ``-h``, will show the available options::
98 usage: venv [-h] [--system-site-packages] [--symlinks | --copies] [--clear]
99 [--upgrade] [--without-pip] [--prompt PROMPT] [--upgrade-deps]
100 [--without-scm-ignore-files]
106 ENV_DIR A directory to create the environment in.
109 -h, --help show this help message and exit
110 --system-site-packages
111 Give the virtual environment access to the system
112 site-packages dir.
113 --symlinks Try to use symlinks rather than copies, when
115 --copies Try to use copies rather than symlinks, even when
117 --clear Delete the contents of the environment directory
118 if it already exists, before environment creation.
119 --upgrade Upgrade the environment directory to use this
121 upgraded in-place.
122 --without-pip Skips installing or upgrading pip in the virtual
123 environment (pip is bootstrapped by default)
124 --prompt PROMPT Provides an alternative prompt prefix for this
125 environment.
126 --upgrade-deps Upgrade core dependencies (pip) to the latest
128 --without-scm-ignore-files
129 Skips adding SCM ignore files to the environment
132 Once an environment has been created, you may wish to activate it, e.g. by
137 Installs pip by default, added the ``--without-pip`` and ``--copies``
142 raised, unless the ``--clear`` or ``--upgrade`` option was provided.
145 Add ``--upgrade-deps`` option to upgrade pip + setuptools to the latest on PyPI.
153 Added the ``--without-scm-ignore-files`` option.
155 ``venv`` now creates a :file:`.gitignore` file for Git by default.
159 particular note is that double-clicking ``python.exe`` in File Explorer
160 will resolve the symlink eagerly and ignore the virtual environment.
167 .. code-block:: powershell
169 PS C:\> Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser
175 The created :file:`pyvenv.cfg` file also includes the
176 ``include-system-site-packages`` key, set to ``true`` if ``venv`` is
177 run with the ``--system-site-packages`` option, ``false`` otherwise.
179 Unless the ``--without-pip`` option is given, :mod:`ensurepip` will be
180 invoked to bootstrap ``pip`` into the virtual environment.
183 environment will be created, according to the given options, at each provided
186 .. _venv-explanation:
189 --------------
191 When a Python interpreter is running from a virtual environment,
193 point to the directories of the virtual environment,
195 point to those of the base Python used to create the environment.
198 running from a virtual environment.
200 A virtual environment may be "activated" using a script in its binary directory
203 :program:`python` will invoke the environment's Python interpreter
205 The invocation of the activation script is platform-specific
207 containing the virtual environment):
209 +-------------+------------+--------------------------------------------------+
210 | Platform | Shell | Command to activate virtual environment |
213 | +------------+--------------------------------------------------+
215 | +------------+--------------------------------------------------+
217 | +------------+--------------------------------------------------+
219 +-------------+------------+--------------------------------------------------+
221 | +------------+--------------------------------------------------+
223 +-------------+------------+--------------------------------------------------+
232 You don't specifically *need* to activate a virtual environment,
233 as you can just specify the full path to that environment's
235 Furthermore, all scripts installed in the environment
239 a "shebang" line which points to the environment's Python interpreter,
240 :samp:`#!/{<path-to-venv>}/bin/python`.
243 you have the :ref:`launcher` installed. Thus, double-clicking an installed
245 without the environment needing to be activated or on the :envvar:`PATH`.
247 When a virtual environment has been activated, the :envvar:`!VIRTUAL_ENV`
248 environment variable is set to the path of the environment.
249 Since explicitly activating a virtual environment is not required to use it,
251 whether a virtual environment is being used.
254 environment to be activated, their shebang lines contain the absolute paths
255 to their environment's interpreters. Because of this, environments are
256 inherently non-portable, in the general case. You should always have a
257 simple means of recreating an environment (for example, if you have a
258 requirements file ``requirements.txt``, you can invoke ``pip install -r
259 requirements.txt`` using the environment's ``pip`` to install all of the
260 packages needed by the environment). If for any reason you need to move the
261 environment to a new location, you should recreate it at the desired
262 location and delete the one at the old location. If you move an environment
264 environment in its new location. Otherwise, software installed into the
265 environment may not work as expected.
267 You can deactivate a virtual environment by typing ``deactivate`` in your shell.
268 The exact mechanism is platform-specific and is an internal implementation
272 .. _venv-api:
275 ---
279 The high-level method described above makes use of a simple API which provides
280 mechanisms for third-party virtual environment creators to customize environment
291 * *system_site_packages* -- a boolean value indicating that the system Python
292 site-packages should be available to the environment (defaults to ``False``).
294 * *clear* -- a boolean value which, if true, will delete the contents of
295 any existing target directory, before creating the environment.
297 * *symlinks* -- a boolean value indicating whether to attempt to symlink the
300 * *upgrade* -- a boolean value which, if true, will upgrade an existing
301 environment with the running Python - for use when that Python has been
302 upgraded in-place (defaults to ``False``).
304 * *with_pip* -- a boolean value which, if true, ensures pip is
305 installed in the virtual environment. This uses :mod:`ensurepip` with
306 the ``--default-pip`` option.
308 * *prompt* -- a string to be used after virtual environment is activated
309 (defaults to ``None`` which means directory name of the environment would
313 * *upgrade_deps* -- Update the base venv modules to the latest on PyPI
315 * *scm_ignore_files* -- Create ignore files based for the specified source
337 Create a virtual environment by specifying the target directory
339 virtual environment. The ``create`` method will either create the
340 environment in the specified directory, or raise an appropriate
348 Create a virtualized Python environment in a directory.
349 env_dir is the target directory to create an environment in.
364 Creates the environment directory and all necessary subdirectories that
368 ``clear=True``, contents of the environment directory will be cleared
374 * ``env_dir`` - The location of the virtual environment. Used for
377 * ``env_name`` - The name of the virtual environment. Used for
380 * ``prompt`` - The prompt to be used by the activation scripts. Used for
383 * ``executable`` - The underlying Python executable used by the virtual
384 environment. This takes into account the case where a virtual environment
385 is created from another virtual environment.
387 * ``inc_path`` - The include path for the virtual environment.
389 * ``lib_path`` - The purelib path for the virtual environment.
391 * ``bin_path`` - The script path for the virtual environment.
393 * ``bin_name`` - The name of the script path relative to the virtual
394 environment location. Used for ``__VENV_BIN_NAME__`` in activation
397 * ``env_exe`` - The name of the Python interpreter in the virtual
398 environment. Used for ``__VENV_PYTHON__`` in activation scripts
401 * ``env_exec_cmd`` - The name of the Python interpreter, taking into
403 the virtual environment.
417 Creates the ``pyvenv.cfg`` configuration file in the environment.
421 Creates a copy or symlink to the Python executable in the environment.
429 environment.
434 in the environment. This is done by shelling out to the
435 ``pip`` executable in the environment.
445 implementations to pre-install packages in the virtual environment or
446 perform other post-creation steps.
452 assist in installing custom scripts into the virtual environment.
456 ``bin`` directory in the environment. The contents of ``common`` and the
460 * ``__VENV_DIR__`` is replaced with the absolute path of the environment
463 * ``__VENV_NAME__`` is replaced with the environment name (final path
464 segment of environment directory).
466 * ``__VENV_PROMPT__`` is replaced with the prompt (the environment
473 environment's executable.
475 The directories are allowed to exist (for when an existing environment
480 Creates a ``.gitignore`` file within the virtual environment that causes
495 There is also a module-level convenience function:
519 --------------------------------------
522 subclass which installs setuptools and pip into a created virtual environment::
536 easy_install other packages into the created virtual environment.
539 created virtual environment.
541 virtual environment.
566 Set up any packages which need to be pre-installed into the
567 virtual environment being created.
569 :param context: The information for the virtual environment
595 sys.stderr.write(s.decode('utf-8'))
601 fn = os.path.split(path)[-1]
604 # Download script into the virtual environment's binaries folder
616 # Install in the virtual environment
630 # Clean up - no longer needed
635 Install setuptools in the virtual environment.
637 :param context: The information for the virtual environment
643 pred = lambda o: o.startswith('setuptools-') and o.endswith('.tar.gz')
651 Install pip in the virtual environment.
653 :param context: The information for the virtual environment
656 url = 'https://bootstrap.pypa.io/get-pip.py'
670 'virtual environment.')
671 parser.add_argument('--no-setuptools', default=False,
674 "virtual environment.")
675 parser.add_argument('--no-pip', default=False,
678 "environment.")
679 parser.add_argument('--system-site-packages', default=False,
681 help='Give the virtual environment access to the '
682 'system site-packages dir.')
687 parser.add_argument('--symlinks', default=use_symlinks,
692 parser.add_argument('--clear', default=False, action='store_true',
694 'virtual environment '
697 'environment creation.')
698 parser.add_argument('--upgrade', default=False, action='store_true',
700 'environment directory to '
704 'in-place.')
705 parser.add_argument('--verbose', default=False, action='store_true',
711 raise ValueError('you cannot supply --upgrade and --clear together.')
728 print('Error: %s' % e, file=sys.stderr)