User Guide - virtualenv (2023)

introduction#

Virtualenv has a basic command:

venv virtual environment

This will create a python virtual environment with the same version as virtualenv installed in the subdirectoryvenv. The command line tool has several flags that change the behavior of the tool. A complete list can be found hereCLI-Flags.

The tool works in two phases:

• Phase 1discovers a Python interpreter from which to create a virtual environment (by default, this is the same Python as thevirtual environmentexpires, but we can change this via thePAGPossibility).

• Level 2creates a virtual environment on the specified destination (Meta), this can be broken down into four further sub-steps:

  • Create a python that corresponds to the target python interpreter from phase 1,

  • Install (bootstrap) seed packages (one or more of theNugget,configuration tools,Rad) in the created virtual environment,

  • Install the activation scripts in the virtual environment binary directory (these allow end users toActivatethe virtual environment from different shells).

  • Create files that mark the virtual environment as ignored by version control systems (we currently only support Git as Mercurial, Bazaar, or SVN do not support skipping files in subdirectories). This step can be skipped withno-vcs-ignorePossibility.

The Python in your new virtual environment is effectively isolated from the Python used to create it.

discovery of python#

The first thing we need to be able to create a virtual environment is a Python interpreter. This tells the tool what kind of virtual environment you want to create, think of it like this: version, architecture, implementation.

virtual environmentSince this is a Python application, there is always at least one available, thevirtual environmentitself and as such is the element recognized by default. That is, when you installvirtual environmentsubpython3.8, virtualenv creates virtual environments that also match the default version3.8.

