User Guide - virtualenv (2023)


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:

    • 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).


As described above, virtual environments usually just borrow things from the Python system, they don't contain all the data from the Python system. The python executable version is coded in the python exe itself. So when you upgrade your system to Python, your virtual environment will still report the pre-upgrade version, even though all additional content (standard library, binary libraries, etc.) other than the executable is now of the new version.

Barring major incompatibilities (they rarely happen), the virtual environment will still work, but other than the content embedded in the Python executable, it behaves like the updated version. If Python from a virtual environment is specified as the target Python interpreter, we create virtual environments that conform to the new version of Python on the system, not the version reported by the virtual environment.


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).


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.


To install a seed package viaNuggetoapplication dataThe virtualenv method needs to acquire a wheel from the destination package. These wheels can be purchased in a number of places, as follows:

  • virtual environmentcomes with a set of inlays out of the boxWheelsfor the three seed packets (Nugget,configuration tools,Rad). These are packaged with the virtualenv source files and only change when virtualenv is updated. Different versions of python require different versions of it, and since virtualenv supports a wide range of python versions, the number of built-in wheels is greater than 3. Whenever newer versions of these built-in packages are released upstreamvirtual environmentproject updates them and creates a new version. Therefore, the periodic update of virtualenv also updates the version of the seed packages.

  • However, end users may not be able to update virtualenv at the same rate that we do with new versions. Thus, a user can request to update the list of embedded wheels by calling virtualenv with theUpdate-Embed-RäderFlag. If the operation is manually triggered in this way, subsequent executions of virtualenv will always use the update embedding wheels.

    The process can also be automatically triggered as a background process when virtualenv is called if no such update has been done in the last 14 days. The auto-updated wheel will only be used if it has been released for more than 28 days and the auto-update completed at least one hour ago:

    • the 28-day period must ensure that end users do not automatically apply versions that contain known bugs,

    • The one hour period after the completion of the automatic update is implemented so that the continuous integration services do not start using a new version built in the middle.

    The automatic behavior can be disabled by using theno regular updatesIndicator/setting option. To get the release date of a package, virtualenv runs:

    • look for<Verteilung>/json(main source of truth),

    • Save the date the version was first discovered and wait for 28 days to pass.

  • Users can specify a set of local roads that contain additional wheels using theextra-suchverzCommand line argument flag.

When searching for a wheel to use, virtualenv performs the search in the following order:

  • embedded wheels,

  • improved embedded wheels,

  • additional search directory

The grouped wheels are the previous three together. If neither location contains the requested wheel version ordescargaroption is usedNuggetdownload to load the latest available version of the index server.

Embed wheels for distributions#

Custom distributions often want to use their own versions of the wheel to distribute to PyPi instead of the virtualenv versions. The reason for this is to try to keep the system versions of these packages in sync with whatvirtualenv. In such cases, you should patch the modulevirtualenv.seed.wheels.embed, make sure the function is implementedget_embed_wheel(which returns the wheel for use in a distro/python version). HeBUNDLE_FOLDER,BUNDLE_SUPPORTYmaximumVariables are needed if you want to use the virtualenv test suite for validation.

Also, they might want to disable the regular update by patching thatvirtualenv.seed.embed.base_embed.PERIODIC_UPDATE_ON_BY_DEFAULTAINCORRECTand let the system update mechanism handle this. Note that in this case the user can still request an update to the built-in wheels by calling virtualenv viaUpdate-Embed-Räder, but it no longer happens automatically and doesn't change the wheels provided by the operating system.


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:



If you use Powershell, theActivateThe script is subject toExecution Policieson system By default, Windows 7 and later, the system execution policy is set toRestricted, which means there are no scripts like thatActivateScripts can be executed.

However, that can't stop us from slightly modifying it to make it work. You can relax the system execution policy to allow execution of local scripts without code signature verification using:

Establecer-ExecutionPolicy RemoteSigned

From theactivate.ps1The script is generated locally for each virtual environment, it is not considered a remote script, and can then be executed.

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.

  • argument– command line arguments

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

  • setup_loggingTRUEwhen configuring registry handlers,INCORRECTuse already registered handlers

  • env– Environment variables to use


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.

  • argument– command line arguments

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

  • setup_loggingTRUEwhen configuring registry handlers,INCORRECTuse already registered handlers

  • env– Environment variables to use


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

Class,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

Top Articles
Latest Posts
Article information

Author: Tyson Zemlak

Last Updated: 03/21/2023

Views: 6475

Rating: 4.2 / 5 (63 voted)

Reviews: 94% of readers found this page helpful

Author information

Name: Tyson Zemlak

Birthday: 1992-03-17

Address: Apt. 662 96191 Quigley Dam, Kubview, MA 42013

Phone: +441678032891

Job: Community-Services Orchestrator

Hobby: Coffee roasting, Calligraphy, Metalworking, Fashion, Vehicle restoration, Shopping, Photography

Introduction: My name is Tyson Zemlak, I am a excited, light, sparkling, super, open, fair, magnificent person who loves writing and wants to share my knowledge and understanding with you.