neulab/tldr huggingface dataset:
• However, end users might not be able to upgrade virtualenv at the same speed as we do new releases. Therefore, a user might request to upgrade the list of embedded wheels by invoking virtualenv with the upgrade-embed-wheels flag. If the operation is triggered in such a manual way subsequent runs of virtualenv will always use the upgraded embed wheels.
The operation can trigger automatically too, as a background process upon invocation of virtualenv, if no such upgrade has been performed in the last 14 days. It will only start using automatically upgraded wheel if they have been released for more than 28 days, and the automatic upgrade finished at least an hour ago:
• the 28 days period should guarantee end users are not pulling in automatically releases that have known bugs within,
• the one hour period after the automatic upgrade finished is implemented so that continuous integration services do not start using a new embedded versions half way through.
The automatic behaviour might be disabled via the no-periodic-update configuration flag/option. To acquire the release date of a package virtualenv will perform the following:
• lookup https://pypi.org/pypi/<distribution>/json (primary truth source),
• save the date the version was first discovered, and wait until 28 days passed.
• Users can specify a set of local paths containing additional wheels by using the extra-search-dir command line argument flag.
When searching for a wheel to use virtualenv performs lookup in the following order:
• embedded wheels,
• upgraded embedded wheels,
• extra search dir.
Bundled wheels are all three above together. If neither of the locations contain the requested wheel version or download option is set will use pip download to load the latest version available from the index server.
Embed wheels for distributions Custom distributions often want to use their own set of wheel versions to distribute instead of the one virtualenv releases on PyPi. The reason for this is trying to keep the system versions of those packages in sync with what virtualenv uses. In such cases they should patch the module virtualenv.seed.wheels.embed, making sure to provide the function get_embed_wheel (which returns the wheel to use given a distribution/python version). The BUNDLE_FOLDER, BUNDLE_SUPPORT and MAX variables are needed if they want to use virtualenv's test suite to validate.
Furthermore, they might want to disable the periodic update by patching the virtualenv.seed.embed.base_embed.PERIODIC_UPDATE_ON_BY_DEFAULT to False, and letting the system update mechanism to handle this. Note in this case the user might still request an upgrade of the embedded wheels by invoking virtualenv via upgrade-embed-wheels, but no longer happens automatically, and will not alter the OS provided wheels.
Activators These are activation scripts that will mangle with your shell's settings to ensure that commands from within the python virtual environment take priority over your system paths. For example, if invoking pip from your shell returned the system python's pip before activation, once you do the activation this should refer to the virtual environments pip.  Note, though that all we do is change priority; so, if your virtual environments bin/Scripts folder does not contain some executable, this will still resolve to the same executable it would have resolved before the activation.
For a list of shells we provide activators see activators. The location of these is right alongside the python executables ( usually Scripts folder on Windows, bin on POSIX), and are named as activate (and some extension that's specific per activator; no extension is bash). You can invoke them, usually by source-ing (the source command might vary by shell - e.g. bash is .):
source bin/activate
This is all it does; it's purely a convenience of prepending the virtual environment's binary folder onto the PATH environment variable. Note you don't have to activate a virtual environment to use it. In this case though you would need to type out the path to the executables, rather than relying on your shell to resolve them to your virtual environment.
The activate script will also modify your shell prompt to indicate which environment is currently active. The script also provisions a deactivate command that will allow you to undo the operation:
NOTE: If using Powershell, the activate script is subject to the execution policies on the system. By default, Windows 7 and later, the system's execution policy is set to Restricted, meaning no scripts like the activate script are allowed to be executed.
However, that can't stop us from changing that slightly to allow it to be executed. You may relax the system execution policy to allow running of local scripts without verifying the code signature using the following:
Set-ExecutionPolicy RemoteSigned
Since the activate.ps1 script is generated locally for each virtualenv, it is not considered a remote script and can then be executed.
A longer explanation of this can be found within Allison Kaptur's 2013 blog post: There's no magic: virtualenv edition explains how virtualenv uses bash and Python and PATH and PYTHONHOME to isolate virtual environments' paths.
Programmatic API At the moment virtualenv offers only CLI level interface. If you want to trigger invocation of Python environments from within Python you should be using the virtualenv.cli_run method; this takes an args argument where you can pass the options the same way you would from the command line. The run will return a session object containing data about the created virtual environment.
from virtualenv import cli_run
cli_run(["venv"])
virtualenv.cli_run(args, options=None, setup_logging=True, env=None) Create a virtual environment given some command line interface arguments.
• args -- the command line arguments
• options -- passing in a VirtualEnvOptions object allows return of the parsed options
• setup_logging -- True if setup logging handlers, False to use handlers already registered
• env -- environment variables to use
Returns the session object of the creation (its structure for now is experimental and might change on short notice)
virtualenv.session_via_cli(args, options=None, setup_logging=True, env=None) Create a virtualenv session (same as cli_run, but this does not perform the creation). Use this if you just want to query what the virtual environment would look like, but not actually create it.
class virtualenv.run.session.Session(verbosity, app_data, interpreter, creator, seeder, activators) Represents a virtual environment creation session
property verbosity The verbosity of the run
property interpreter Create a virtual environment based on this reference interpreter
property creator The creator used to build the virtual environment (must be compatible with the interpreter)
property seeder The mechanism used to provide the seed packages (pip, setuptools, wheel)
property activators Activators used to generate activations scripts
CLI interface CLI flags virtualenv is primarily a command line application.
It modifies the environment variables in a shell to create an isolated Python environment, so you'll need to have a shell to run it. You can type in virtualenv (name of the application) followed by flags that control its behaviour. All options have sensible defaults, and there's one required argument: then name/path of the virtual environment to create. The default values for the command line options can be overridden via the Configuration file or Environment Variables. Environment variables takes priority over the configuration file values (--help will show if a default comes from the environment variable as the help message will end in this case with environment variables or the configuration file).
The options that can be passed to virtualenv, along with their default values and a short description are listed below.
virtualenv [OPTIONS]
┌────────────────┬───────────────────┬──────────────────────┐ │Named Arguments │                   │                      │ ├────────────────┼───────────────────┼──────────────────────┤ │                │                   │ display the version  │ │                │                   │ of the virtualenv    │ │                │                   │ package and its      │ │                │                   │ location, then exit  │ ├────────────────┼───────────────────┼──────────────────────┤ │                │ False             │ on failure also      │ │                │                   │ display the          │ │                │                   │ stacktrace internals │ │                │                   │ of virtualenv        │ ├────────────────┼───────────────────┼──────────────────────┤ │                │ False             │ use app data folder  │ │                │                   │ in read-only mode    │ │                │                   │ (write operations    │ │                │                   │ will fail with       │ │                │                   │ error)               │ ├────────────────┼───────────────────┼──────────────────────┤ │                │ platform specific │ a data folder used   │ │                │ application data  │ as cache by the      │ │                │ folder            │ virtualenv           │ ├────────────────┼───────────────────┼──────────────────────┤ │                │ False             │ start with empty app │ │                │                   │ data folder          │ ├────────────────┼───────────────────┼──────────────────────┤ │                │ False             │ trigger a manual     │ │                │                   │ update of the        │ │                │                   │ embedded wheels      │ └────────────────┴───────────────────┴──────────────────────┘
┌─────────────────────┬───┬────────────────────┐ │verbosity ⇒          │   │                    │ │verbosity = verbose  │   │                    │ │- quiet, default     │   │                    │ │INFO, mapping =>     │   │                    │ │CRITICAL=0, ERROR=1, │   │                    │ │WARNING=2, INFO=3,   │   │                    │ │DEBUG=4, NOTSET=5    │   │                    │ ├─────────────────────┼───┼────────────────────┤ │                     │ 2 │ increase verbosity │ ├─────────────────────┼───┼────────────────────┤ │                     │ 0 │ decrease verbosity │ └─────────────────────┴───┴────────────────────┘
discovery ┌──────────────────┬────────────────┬──────────────────────┐ │core ⇒ options    │                │                      │ │shared across all │                │                      │ │discovery         │                │                      │ ├──────────────────┼────────────────┼──────────────────────┤ │                  │ builtin        │ interpreter          │ │                  │                │ discovery method;    │ │                  │                │ choice of: builtin   │ └──────────────────┴────────────────┴──────────────────────┘
│                  │ the python     │ interpreter based on │ │                  │ executable     │ what to create       │ │                  │ virtualenv is  │ environment          │ │                  │ installed into │ (path/identifier) -  │ │                  │                │ by default use the   │ │                  │                │ interpreter where    │ │                  │                │ the tool is          │ │                  │                │ installed - first    │ │                  │                │ found wins           │ ├──────────────────┼────────────────┼──────────────────────┤ │                  │ []             │ try first these      │ │                  │                │ interpreters before  │ │                  │                │ starting the         │ │                  │                │ discovery            │ └──────────────────┴────────────────┴──────────────────────┘
┌───────────────────┬───────┬─────────────────────┐ │app-data ⇒ options │       │                     │ │specific to seeder │       │                     │ │app-data           │       │                     │ ├───────────────────┼───────┼─────────────────────┤ │                   │ False │  symlink the python │ │                   │       │ packages from the   │ │                   │       │ app-data folder     │ │                   │       │ (requires seed      │ │                   │       │ pip>=19.3)          │ └───────────────────┴───────┴─────────────────────┘
activators ┌──────────────────┬──────────────────────┬──────────────────────┐ │core ⇒ options    │                      │                      │ │shared across all │                      │                      │ │activators        │                      │                      │ ├──────────────────┼──────────────────────┼──────────────────────┤ │                  │ comma separated list │ activators to        │ │                  │ of activators        │ generate - default   │ │                  │ supported            │ is all supported;    │ │                  │                      │ choice of: bash,     │ │                  │                      │ batch, cshell, fish, │ │                  │                      │ nushell, powershell, │ │                  │                      │ python               │ ├──────────────────┼──────────────────────┼──────────────────────┤ │                  │                      │ provides an          │ │                  │                      │ alternative prompt   │ │                  │                      │ prefix for this      │ │                  │                      │ environment          │ └──────────────────┴──────────────────────┴──────────────────────┘
Defaults Configuration file virtualenv looks for a standard ini configuration file. The exact location depends on the operating system you're using, as determined by appdirs application configuration definition. The configuration file location is printed as at the end of the output when --help is passed.
The keys of the settings are derived from the command line option (left strip the - characters, and replace - with _). Where multiple flags are available first found wins (where order is as it shows up under the --help).
For example, --python would be specified as:
[virtualenv] python = /opt/python-3.8/bin/python
Options that take multiple values, like extra-search-dir can be specified as:
[virtualenv] extra_search_dir = /path/to/dists /path/to/other/dists
Environment Variables Default values may be also specified via environment variables. The keys of the settings are derived from the command line option (left strip the - characters, and replace - with _, finally capitalize the name). Where multiple flags are available first found wins (where order is as it shows up under the --help).
For example, to use a custom Python binary, instead of the one virtualenv is run with, you can set the environment variable VIRTUALENV_PYTHON like:
env VIRTUALENV_PYTHON=/opt/python-3.8/bin/python virtualenv
Where the option accepts multiple values, for example for python or extra-search-dir, the values can be separated either by literal newlines or commas. Newlines and commas can not be mixed and if both are present only the newline is used for separating values. Examples for multiple values:
env VIRTUALENV_PYTHON=/opt/python-3.8/bin/python,python3.8 virtualenv env VIRTUALENV_EXTRA_SEARCH_DIR=/path/to/dists\n/path/to/other/dists virtualenv
The equivalent CLI-flags based invocation for the above examples would be:
virtualenv --python=/opt/python-3.8/bin/python --python=python3.8 virtualenv --extra-search-dir=/path/to/dists --extra-search-dir=/path/to/other/dists
Extend functionality virtualenv allows one to extend the builtin functionality via a plugin system. To add a plugin you need to:
• write a python file containing the plugin code which follows our expected interface,
• package it as a python library,
• install it alongside the virtual environment.
WARNING: The public API of some of these components is still to be finalized, consider the current interface a beta one until we get some feedback on how well we planned ahead. We expect to do this by end of Q3 2020. Consider the class interface explained below as initial draft proposal. We reserve the right to change the API until then, however such changes will be communicated in a timely fashion, and you'll have time to migrate. Thank you for your understanding.
Python discovery The python discovery mechanism is a component that needs to answer the following answer: based on some type of user input give me a Python interpreter on the machine that matches that. The builtin interpreter tries to discover an installed Python interpreter (based on PEP-515 and PATH discovery) on the users machine where the user input is a python specification. An alternative such discovery mechanism for example would be to use the popular pyenv project to discover, and if not present install the requested Python interpreter. Python discovery mechanisms must be registered under key virtualenv.discovery, and the plugin must implement virtualenv.discovery.discover.Discover:
virtualenv.discovery = pyenv = virtualenv_pyenv.discovery:PyEnvDiscovery
class virtualenv.discovery.discover.Discover(options) Discover and provide the requested Python interpreter
Create a new discovery mechanism.
Parameters options -- the parsed options as defined within add_parser_arguments()
classmethod add_parser_arguments(parser) Add CLI arguments for this discovery mechanisms.
Parameters parser -- the CLI parser
abstract run() Discovers an interpreter.
Returns the interpreter ready to use for virtual environment creation
property interpreter
Returns the interpreter as returned by run(), cached
Creators Creators are what actually perform the creation of a virtual environment. The builtin virtual environment creators all achieve this by referencing a global install; but would be just as valid for a creator to install a brand new entire python under the target path; or one could add additional creators that can create virtual environments for other python implementations, such as IronPython. They must be registered under and entry point with key virtualenv.discovery , and the class must implement virtualenv.create.creator.Creator:
virtualenv.create = cpython3-posix = virtualenv.create.via_global_ref.builtin.cpython.cpython3:CPython3Posix
class virtualenv.create.creator.Creator(options, interpreter) A class that given a python Interpreter creates a virtual environment
Construct a new virtual environment creator.
• options -- the CLI option as parsed from add_parser_arguments()
• interpreter -- the interpreter to create virtual environment from
classmethod can_create(interpreter) Determine if we can create a virtual environment.
Parameters interpreter -- the interpreter in question
Returns None if we can't create, any other object otherwise that will be forwarded to add_parser_arguments()
classmethod add_parser_arguments(parser, interpreter, meta, app_data) Add CLI arguments for the creator.
• parser -- the CLI parser
• app_data -- the application data folder
• interpreter -- the interpreter we're asked to create virtual environment for
• meta -- value as returned by can_create()
abstract create() Perform the virtual environment creation.
setup_ignore_vcs() Generate ignore instructions for version control systems.
Seed mechanism Seeders are what given a virtual environment will install somehow some seed packages into it. They must be registered under and entry point with key virtualenv.seed , and the class must implement virtualenv.seed.seeder.Seeder:
virtualenv.seed = db = virtualenv.seed.fromDb:InstallFromDb
class virtualenv.seed.seeder.Seeder(options, enabled) A seeder will install some seed packages into a virtual environment.
• options -- the parsed options as defined within add_parser_arguments()
• enabled -- a flag weather the seeder is enabled or not
classmethod add_parser_arguments(parser, interpreter, app_data) Add CLI arguments for this seed mechanisms.
• app_data -- the CLI parser
• interpreter -- the interpreter this virtual environment is based of
abstract run(creator) Perform the seed operation.
Parameters creator -- the creator (based of virtualenv.create.creator.Creator) we used to create this         virtual environment
Activation scripts If you want add an activator for a new shell you can do this by implementing a new activator. They must be registered under and entry point with key virtualenv.activate , and the class must implement virtualenv.activation.activator.Activator:
virtualenv.activate = bash = virtualenv.activation.bash:BashActivator
class virtualenv.activation.activator.Activator(options) Generates an activate script for the virtual environment
Create a new activator generator.
classmethod supports(interpreter) Check if the activation script is supported in the given interpreter.
Parameters interpreter -- the interpreter we need to support
Returns True if supported, False otherwise
classmethod add_parser_arguments(parser, interpreter) Add CLI arguments for this activation script.
abstract generate(creator) Generate the activate script for the given creator.
Development Getting started virtualenv is a volunteer maintained open source project and we welcome contributions of all forms. The sections below will help you get started with development, testing, and documentation. We’re pleased that you are interested in working on virtualenv. This document is meant to get you setup to work on virtualenv and to act as a guide and reference to the development setup. If you face any issues during this process, please open an issue about it on the issue tracker.
Setup virtualenv is a command line application written in Python. To work on it, you'll need:
Source code: available on GitHub. You can use git to clone the repository:
git clone https://github.com/pypa/virtualenv cd virtualenv
• Python interpreter: We recommend using CPython. You can use this guide to set it up.
• tox: to automatically get the projects development dependencies and run the test suite. We recommend installing it using pipx.
Running from source tree The easiest way to do this is to generate the development tox environment, and then invoke virtualenv from under the .tox/dev folder
tox -e dev .tox/dev/bin/virtualenv  # on Linux .tox/dev/Scripts/virtualenv  # on Windows
Running tests virtualenv's tests are written using the pytest test framework. tox is used to automate the setup and execution of virtualenv's tests.
To run tests locally execute:
tox -e py
This will run the test suite for the same Python version as under which tox is installed. Alternatively you can specify a specific version of python by using the pyNN format, such as: py38, pypy3, etc.
tox has been configured to forward any additional arguments it is given to pytest.  This enables the use of pytest's rich CLI. As an example, you can select tests using the various ways that pytest provides:
# Using markers tox -e py -- -m "not slow" # Using keywords tox -e py -- -k "test_extra"
Some tests require additional dependencies to be run, such is the various shell activators (bash, fish, powershell, etc). These tests will automatically be skipped if these are not present, note however that in CI all tests are run; so even if all tests succeed locally for you, they may still fail in the CI.
Running linters virtualenv uses pre-commit for managing linting of the codebase. pre-commit performs various checks on all files in virtualenv and uses tools that help follow a consistent code style within the codebase. To use linters locally, run:
tox -e fix_lint
NOTE: Avoid using # noqa comments to suppress linter warnings - wherever possible, warnings should be fixed instead.  # noqa comments are reserved for rare cases where the recommended style causes severe readability problems.
Building documentation virtualenv's documentation is built using Sphinx. The documentation is written in reStructuredText. To build it locally, run:
tox -e docs
The built documentation can be found in the .tox/docs_out folder and may be viewed by opening index.html within that folder.
Release virtualenv's release schedule is tied to pip, setuptools and wheel. We bundle the latest version of these libraries so each time there's a new version of any of these, there will be a new virtualenv release shortly afterwards (we usually wait just a few days to avoid pulling in any broken releases).
Contributing Submitting pull requests Submit pull requests against the main branch, providing a good description of what you're doing and why. You must have legal permission to distribute any code you contribute to virtualenv and it must be available under the MIT License. Provide tests that cover your changes and run the tests locally first. virtualenv supports multiple Python versions and operating systems. Any pull request must consider and work on all these platforms.
Pull Requests should be small to facilitate review. Keep them self-contained, and limited in scope. Studies have shown that review quality falls off as patch size grows. Sometimes this will result in many small PRs to land a single large feature. In particular, pull requests must not be treated as "feature branches", with ongoing development work happening within the PR. Instead, the feature should be broken up into smaller, independent parts which can be reviewed and merged individually.
Additionally, avoid including "cosmetic" changes to code that is unrelated to your change, as these make reviewing the PR more difficult. Examples include re-flowing text in comments or documentation, or addition or removal of blank lines or whitespace within lines. Such changes can be made separately, as a "formatting cleanup" PR, if needed.
Automated testing All pull requests and merges to 'main' branch are tested using Azure Pipelines (configured by azure-pipelines.yml file at the root of the repository). You can find the status and results to the CI runs for your PR on GitHub's Web UI for the pull request. You can also find links to the CI services' pages for the specific builds in the form of "Details" links, in case the CI run fails and you wish to view the output.
To trigger CI to run again for a pull request, you can close and open the pull request or submit another change to the pull request. If needed, project maintainers can manually trigger a restart of a job/build.
NEWS entries The changelog.rst file is managed using towncrier and all non trivial changes must be accompanied by a news entry. To add an entry to the news file, first you need to have created an issue describing the change you want to make. A Pull Request itself may function as such, but it is preferred to have a dedicated issue (for example, in case the PR ends up rejected due to code quality reasons).
Once you have an issue or pull request, you take the number and you create a file inside of the docs/changelog directory named after that issue number with an extension of:
• feature.rst,
• bugfix.rst,
• doc.rst,
• removal.rst,
• misc.rst.
Thus if your issue or PR number is 1234 and this change is fixing a bug, then you would create a file docs/changelog/1234.bugfix.rst. PRs can span multiple categories by creating multiple files (for instance, if you added a feature and deprecated/removed the old feature at the same time, you would create docs/changelog/1234.bugfix.rst and docs/changelog/1234.remove.rst). Likewise if a PR touches multiple issues/PRs you may create a file for each of them with the same contents and towncrier will deduplicate them.
Contents of a NEWS entry The contents of this file are reStructuredText formatted text that will be used as the content of the news file entry.  You do not need to reference the issue or PR numbers here as towncrier will automatically add a reference to all of the affected issues when rendering the news file.
In order to maintain a consistent style in the changelog.rst file, it is preferred to keep the news entry to the point, in sentence case, shorter than 120 characters and in an imperative tone -- an entry should complete the sentence This change will …. In rare cases, where one line is not enough, use a summary line in an imperative tone followed by a blank line separating it from a description of the feature/change in one or more paragraphs, each wrapped at 120 characters. Remember that a news entry is meant for end users and should only contain details relevant to an end user.
Choosing the type of NEWS entry A trivial change is anything that does not warrant an entry in the news file. Some examples are: code refactors that don't change anything as far as the public is concerned, typo fixes, white space modification, etc. To mark a PR as trivial a contributor simply needs to add a randomly named, empty file to the news/ directory with the extension of .trivial.
Becoming a maintainer If you want to become an official maintainer, start by helping out. As a first step, we welcome you to triage issues on virtualenv's issue tracker. virtualenv maintainers provide triage abilities to contributors once they have been around for some time and contributed positively to the project. This is optional and highly recommended for becoming a virtualenv maintainer. Later, when you think you're ready, get in touch with one of the maintainers and they will initiate a vote among the existing maintainers.
NOTE: Upon becoming a maintainer, a person should be given access to various virtualenv-related tooling across multiple platforms. These are noted here for future reference by the maintainers:
• GitHub Push Access
• PyPI Publishing Access
• CI Administration capabilities
• ReadTheDocs Administration capabilities
Release History v20.8.0 (2021-09-16) • upgrade embedded setuptools to 58.0.4 from 57.4.0 and pip to 21.2.4 from 21.2.3
• Add nushell activation script
v20.7.2 (2021-08-10) Bugfixes - 20.7.2 • Upgrade embedded pip to 21.2.3 from 21.2.2 and wheel to 0.37.0 from 0.36.2 - by @gaborbernat. (#2168)
v20.7.1 (2021-08-09) Bugfixes - 20.7.1 • Fix unpacking dictionary items in PythonInfo.install_path (#2165)
v20.7.0 (2021-07-31) Bugfixes - 20.7.0 • upgrade embedded pip to 21.2.2 from 21.1.3 and setuptools to 57.4.0 from 57.1.0 - by @gaborbernat (#2159)
Deprecations and Removals - 20.7.0 • Removed xonsh activator due to this breaking fairly often the CI and lack of support from those packages maintainers, upstream is encouraged to continue supporting the project as a plugin  - by @gaborbernat. (‐ #2160)
v20.6.0 (2021-07-14) Features - 20.6.0 • Support Python interpreters without distutils (fallback to syconfig in these cases) - by @gaborbernat. (#1910)
v20.5.0 (2021-07-13) Features - 20.5.0 • Plugins now use 'selectable' entry points - by @jaraco. (#2093)
• add libffi-7.dll to the hard-coded list of dlls for PyPy (#2141)
• Use the better maintained platformdirs instead of appdirs - by @gaborbernat. (#2142)
Bugfixes - 20.5.0 • Bump pip the embedded pip 21.1.3 and setuptools to 57.1.0 - by @gaborbernat. (#2135)
Deprecations and Removals - 20.5.0 • Drop python 3.4 support as it has been over 2 years since EOL - by @gaborbernat. (#2141)
v20.4.7 (2021-05-24) Bugfixes - 20.4.7 • Upgrade embedded pip to 21.1.2 and setuptools to 57.0.0 - by @gaborbernat. (#2123)
v20.4.6 (2021-05-05) Bugfixes - 20.4.6 • Fix site.getsitepackages() broken on python2 on debian - by @freundTech. (#2105)
v20.4.5 (2021-05-05) Bugfixes - 20.4.5 • Bump pip to 21.1.1 from 21.0.1 - by @gaborbernat. (#2104)
• Fix site.getsitepackages() ignoring --system-site-packages on python2 - by @freundTech. (#2106)
v20.4.4 (2021-04-20) Bugfixes - 20.4.4 • Built in discovery class is always preferred over plugin supplied classes. (#2087)
• Upgrade embeded setuptools to 56.0.0 by @gaborbernat. (#2094)
v20.4.3 (2021-03-16) Bugfixes - 20.4.3 • Bump embeded setuptools from 52.0.0 to 54.1.2 - by @gaborbernat (#2069)
• Fix PyPy3 stdlib on Windows is incorrect - by @gaborbernat. (#2071)
v20.4.2 (2021-02-01) Bugfixes - 20.4.2 • Running virtualenv --upgrade-embed-wheels crashes - by @gaborbernat. (‐ #2058)
v20.4.1 (2021-01-31) Bugfixes - 20.4.1 • Bump embedded pip and setuptools packages to latest upstream supported (21.0.1 and 52.0.0) - by @gaborbernat. (#2060)
v20.4.0 (2021-01-19) Features - 20.4.0 • On the programmatic API allow passing in the environment variable dictionary to use, defaults to os.environ if not specified - by @gaborbernat. (#2054)
Bugfixes - 20.4.0 • Upgrade embedded setuptools to 51.3.3 from 51.1.2 - by @gaborbernat. (‐ #2055)
v20.3.1 (2021-01-13) Bugfixes - 20.3.1 • Bump embed pip to 20.3.3, setuptools to 51.1.1 and wheel to 0.36.2 - by @gaborbernat. (#2036)
• Allow unfunctioning of pydoc to fail freely so that virtualenvs can be activated under Zsh with set -e (since otherwise unset -f and unfunction exit with 1 if the function does not exist in Zsh) - by @d125q. (#2049)
• Drop cached python information if the system executable is no longer present (for example when the executable is a shim and the mapped executable is replaced - such is the case with pyenv) - by @gaborbernat. (#2050)
v20.3.0 (2021-01-10) Features - 20.3.0 • The builtin discovery takes now a --try-first-with argument and is first attempted as valid interpreters. One can use this to force discovery of a given python executable when the discovery order/mechanism raises errors - by @gaborbernat. (#2046)
Bugfixes - 20.3.0 • On Windows python 3.7+ distributions where the exe shim is missing fallback to the old ways - by @gaborbernat. (#1986)
• When discovering interpreters on Windows, via the PEP-514, prefer PythonCore releases over other ones. virtualenv is used via pip mostly by this distribution, so prefer it over other such as conda - by @gaborbernat. (#2046)
v20.2.2 (2020-12-07) Bugfixes - 20.2.2 • Bump pip to 20.3.1, setuptools to 51.0.0 and wheel to 0.36.1 - by @gaborbernat. (#2029)
v20.2.1 (2020-11-23) No significant changes.
v20.2.0 (2020-11-21) Features - 20.2.0 • Optionally skip VCS ignore directive for entire virtualenv directory, using option no-vcs-ignore, by default False. (#2003)
• Add --read-only-app-data option to allow for creation based on an existing app data cache which is non-writable. This may be useful (for example) to produce a docker image where the app-data is pre-populated.
ENV \ VIRTUALENV_OVERRIDE_APP_DATA=/opt/virtualenv/cache \ VIRTUALENV_SYMLINK_APP_DATA=1 RUN virtualenv venv && rm -rf venv ENV VIRTUALENV_READ_ONLY_APP_DATA=1 USER nobody # this virtualenv has symlinks into the read-only app-data cache RUN virtualenv /tmp/venv
Patch by @asottile. (#2009)
Bugfixes - 20.2.0 • Fix processing of the VIRTUALENV_PYTHON environment variable and make it multi-value as well (separated by comma) - by @pneff. (#1998)
v20.1.0 (2020-10-25) Features - 20.1.0 • The python specification can now take one or more values, first found is used to create the virtual environment - by @gaborbernat. (#1995)
v20.0.35 (2020-10-15) Bugfixes - 20.0.35 • Bump embedded setuptools from 50.3.0 to 50.3.1 - by @gaborbernat. (‐ #1982)
• After importing virtualenv passing cwd to a subprocess calls breaks with invalid directory - by @gaborbernat. (#1983)
v20.0.34 (2020-10-12) Bugfixes - 20.0.34 • Align with venv module when creating virtual environments with builtin creator on Windows 3.7 and later - by @gaborbernat. (#1782)
• Handle Cygwin path conversion in the activation script - by @davidcoghlan. (#1969)
v20.0.33 (2020-10-04) Bugfixes - 20.0.33 • Fix None type error in cygwin if POSIX path in dest - by @danyeaw. (‐ #1962)
• Fix Python 3.4 incompatibilities (added back to the CI) - by @gaborbernat. (#1963)
v20.0.32 (2020-10-01) Bugfixes - 20.0.32 • For activation scripts always use UNIX line endings (unless it's BATCH shell related) - by @saytosid. (#1818)
• Upgrade embedded pip to 20.2.1 and setuptools to 49.4.0 - by @gaborbernat. (#1918)
• Avoid spawning new windows when doing seed package upgrades in the background on Windows - by @gaborbernat. (#1928)
• Fix a bug that reading and writing on the same file may cause race on multiple processes. (#1938)
• Upgrade embedded setuptools to 50.2.0 and pip to 20.2.3 - by @gaborbernat. (#1939)
• Provide correct path for bash activator in cygwin or msys2 - by @danyeaw. (#1940)
• Relax importlib requirement to allow version<3 - by @usamasadiq (#1953)
• pth files were not processed on CPython2 if $PYTHONPATH was pointing to site-packages/ - by @navytux. (#1959) (#1960)
v20.0.31 (2020-08-17) Bugfixes - 20.0.31 • Upgrade embedded pip to 20.2.1, setuptools to 49.6.0 and wheel to 0.35.1  - by @gaborbernat. (#1918)
v20.0.30 (2020-08-04) Bugfixes - 20.0.30 • Upgrade pip to 20.2.1 and setuptools to 49.2.1 - by @gaborbernat. (‐ #1915)
v20.0.29 (2020-07-31) Bugfixes - 20.0.29 • Upgrade embedded pip from version 20.1.2 to 20.2 - by @gaborbernat. (‐ #1909)
v20.0.28 (2020-07-24) Bugfixes - 20.0.28 • Fix test suite failing if run from system Python - by @gaborbernat. (‐ #1882)
• Provide setup_logging flag to python API so that users can bypass logging handling if their application already performs this - by @gaborbernat. (#1896)
• Use \n instead if \r\n as line separator for report (because Python already performs this transformation automatically upon write to the logging pipe) - by @gaborbernat. (#1905)
v20.0.27 (2020-07-15) Bugfixes - 20.0.27 • No longer preimport threading to fix support for gpython and gevent - by @navytux. (#1897)
• Upgrade setuptools from 49.2.0 on Python 3.5+ - by @gaborbernat. (‐ #1898)
v20.0.26 (2020-07-07) Bugfixes - 20.0.26 • Bump dependency distutils >= 0.3.1 - by @gaborbernat. (#1880)
• Improve periodic update handling:
• better logging output while running and enable logging on background process call ( _VIRTUALENV_PERIODIC_UPDATE_INLINE may be used to debug behaviour inline)
• fallback to unverified context when querying the PyPi for release date,
• stop downloading wheels once we reach the embedded version,
by @gaborbernat. (#1883)
• Do not print error message if the application exists with SystemExit(0) - by @gaborbernat. (#1885)
• Upgrade embedded setuptools from 47.3.1 to 49.1.0 for Python 3.5+ - by @gaborbernat. (#1887)
v20.0.25 (2020-06-23) Bugfixes - 20.0.25 • Fix that when the app-data seeders image creation fails the exception is silently ignored. Avoid two virtual environment creations to step on each others toes by using a lock while creating the base images. By @gaborbernat. (#1869)
v20.0.24 (2020-06-22) Features - 20.0.24 • Ensure that the seeded packages do not get too much out of date:
• add a CLI flag that triggers upgrade of embedded wheels under upgrade-embed-wheels
• periodically (once every 14 days) upgrade the embedded wheels in a background process, and use them if they have been released for more than 28 days (can be disabled via no-periodic-update)
More details under wheels - by @gaborbernat. (#1821)
• Upgrade embed wheel content:
• ship wheels for Python 3.9 and 3.10
• upgrade setuptools for Python 3.5+ from 47.1.1 to 47.3.1
by @gaborbernat. (#1841)
• Display the installed seed package versions in the final summary output, for example:
created virtual environment CPython3.8.3.final.0-64 in 350ms creator CPython3Posix(dest=/x, clear=True, global=False) seeder FromAppData(download=False, pip=bundle, setuptools=bundle, wheel=bundle, via=copy, app_data_dir=/y/virtualenv) added seed packages: pip==20.1.1, setuptools==47.3.1, wheel==0.34.2
by @gaborbernat. (#1864)
Bugfixes - 20.0.24 • Do not generate/overwrite .gitignore if it already exists at destination path - by @gaborbernat. (#1862)
• Improve error message for no .dist-info inside the app-data copy seeder - by @gaborbernat. (#1867)
Improved Documentation - 20.0.24 • How seeding mechanisms discover (and automatically keep it up to date) wheels at wheels - by @gaborbernat. (#1821)
• How distributions should handle shipping their own embedded wheels at distribution_wheels - by @gaborbernat. (#1840)
v20.0.23 (2020-06-12) Bugfixes - 20.0.23 • Fix typo in setup.cfg - by @RowdyHowell. (#1857)
v20.0.22 (2020-06-12) Bugfixes - 20.0.22 • Relax importlib.resources requirement to also allow version 2 - by @asottile. (#1846)
• Upgrade embedded setuptools to 44.1.1 for python 2 and 47.1.1 for python3.5+ - by @gaborbernat. (#1855)
v20.0.21 (2020-05-20) Features - 20.0.21 • Generate ignore file for version control systems to avoid tracking virtual environments by default. Users should remove these files if still want to track. For now we support only git by @gaborbernat. (‐ #1806)
Bugfixes - 20.0.21 • Fix virtualenv fails sometimes when run concurrently, --clear-app-data conflicts with clear flag when abbreviation is turned on. To bypass this while allowing abbreviated flags on the command line we had to move it to reset-app-data - by @gaborbernat. (#1824)
• Upgrade embedded setuptools to 46.4.0 from 46.1.3 on Python 3.5+, and pip from 20.1 to 20.1.1 - by @gaborbernat. (#1827)
• Seeder pip now correctly handles --extra-search-dir - by @frenzymadness. (#1834)
v20.0.20 (2020-05-04) Bugfixes - 20.0.20 • Fix download fails with python 3.4 - by @gaborbernat. (#1809)
• Fixes older CPython2 versions use _get_makefile_filename instead of get_makefile_filename on sysconfig - by @ianw. (#1810)
• Fix download is True by default - by @gaborbernat. (#1813)
• Fail app-data seed operation when wheel download fails and better error message - by @gaborbernat. (#1814)
v20.0.19 (2020-05-03) Bugfixes - 20.0.19 • Fix generating a Python 2 environment from Python 3 creates invalid python activator - by @gaborbernat. (#1776)
• Fix pinning seed packages via app-data seeder raised Invalid Requirement - by @gaborbernat. (#1779)
• Do not stop interpreter discovery if we fail to find the system interpreter for a executable during discovery - by @gaborbernat. (‐ #1781)
• On CPython2 POSIX platforms ensure syconfig.get_makefile_filename exists within the virtual environment (this is used by some c-extension based libraries - e.g. numpy - for building) - by @gaborbernat. (#1783)
• Better handling of options copies and symlinks. Introduce priority of where the option is set to follow the order: CLI, env var, file, hardcoded. If both set at same level prefers copy over symlink. - by @gaborbernat. (#1784)
• Upgrade pip for Python 2.7 and 3.5+ from 20.0.2 to 20.1 - by @gaborbernat. (#1793)
• Fix CPython is not discovered from Windows registry, and discover pythons from Windows registry in decreasing order by version - by @gaborbernat. (#1796)
• Fix symlink detection for creators - by @asottile (#1803)
v20.0.18 (2020-04-16) Bugfixes - 20.0.18 • Importing setuptools before cli_run could cause our python information query to fail due to setuptools patching distutils.dist.Distribution - by @gaborbernat. (#1771)
v20.0.17 (2020-04-09) Features - 20.0.17 • Extend environment variables checked for configuration to also check aliases (e.g. setting either VIRTUALENV_COPIES or VIRTUALENV_ALWAYS_COPY will work) - by @gaborbernat. (#1763)
v20.0.16 (2020-04-04) Bugfixes - 20.0.16 • Allow seed wheel files inside the extra-search-dir folders that do not have Requires-Python metadata specified, these are considered compatible with all python versions - by @gaborbernat. (#1757)
v20.0.15 (2020-03-27) Features - 20.0.15 • Upgrade embedded setuptools to 46.1.3 from 46.1.1 - by @gaborbernat. (‐ #1752)
v20.0.14 (2020-03-25) Features - 20.0.14 • Remove __PYVENV_LAUNCHER__ on macOs for Python 3.7.(<8) and 3.8.(<3) on interpreter startup via pth file, this pulls in the upstream patch - by @gaborbernat. (#1704)
• Upgrade embedded setuptools for Python 3.5+ to 46.1.1, for Python 2.7 to 44.1.0 - by @gaborbernat. (#1745)
Bugfixes - 20.0.14 • Fix discovery of interpreter by name from PATH that does not match a spec format - by @gaborbernat. (#1746)
v20.0.13 (2020-03-19) Bugfixes - 20.0.13 • Do not fail when the pyc files is missing for the host Python 2 - by @gaborbernat. (#1738)
• Support broken Packaging pythons that put the include headers under distutils pattern rather than sysconfig one - by @gaborbernat. (#1739)
v20.0.12 (2020-03-19) Bugfixes - 20.0.12 • Fix relative path discovery of interpreters - by @gaborbernat. (#1734)
v20.0.11 (2020-03-18) Features - 20.0.11 • Improve error message when the host python does not satisfy invariants needed to create virtual environments (now we print which host files are incompatible/missing and for which creators when no supported creator can be matched, however we found creators that can describe the given Python interpreter - will still print no supported creator for Jython, however print exactly what host files do not allow creation of virtual environments in case of CPython/PyPy) - by @gaborbernat. (‐ #1716)
Bugfixes - 20.0.11 • Support Python 3 Framework distributed via XCode in macOs Catalina and before - by @gaborbernat. (#1663)
• Fix Windows Store Python support, do not allow creation via symlink as that's not going to work by design - by @gaborbernat. (#1709)
• Fix activate_this.py throws AttributeError on Windows when virtual environment was created via cross python mechanism - by @gaborbernat. (#1710)
• Fix --no-pip, --no-setuptools, --no-wheel not being respected - by @gaborbernat. (#1712)
• Allow missing .py files if a compiled .pyc version is available - by @tucked. (#1714)
• Do not fail if the distutils/setuptools patch happens on a C-extension loader (such as zipimporter on Python 3.7 or earlier) - by @gaborbernat. (#1715)
• Support Python 2 implementations that require the landmark files and site.py to be in platform standard library instead of the standard library path of the virtual environment (notably some RHEL ones, such as the Docker image amazonlinux:1) - by @gaborbernat. (#1719)
• Allow the test suite to pass even when called with the system Python - to help repackaging of the tool for Linux distributions -  by @gaborbernat. (#1721)
• Also generate pipx.y console script beside pip-x.y to be compatible with how pip installs itself - by @gaborbernat. (#1723)
• Automatically create the application data folder if it does not exists - by @gaborbernat. (#1728)
Improved Documentation - 20.0.11 • supports details now explicitly what Python installations we support - by @gaborbernat. (#1714)
v20.0.10 (2020-03-10) Bugfixes - 20.0.10 • Fix acquiring python information might be altered by distutils configuration files generating incorrect layout virtual environments - by @gaborbernat. (#1663)
• Upgrade embedded setuptools to 46.0.0 from 45.3.0 on Python 3.5+ - by @gaborbernat. (#1702)
Improved Documentation - 20.0.10 • Document requirements (pip + index server) when installing via pip under the installation section - by @gaborbernat. (#1618)
• Document installing from non PEP-518 systems - @gaborbernat. (#1619)
• Document installing latest unreleased version from Github - @gaborbernat. (#1620)
v20.0.9 (2020-03-08) Bugfixes - 20.0.9 • pythonw.exe works as python.exe on Windows - by @gaborbernat. (#1686)
• Handle legacy loaders for virtualenv import hooks used to patch distutils configuration load - by @gaborbernat. (#1690)
• Support for python 2 platforms that store landmark files in platstdlib over stdlib (e.g. RHEL) - by @gaborbernat. (#1694)
• Upgrade embedded setuptools to 45.3.0 from 45.2.0 for Python 3.5+  - by @gaborbernat. (#1699)
v20.0.8 (2020-03-04) Bugfixes - 20.0.8 • Having distutils configuration files that set prefix and install_scripts cause installation of packages in the wrong location - by @gaborbernat. (#1663)
• Fix PYTHONPATH being overridden on Python 2 — by @jd. (#1673)
• Fix list configuration value parsing from config file or environment variable - by @gaborbernat. (#1674)
• Fix Batch activation script shell prompt to display environment name by default - by @spetafree. (#1679)
• Fix startup on Python 2 is slower for virtualenv - this was due to setuptools calculating it's working set distribution - by @gaborbernat. (#1682)
• Fix entry points are not populated for editable installs on Python 2 due to setuptools working set being calculated before easy_install.pth runs - by @gaborbernat. (#1684)
• Fix attr: import fails for setuptools - by @gaborbernat. (#1685)
v20.0.7 (2020-02-26) Bugfixes - 20.0.7 • Disable distutils fixup for python 3 until pypa/pip #7778 is fixed and released - by @gaborbernat. (#1669)
v20.0.6 (2020-02-26) Bugfixes - 20.0.6 • Fix global site package always being added with bundled macOs python framework builds - by @gaborbernat. (#1561)
• Fix generated scripts use host version info rather than target - by @gaborbernat. (#1600)
• Fix circular prefix reference with single elements (accept these as if they were system executables, print a info about them referencing themselves) - by @gaborbernat. (#1632)
• Handle the case when the application data folder is read-only:
• the application data folder is now controllable via app-data,
• clear-app-data now cleans the entire application data folder, not just the app-data seeder path,