Installation

via pipx

virtualenv is a CLI tool that needs a Python interpreter to run. If you already have a Python 3.5+ interpreter the best is to use pipx to install virtualenv into an isolated environment. This has the added benefit that later you’ll be able to upgrade virtualenv without affecting other parts of the system.

pipx install virtualenv
virtualenv --help

via pip

Alternatively you can install it within the global Python interpreter itself (perhaps as a user package via the --user flag). Be cautious if you are using a python install that is managed by your operating system or another package manager. pip might not coordinate with those tools, and may leave your system in an inconsistent state. Note, if you go down this path you need to ensure pip is new enough per the subsections below:

python -m pip install --user virtualenv
python -m virtualenv --help

wheel

Installing virtualenv via a wheel (default with pip) requires an installer that can understand the python-requires tag (see PEP-503), with pip this is version 9.0.0 (released 2016 November). Furthermore, in case you’re not installing it via the PyPi you need to be using a mirror that correctly forwards the python-requires tag (notably the OpenStack mirrors don’t do this, or older devpi versions - added with version 4.7.0).

sdist

When installing via a source distribution you need an installer that handles the PEP-517 specification. In case of pip this is version 18.0.0 or later (released on 2018 July). If you cannot upgrade your pip to support this you need to ensure that the build requirements from pyproject.toml are satisfied before triggering the install.

via zipapp

You can use virtualenv without installing it too. We publish a Python zipapp, you can just download this from https://bootstrap.pypa.io/virtualenv.pyz and invoke this package with a python interpreter:

python virtualenv.pyz --help

The root level zipapp is always the current latest release. To get the last supported zipapp against a given python minor release use the link https://bootstrap.pypa.io/virtualenv/x.y/virtualenv.pyz, e.g. for the last virtualenv supporting Python 2.7 use https://bootstrap.pypa.io/virtualenv/2.7/virtualenv.pyz.

If you are looking for past version of virtualenv.pyz they are available here: https://github.com/pypa/get-virtualenv/blob/<virtualenv version>/public/<python version>/virtualenv.pyz?raw=true

via setup.py

We don’t recommend and officially support this method. One should prefer using an installer that supports PEP-517 interface, such as pip 19.0.0 or later. That being said you might be able to still install a package via this method if you satisfy build dependencies before calling the install command (as described under sdist).

latest unreleased

Installing an unreleased version is discouraged and should be only done for testing purposes. If you do so you’ll need a pip version of at least 18.0.0 and use the following command:

pip install git+https://github.com/pypa/virtualenv.git@main

Python and OS Compatibility

virtualenv works with the following Python interpreter implementations:

  • CPython versions 2.7, 3.5, 3.6, 3.7, 3.8, 3.9, 3.10

  • PyPy 2.7 and 3.5+.

This means virtualenv works on the latest patch version of each of these minor versions. Previous patch versions are supported on a best effort approach.

CPython is shipped in multiple forms, and each OS repackages it, often applying some customization along the way. Therefore we cannot say universally that we support all platforms, but rather specify some we test against. In case of ones not specified here the support is unknown, though likely will work. If you find some cases please open a feature request on our issue tracker. Note, as of 20.16.0 we no longer support running under Python less than 3.6, however we still support creating environments for 2.7 and 3.5.

Linux

  • installations from python.org

  • Ubuntu 16.04+ (both upstream and deadsnakes builds)

  • Fedora

  • RHEL and CentOS

  • OpenSuse

  • Arch Linux

macOS

In case of macOS we support:

  • installations from python.org

  • python versions installed via brew (both older python2.7 and python3)

  • Python 3 part of XCode (Python framework - /Library/Frameworks/Python3.framework/)

  • Python 2 part of the OS (/System/Library/Frameworks/Python.framework/Versions/)

Windows

Packaging variants

  • Normal variant (file structure as comes from python.org).

  • We support CPython 2 system installations that do not contain the python files for the standard library if the respective compiled files are present (e.g. only os.pyc, not os.py). This can be used by custom systems may want to maximize available storage or obfuscate source code by removing .py files.