virtualenv Documentation

File: README.md Copy Chapter

virtualenv

A tool for creating isolated virtual python environments.

• Installation
• Documentation
• Changelog
• Issues
• PyPI
• Github

Code of Conduct Copy Chapter

Everyone interacting in the virtualenv project's codebases, issue trackers, chat rooms, and mailing lists is expected to
follow the PSF Code of Conduct.

File: docs/changelog/examples.rst Copy Chapter

.. examples for changelog entries adding to your Pull Requests

file 544.doc.rst:

::

explain everything much better - by :user:`passionate_technicalwriter`.

file 544.feature.rst:

::

``tox --version`` now shows information about all registered plugins - by :user:`obestwalter`.

file 571.bugfix.rst:

::

``skip_install`` overrides ``usedevelop`` (``usedevelop`` is an option to choose the
installation type if the package is installed and ``skip_install`` determines if it should be
installed at all) - by :user:`ferdonline`.

.. see pyproject.toml for all available categories

File: docs/development.rst Copy Chapter

#############
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 <https://github.com/pypa/virtualenv/issues/new?title=Trouble+with+development+environment>_ 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 <https://github.com/pypa/virtualenv>_. You can use git to clone the
  .. code-block:: console

  text Copy

  git clone https://github.com/pypa/virtualenv
  cd virtualenv

• Python interpreter: We recommend using CPython. You can use this guide <https://realpython.com/installing-python/>_ to set it up.

• :pypi:tox: to automatically get the projects development dependencies and run the test suite. We recommend
  installing it using pipx <https://pipxproject.github.io/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

.. code-block:: console

tox -e dev
.tox/dev/bin/virtualenv  # on Linux
.tox/dev/Scripts/virtualenv  # on Windows

Running tests

virtualenv's tests are written using the :pypi:pytest test framework. :pypi:tox is used to automate the setup and
execution of virtualenv's tests.

To run tests locally execute:

.. code-block:: console

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: py314, 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 <https://docs.pytest.org/en/latest/usage.html#specifying-tests-selecting-tests>_. As an example, you
can select tests using the various ways that pytest provides:

.. code-block:: console

# 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 :pypi: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:

.. code-block:: console

tox -e fix

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

Type checking

virtualenv ships a :PEP:561 py.typed marker and has comprehensive type annotations across the entire codebase.
This means downstream consumers and type checkers automatically recognize virtualenv as an inline-typed package.

All new code must include complete type annotations for function parameters and return types. To verify annotations
locally, run:

.. code-block:: console

tox -e type

This uses ty <https://docs.astral.sh/ty/>_ (Astral's Rust-based type checker) to validate annotations against Python
3.14. A second environment checks compatibility with the minimum supported version:

.. code-block:: console

tox -e type-3.9

Both environments validate that annotations are consistent and correct.

Annotation guidelines Copy Chapter

• Use from __future__ import annotations at the top of every module (enforced by ruff's required-imports
  setting).
• Place imports that are only needed for type checking inside an if TYPE_CHECKING: block to avoid runtime overhead.
• Ruff's ANN rules are enabled. ANN401 (typing.Any) is suppressed on a case-by-case basis with inline # noqa: ANN401 comments where Any is genuinely required (e.g. serialization, dynamic dispatch).
• Prefer concrete types over Any. Use Union / | for nullable or multi-type parameters.
• When a type error is genuinely unfixable (e.g. third-party library limitations), suppress it with an inline # ty: ignore[rule-name] comment and a brief justification.

Building documentation

virtualenv's documentation is built using :pypi:Sphinx. The documentation is written in reStructuredText. To build it
locally, run:

.. code-block:: console

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.

Logo and branding

Two logo files live in docs/_static and serve different roles, so both are kept on purpose:

• virtualenv.png is the official logo — the snakes wrapped around a terminal, with the wordmark. It is the site logo
  (light_logo/dark_logo in docs/conf.py) and the one to use wherever a virtualenv logo is needed.
• virtualenv.svg is a simplified mark used only as the browser favicon (html_favicon), where the detailed PNG
  would be illegible at 16×16. It is not a vector copy of the PNG.

Release

virtualenv's release schedule is tied to pip and setuptools. 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).

Performing a release Copy Chapter

A full release publishes to PyPI <https://pypi.org/project/virtualenv/>, creates a GitHub Release <https://github.com/pypa/virtualenv/releases> with the zipapp attached, and updates get-virtualenv <https://github.com/pypa/get-virtualenv>_ so that https://bootstrap.pypa.io/virtualenv.pyz serves the new version.

Version bumping
^^^^^^^^^^^^^^^

The --version argument to tox r -e release controls the version. It defaults to auto, which inspects the
docs/changelog directory: if any *.feature.rst or *.removal.rst fragments exist, the minor version is
bumped, otherwise the patch version is bumped. You can also pass major, minor, or patch explicitly.

Both methods produce identical results: a release commit and tag on main. Pushing the tag triggers the Release workflow <https://github.com/pypa/virtualenv/actions/workflows/release.yaml>_ which builds the sdist, wheel, and
zipapp, publishes to PyPI via trusted publisher, creates a GitHub Release <https://github.com/pypa/virtualenv/releases>_ with the zipapp attached, and updates get-virtualenv <https://github.com/pypa/get-virtualenv>_. If publish fails, a rollback job automatically reverts everything.

