Skip to main content

Status and License

virtualenv is intended (when complete) to be a successor to workingenv, and an extension of virtual-python.

It is written by Ian Bicking, and sponsored by the Open Planning Project.

It is licensed under an MIT-style permissive license.

What It Does

virtualenv is a tool to create isolated Python environments.

The basic problem being addressed is one of dependencies and versions, and indirectly permissions. Imagine you have an application that needs version 1 of LibFoo, but another application requires version 2. How can you use both these applications? If you install everything into /usr/lib/python2.4/site-packages (or whatever your platform’s standard location is), it’s easy to end up in a situation where you unintentionally upgrade an application that shouldn’t be upgraded.

Or more generally, what if you want to install an application and leave it be? If an application works, any change in its libraries or the versions of those libraries can break the application.

Also, what if you can’t install packages into the global site-packages directory? For instance, on a shared host.

In all these cases, virtualenv can help you. It creates an environment that has its own installation directories, that doesn’t share libraries with other virtualenv environments (and optionally doesn’t use the globally installed libraries either).

The basic usage is:

$ python virtualenv.py ENV

This creates ENV/lib/python2.4/site-packages (or ENV/lib/python2.5/site-packages on Python 2.5, etc), where any libraries you install will go. It also creates ENV/bin/python, which is a Python interpreter that uses this environment. Anytime you use that interpreter (including when a script has #!/path/to/ENV/bin/python in it) the libraries in that environment will be used.

It also installs Setuptools for you, and if you use ENV/bin/easy_install the packages will be installed into the environment.

Creating Your Own Bootstrap Scripts

While this creates an environment, it doesn’t put anything into the environment. Developers may find it useful to distribute a script that sets up a particular environment, for example a script that installs a particular web application.

To create a script like this, call virtualenv.create_bootstrap_script(extra_text), and write the result to your new bootstrapping script. Here’s the documentation from the docstring:

Creates a bootstrap script, which is like this script but with extend_parser, adjust_options, and after_install hooks.

This returns a string that (written to disk of course) can be used as a bootstrap script with your own customizations. The script will be the standard virtualenv.py script, with your extra text added (your extra text should be Python code).

If you include these functions, they will be called:

extend_parser(optparse_parser):

You can add or remove options from the parser here.

adjust_options(options, args):

You can change options here, or change the args (if you accept different kinds of arguments, be sure you modify args so it is only [DEST_DIR]).

after_install(options, home_dir):

After everything is installed, this function is called. This is probably the function you are most likely to use. An example would be:

def after_install(options, home_dir):
    subprocess.call([join(home_dir, 'bin', 'easy_install'),
                     'MyPackage'])
    subprocess.call([join(home_dir, 'bin', 'my-package-script'),
                     'setup', home_dir])

This example immediately installs a package, and runs a setup script from that package.

Bootstrap Example

Here’s a more concrete example of how you could use this:

import virtualenv, textwrap
output = virtualenv.create_bootstrap_script(textwrap.dedent("""
import os, subprocess
def after_install(options, home_dir):
    etc = join(home_dir, 'etc')
    if not os.path.exists(etc):
        os.makedirs(etc)
    subprocess.call([join(home_dir, 'bin', 'easy_install'),
                     'BlogApplication'])
    subprocess.call([join(home_dir, 'bin', 'paster'),
                     'make-config', 'BlogApplication',
                     join(etc, 'blog.ini')])
    subprocess.call([join(home_dir, 'bin', 'paster'),
                     'setup-app', join(etc, 'blog.ini')])
"""))
f = open('blog-bootstrap.py', 'w').write(output)

Compare & Contrast with Alternatives

There are several alternatives that create isolated environments:

  • workingenv (which I do not suggest you use anymore if virtualenv works on your platform) is the predecessor to this library. It used the main Python interpreter, but relied on setting $PYTHONPATH to activate the environment. This causes problems when running Python scripts that aren’t part of the environment (e.g., a globally installed hg or bzr). It also conflicted a lot with Setuptools.

  • virtual-python is also a predecessor to this library. It uses only symlinks, so it couldn’t work on Windows. It also symlinks over the entire standard library and global site-packages. As a result, it won’t see new additions to the global site-packages.

    This script only symlinks a small portion of the standard library into the environment, and so Windows it is feasible to simply copy these files over. Also, it creates a new/empty site-packages and also adds the global site-packages to the path, so updates are tracked separately. This script also installs Setuptools automatically, saving a step and avoiding the need for network access.

  • zc.buildout doesn’t create an isolated Python environment in the same style, but achieves similar results through a declarative config file that sets up scripts with very particular packages. As a declarative system, it is somewhat easier to repeat and manage, but more difficult to experiment with. zc.buildout includes the ability to setup non-Python systems (e.g., a database server or an Apache instance).

I strongly recommend anyone doing application development or deployment use one of these tools.

Changes & News

0.8.3

  • Added support for Windows.

0.8.2

  • Give a better warning if you are on an unsupported platform (Mac Framework Pythons, and Windows).

  • Give error about running while inside a workingenv.

  • Give better error message about Python 2.3.

0.8.1

Fixed packaging of the library.

0.8

Initial release. Everything is changed and new!

Metadata

Release files for virtualenv 0.8.3

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for virtualenv 0.8.3
File Size Uploaded Provenance Actions
virtualenv-0.8.3.tar.gz 671.1 kB Without provenance Details for virtualenv-0.8.3.tar.gz

Built distributions (wheels)

Table of built distributions (wheels) for virtualenv 0.8.3
File Interpreter ABI Platform Actions
virtualenv-0.8.3-py2.5.egg Legacy Egg format - - Details for virtualenv-0.8.3-py2.5.egg
virtualenv-0.8.3-py2.4.egg Legacy Egg format - - Details for virtualenv-0.8.3-py2.4.egg

Total release size: 1.4 MB

Release files / virtualenv-0.8.3.tar.gz

Download URL virtualenv-0.8.3.tar.gz
Size 671.1 kB
Tags Source
SHA-256 checksum
How to use checksums
66a32465bc59f98c5c4518386fe1ed3c524ee1b10aef33fdb3bfaf2c33003f56
BLAKE2b-256 checksum
How to use checksums
919e2356ac78bfa8b8a8b5afdd466fbb42128e87affa34e04f73a304ce9ca6cd
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No

Release files / virtualenv-0.8.3-py2.5.egg

Download URL virtualenv-0.8.3-py2.5.egg
Size 352.9 kB
Tags Egg
SHA-256 checksum
How to use checksums
48b67b74d4be30ec86966b90fedc4daae65a16aa90716a7ea9df88a1ecf1e1ad
BLAKE2b-256 checksum
How to use checksums
83efb1afc523162267d46676bb2a0a2a7add61b13b99d91e806b2c9551710573
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No

Release files / virtualenv-0.8.3-py2.4.egg

Download URL virtualenv-0.8.3-py2.4.egg
Size 357.2 kB
Tags Egg
SHA-256 checksum
How to use checksums
6752c3e44665deb509d7165f9548035b57f10107faa3aea137088e0bc0878cd3
BLAKE2b-256 checksum
How to use checksums
9d59bb0252b659e3cacda7b331a22f33960556ce90706f445e77492048e7f29f
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No

Security for virtualenv 0.8.3

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

No provenance found

None of the files in this release were uploaded with provenance metadata.

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Release history Release notifications | RSS feed

This release

0.8.3 This release

3 release files No provenance

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page