Python virtual environments

If you plan to do regular work on astropy you should do your development in a python virtual environment. Conceptually a virtual environment is a duplicate of the python environment you normally work in with as many (or as few) of the packages from your normal environment included in that virtual environment. It is sandboxed from your normal python environment in the sense that packages installed in the virtual environment do not affect your normal environment in any way.

Note

“Normal python environment” means whatever python you are using when you log in.

There are two options for using virtual environments; the choice of method is dictated by the python distribution you use:

• If you use the anaconda python distribution you must use conda to make and manage your virtual environments.

• If you use any other distribution you use virtualenvwrapper; you can not use conda. As the name suggests, virtualenvwrapper is a wrapper around virtualenv.

In both cases you will go through the same basic steps; the commands to accomplish each step are given for both conda and virtualenvwrapper:

• Set up for virtual environments

• List virtual environments

• Create a new virtual environment

• Activate a virtual environment

• Deactivate a virtual environment

• Delete a virtual environment

Note

• You cannot use virtualenvwrapper or virtualenv within anaconda.

• virtualenvwrapper works with bash and bash-like shells; see Using virtualenv for alternatives.

Set up for virtual environments

• virtualenvwrapper:

  • First, install virtualenvwrapper, which will also install virtualenv, with pip install virtualenvwrapper.

  • From the documentation for virtualenvwrapper, you also need to:

    export WORKON_HOME=$HOME/.virtualenvs
    export PROJECT_HOME=$HOME/
    source /usr/local/bin/virtualenvwrapper.sh
    

• conda: No setup is necessary beyond installing the anaconda python distribution.

List virtual environments

You do not need to list the virtual environments you have created before using them…but sooner or later you will forget what environments you have defined and this is the easy way to find out.

• virtualenvwrapper: workon

  • If this displays nothing you have no virtual environments

  • If this displays workon: command not found then you haven’t done the Set up for virtual environments; do that.

  • For more detailed information about installed environments use lsvirtualenv.

• conda: conda info -e

  • you will always have at least one environment, called root

  • your active environment is indicated by a *

Create a new virtual environment

This needs to be done once for each virtual environment you want. There is one important choice you need to make when you create a virtual environment: which, if any, of the packages installed in your normal python environment do you want in your virtual environment?

Including them in your virtual environment doesn’t take much extra space–they are linked into the virtual environment instead of being copied. Within the virtual environment you can install new versions of packages like Numpy or Astropy that override the versions installed in your normal python environment.

The easiest way to get started is to include in your virtual environment the packages installed in your your normal python environment; the instructions below do that.

In everything that follows, ENV represents the name you give your virtual environment.

The name you choose cannot have spaces in it.

• virtualenvwrapper:

  • Make an environment called ENV with all of the packages in your normal python environment:

    mkvirtualenv --system-site-packages ENV
    

  • Omit the option --system-site-packages to create an environment without the python packages installed in your normal python environment.

  • Environments created with virtualenvwrapper always include pip and setuptools so that you can install packages within the virtual environment.

  • More details and examples are in the virtualenvwrapper command documentation.

• conda:

  • Make an environment called ENV with all of the packages in your main anaconda environment:

    conda create -n ENV anaconda
    

  • More details, and examples that start with none of the packages from your normal python environment, are in the documentation for the conda command and the guide on how to manage environments.

  • If astropy is installed in your environment, you may need to uninstall it in order for the development version to install properly. You can do this with the following command:

    conda uninstall astropy
    

Activate a virtual environment

To use a new virtual environment you may need to activate it; virtualenvwrapper will try to automatically activate your new environment when you create it. Activation does two things (either of which you could do manually, though it would be inconvenient):

• Put the bin directory for the virtual environment at the front of your $PATH.

• Add the name of the virtual environment to your command prompt. If you have successfully switched to a new environment called ENV your prompt should look something like this: (ENV)[~] $

The commands below allow you to switch between virtual environments in addition to activating new ones.

• virtualenvwrapper: Activate the environment ENV with:

  workon ENV
  

• ` conda`: Activate the environment ENV with:

  conda activate ENV
  

Deactivate a virtual environment

At some point you may want to go back to your normal python environment. Do that with:

• virtualenvwrapper: deactivate

  • Note that in virtualenvwrapper 4.1.1 the output of mkvirtualenv says you should use source deactivate; that does not seem to actually work.

• conda: conda deactivate

Delete a virtual environment

In both virtualenvwrapper and conda you can simply delete the directory in which the ENV is located; both also provide commands to make that a bit easier.

• virtualenvwrapper: rmvirtualenv ENV

• conda: conda remove --all -n ENV