Using virtualenv¶

virtualenv is a tool for creating and activating isolated Python environments that allow installing and experimenting with Python packages without disrupting your production Python environment. When using commands such as python setup.py develop, for example, it is strongly recommended to do so within a virtualenv. This is generally preferable to installing a development version of Astropy into your system site-packages and having to keep track of whether or not your environment is in a “known good” configuration for production/science use.

Using a virtualenv is also a good way to try out new versions of software that you’re not actively doing development work on without disrupting your normal production environment.

We won’t provide a full tutorial on using virtualenv here — the virtualenv documentation linked to above is a better place to start. But here is a quick overview on how to set up a virtualenv for Astropy development with your default Python version:

Install virtualenv:

$ pip install virtualenv

or (on Debian/Ubuntu):

$ sudo apt-get install python-virtualenv

etc.

(Recommended) Create a root directory for all your virtualenvs under a path you have write access to. For example:
```
$ mkdir ~/.virtualenvs
```
Create the Astropy virtualenv:
```
$ virtualenv --distribute --system-site-packages ~/.virtualenvs/astropy-dev
```
The --system-site-packages option inherits all packages already installed in your system site-packages directory; this frees you from having to reinstall packages like Numpy and Scipy in the virtualenv. However, if you would like your virtualenv to use a development version of Numpy, for example, you can still install Numpy into the virtualenv and it will take precedence over the version installed in site-packages.
Activate the virtualenv:
```
$ source ~/.virtualenvs/astropy-dev/bin/activate
```
or if you’re using a csh-variant:
```
$ source ~/.virtualenvs/astropy-dev/bin/activate.csh
```
virtualenv works on Windows too — see the documentation for details.
If the virtualenv successfully activated its name should appear in your shell prompt:
```
(astropy-dev) $
```
The virtualenv can be disabled at any time by entering:
```
(astropy-dev) $ deactivate
```
Now as long as the virtualenv is activated, packages you install with pip, or by manually running python setup.py install will automatically install into your virtualenv instead of the system site-packages. Consider installing Astropy in develop mode into the virtualenv as described “Activate” the development version of astropy.

Using virtualenv with IPython¶

Note

As of IPython 0.13 this functionality is built into IPython and these steps are not necessary for IPython to recognize that it’s running with a virtualenv enabled.

Each virtualenv has its own bin/, and as IPython is written in pure Python one can always install IPython directly into a virtualenv. However, if you would rather not have to install IPython every time you create a virtualenv, it also suffices to make IPython virtualenv-aware.

Check to see if you already have an IPython profile in ~/.ipython/profile_default/; if not, create one:
```
$ ipython profile create
```

Edit ~/.ipython/profile_default/ipython_config.py and add the following to the end:

import os

execfile(os.path.join(os.environ['HOME'], '.ipython', 'virtualenv.py'))

Finally, create the ~/.ipython/virtualenv.py module:

import site
from os import environ
from os.path import join
from sys import version_info

if 'VIRTUAL_ENV' in environ:
    virtual_env = join(environ.get('VIRTUAL_ENV'),
                       'lib',
                       'python%d.%d' % version_info[:2],
                       'site-packages')
    site.addsitedir(virtual_env)
    print 'VIRTUAL_ENV ->', virtual_env
    del virtual_env
del site, environ, join, version_info

Now IPython will import all packages from your virtualenv where applicable.

Note

This is not magic. If you switch to a virtualenv that uses a different Python version from your main IPython installation this won’t help you — instead use the appropriate IPython installation for the Python version in question.

virtualenvwrapper¶

virtualenvwrapper is a set of enhancements to virtualenv mostly implemented through simple shell scripts and aliases. It automatically organizes all your virtualenvs under a single directory (as suggested above). To create a new virtualenv you can just use the 'mkvirtualenv <env_name>' command and it will automatically create a new virtualenv of that name in the default location.

To activate a virtualenv with virtualenvwrapper you don’t need to think about the environment’s location of the filesystem or which activate script to run. Simply run 'workon <env_name>'. You can also list all virtualenvs with lsvirtualenv. That just scratches the surface of the goodies included with virtualenvwrapper.

The one caveat is that it does not support csh-like shells. For csh-like shells there exists virtualenvwrapper-csh, which implements most of the virtualenvwrapper functionality and is otherwise compatible with the original. There also exists virtualenvwrapper-win, which ports virtualenvwrapper to Windows batch scripts.

venv¶

virtualenv is so commonly used in the Python development community that its functionality was finally added to the standard library in Python 3.3 under the name venv. venv has not gained wide use yet and is not explicitly supported by tools like virtualenvwrapper, but it is expected to see wider adoption in the future.

Navigation

Using virtualenv¶

Using virtualenv with IPython¶

virtualenvwrapper¶

venv¶