Via GitHub Actions (recommended)

1. Go to the Pre-release workflow <https://github.com/pypa/virtualenv/actions/workflows/pre-release.yaml>_ on GitHub.
2. Click Run workflow and select the bump type (auto, major, minor, or patch).

Locally

.. code-block:: console

tox r -e release

Pass --version to override the default auto behavior (e.g. --version minor).

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 :ref:supports <compatibility-requirements> 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 <https://www.kessler.de/prd/smartbear/BestPracticesForPeerCodeReview.pdf>_ 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 GitHub Actions <https://docs.github.com/en/actions>_
(configured by .github/workflows/check.yaml 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 :pypi: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 :pypi:towncrier will deduplicate them.

Contents of a NEWS entry Copy Chapter

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 Copy Chapter

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

.. _current-maintainers:

Current maintainers Copy Chapter

• :user:Bernát Gábor <gaborbernat>
• :user:Rahul Devikar <rahuldevikar>

Previous maintainers Copy Chapter

• :user:Paul Moore
• :user:Ian Bicking
• :user:Donald Stufft <dstufft>

File: docs/index.rst Copy Chapter

############
virtualenv
############

.. image:: https://img.shields.io/pypi/v/virtualenv?style=flat-square
:target: https://pypi.org/project/virtualenv/#history
:alt: Latest version on PyPI

.. image:: https://img.shields.io/pypi/implementation/virtualenv?style=flat-square
:alt: PyPI - Implementation

.. image:: https://img.shields.io/pypi/pyversions/virtualenv?style=flat-square
:alt: PyPI - Python Version

.. image:: https://readthedocs.org/projects/virtualenv/badge/?version=latest&style=flat-square
:target: https://virtualenv.pypa.io
:alt: Documentation status

.. image:: https://img.shields.io/discord/803025117553754132
:target: https://discord.gg/pypa
:alt: Discord

.. image:: https://img.shields.io/pypi/dm/virtualenv?style=flat-square
:target: https://pypistats.org/packages/virtualenv
:alt: PyPI - Downloads

.. image:: https://img.shields.io/pypi/l/virtualenv?style=flat-square
:target: https://opensource.org/licenses/MIT
:alt: PyPI - License

.. image:: https://img.shields.io/github/issues/pypa/virtualenv?style=flat-square
:target: https://github.com/pypa/virtualenv/issues
:alt: Open issues

.. image:: https://img.shields.io/github/issues-pr/pypa/virtualenv?style=flat-square
:target: https://github.com/pypa/virtualenv/pulls
:alt: Open pull requests

.. image:: https://img.shields.io/github/stars/pypa/virtualenv?style=flat-square
:target: https://pypistats.org/packages/virtualenv
:alt: Package popularity

virtualenv is a tool to create isolated Python environments. Since Python 3.3, a subset of it has been integrated
into the standard library under the venv module. For how virtualenv compares to the stdlib venv module, see
:doc:explanation.

Quick navigation

Tutorials - Learn by doing

• :doc:tutorial/getting-started — Create your first virtual environment and learn the basic workflow

How-to guides - Solve specific problems

• :doc:how-to/install — Install virtualenv on your system
• :doc:how-to/usage — Select Python versions, activate environments, configure defaults, and use from Python code

Reference - Technical information

• :doc:reference/compatibility — Supported Python versions and operating systems
• :doc:reference/cli — Command line options and flags
• :doc:reference/api — Programmatic Python API reference

Explanation - Understand the concepts

• :doc:explanation — How virtualenv works under the hood and why it exists

Extensions

• :doc:plugin/index — Extend virtualenv with custom creators, seeders, and activators

Related projects

Several tools build on virtualenv to provide higher-level workflows:

• virtualenvwrapper <https://virtualenvwrapper.readthedocs.io/en/latest/>_ — Shell wrapper for creating and managing
  multiple virtualenvs
• pew <https://github.com/berdario/pew>_ — Python Env Wrapper, a set of commands to manage multiple virtual
  environments
• tox <https://tox.readthedocs.io/en/latest/>_ — Automate testing across multiple Python versions
• nox <https://nox.thea.codes/en/stable/>_ — Flexible test automation in Python

External resources

Learn more about virtualenv from these community resources:

• Corey Schafer's virtualenv tutorial <https://www.youtube.com/watch?v=N5vscPTWKOk>_ — Video walkthrough for beginners
• Bernat Gabor's status quo <https://www.youtube.com/watch?v=o1Vue9CWRxU>_ — Talk about the current state of Python
  packaging
• Carl Meyer's reverse-engineering <http://pyvideo.org/video/568/reverse-engineering-ian-bicking--39-s-brain--insi>_ —
  Deep dive into how virtualenv works internally

.. toctree::
:hidden:
:caption: Tutorial

tutorial/getting-started

.. toctree::
:hidden:
:caption: How-to guides

how-to/install
how-to/usage

.. toctree::
:hidden:
:caption: Reference

reference/compatibility
reference/cli
reference/api

.. toctree::
:hidden:
:caption: Explanation

explanation

.. toctree::
:hidden:
:caption: Extend

plugin/index

.. toctree::
:hidden:
:caption: Project

development
changelog