The Python virtual environments that are typically created are not stand-alone. A complete python package usually consists of thousands of files, so it is not efficient to reinstall all of python in a new folder. Instead, virtual environments are mere shells containing little of their own and borrowing most of the Python system (that's what you installed when you installed Python yourself). This means that when you upgrade your system to Python, your virtual environmentscouldbreak, so be careful. The advantage of this, relative to the Python system, is that creating virtual environments can be fast.

Here we describe the built-in mechanism (note that this can be extended via plugins). The CLI flagPAGoPitonallows you to provide a Python specifier for the type of virtual environment you want, the format is:

• a relative/absolute path to a Python interpreter,

• an identifier that identifies the Python implementation, version, and architecture in the following format:

  {Piton implementation Name}{execution}{architecture}

  We have the following restrictions:

  • The Python implementation consists entirely of alphabetic characters (Pitonmeans any implementation, and if absent, it is used by defaultPiton),

  • version is a version number separated by dots,

  • architecture is-64o-32(lack of fundsany).

  For example:

  See Also

  Conan Virtual Environments: Manage your C and C++ toolsIntroducing the Conan CLion Plugin | CLion's blog

  • python3.8.1means any versioned Python implementation3.8.1,

  • 3means any Python implementation with major version3,

  • cpython3means aCPythonDeployment with version3,

  • pypy2means a Python interpreter with thePyPyImplementation and major version2.

  Given the specifiervirtual environmentwill use the following strategy to discover/find the system executable:

  • If we're on Windows, look in the Windows registry and see if we see any registered Python implementations that meet the specification. This is in line with the expectations set withinPEP-514

  • Try to find a matching python executable in the folders listed in theFARenvironmental variable. In this case, we are trying to find an executable that has a name more or less similar to the specification (see the implementation code for the exact logic).

Creator#

These actually set up the virtual environment, usually as a reference to the Python system. virtualenvat currently has two types of virtual environments:

• venvThis delegates the build process to thevenvmodule how to describe it inPEP 405. This is only available in the interpreters version of Python.3.5or higher and also has the disadvantage that virtualenvhas toCreate a process to call this module (unless virtualalenv is installed on the Python system), which can be an expensive operation (especially on Windows).

• Incorporated- That meansvirtual environmentit is capable of performing the compilation process itself (knowing exactly which files to compile and which system files to reference). The creator by nameIncorporatedis an alias for the first such builder (we provide builders for different target environments, all with differences in the actual build operations, such as CPython 2 on Windows, PyPy2 on Windows, CPython3 on Posix, PyPy3 on Posix, etc. see a complete listCreator).

planters#

These will install some seed packages for you (one or more of:Nugget,configuration tools,Rad) that allows you to install additional python packages in the created virtual environment (by calling pip). There are two main seed mechanisms available:

• Nugget- This method uses the pip package with virtualenv to install the seed packages (note that this requires the creation of a new child process, which can be expensive, especially on Windows).

• application data- This method uses the user application data directory to create installation images. These images only need to be created once, and subsequent virtual environments can simply place these images in their pure Python library path (theSite-PackageBinder). This allows all but the first virtual environment creation to be lightning fast (aNuggetThe mechanism typically takes 98% of the virtual environment creation time. By creating this installation image, which we can simply link to the virtual environment's installation directory, we can reduce the first minute and 10 seconds to just 8 seconds for a copy. either0,8Seconds if symlinks are available: This is as low as possible on Windows, Linux/macOS with symlinks100msof 3+ seconds). To overwrite the file system location of the seed cache, one can use theVIRTUALENV_OVERRIDE_APP_DATAenvironmental variable.

activators#

These are activation scripts that are combined with your shell configuration to ensure that python virtual environment commands take precedence over your system paths. For example when callingNuggetYour shell returned the Python system pip before activation. Once you have activated this should relate to virtual environmentsNugget.But note that we only change the priority; so if your virtual environmentscontainer/scriptsfolder does not contain an executable, it will still resolve to the same executable that would have resolved before activation.

For a list of the shells we offer as activators, seeactivators. The location of these is right next to the python executables: usuallyscriptsfolder in Windows,containerin POSIX. his name isActivate, plus one specific extension per trigger, no extension for bash. You can usually summon them by searching for them. The source command may vary depending on the shell, e.g. in bash it isThose(o.):

What comev/bin/activate

The activation script prepends the virtual environment binary folder to thisFARenvironmental variable. It's really just a convenience, since you could do the same thing yourself.

Note that you don't have to activate a virtual environment to use it. Instead, you can use the full paths to your executables instead of relying on your shell to resolve them in your virtual environment.

Activation scripts also modify the shell prompt to indicate which environment is currently active by prepending the environment name in parentheses, for example(venv). You can disable this behavior by setting the environment variableVIRTUAL_ENV_DISABLE_PROMPTto any value.

Scripts also provide adeactivateCommand you can use to undo the operation:

deactivate

Establecer-ExecutionPolicy RemoteSigned

A longer explanation of this can be found in Allison Kaptur's 2013 blog post:There is no magic: virtualenveditionexplains how virtualenv uses bash and python andFARYPYTONHAUSto isolate the paths of the virtual environments.

programmatic API#

At the momentvirtual environmentit only provides a CLI level interface. If you want to enable the invocation of Python environments from within Python, you should use thevirtualenv.cli_runMethod; that takes a whileargument-argument where you can pass the options as you would from the command line. The execution returns a session object that contains data about the created virtual environment.

outside virtual environment matter CLI_executeCLI_execute(["venv"])

virtual environmentCLI_execute(argument,options=none,setup_logging=TRUE,env=none)#

Create a virtual environment with some command line interface arguments.

Parameter:

• argument– command line arguments

• options– Passing in aVirtualEnvOptionsThe object allows parsed options to be returned.

• setup_logging–TRUEwhen configuring registry handlers,INCORRECTuse already registered handlers

• env– Environment variables to use

Returns:

the session object of creation (its structure is experimental for now and may change in the short term)

virtual environmentsession_via_cli(argument,options=none,setup_logging=TRUE,env=none)#

Create a virtualenv session (same as cli_run but this doesn't do the creation). Use it when you just want to see what the virtual environment would look like, but you don't really want to create it.

Parameter:

• argument– command line arguments

• options– Passing in aVirtualEnvOptionsThe object allows parsed options to be returned.

• setup_logging–TRUEwhen configuring registry handlers,INCORRECTuse already registered handlers

• env– Environment variables to use

Returns:

the session object of creation (its structure is experimental for now and may change in the short term)

Class virtualenv.run.session.meeting(detail,application data,Interpreter,Creator,seeder,activators)#

Represents a virtual environment creation session.

Property detail#

The verbosity of the race.

Property Interpreter#

Create a virtual environment based on this reference interpreter

Property Creator#

The creator used to create the virtual environment (must be supported by the interpreter)

Property seeder#

The mechanism used to deploy the seed packages (pip, setuptools, wheel)

Property activators#

Triggers used to generate activation scripts