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, but sandboxed from your default Python environment in the sense that packages installed in the virtual environment do not affect your normal working environment in any way. This allows you to install, for example, a development version of Astropy and its dependencies without it conflicting with your day-to-day work with Astropy and other Python packages.
“Default Python environment” here means whatever Python you are using when you log in; i.e. the default Python installation on your system, which is not in a Conda environment or virtualenv.
More specifically, in UNIX-like platforms it creates a parallel root
“prefix” with its own
lib/, etc. directories. When you
activate the virtual environment it places this
bin/ at the head of your
$PATH environment variable.
This works similarly on Windows but the details depend on how you installed Python and whether or not you’re using Miniconda.
There are a few options for using virtual environments; the choice of method is dictated by the Python distribution you use:
miniconda is a minimal flavor of the popular Anaconda Python
distribution, containing only
conda, Python, other useful packages
requests, etc.) and their dependencies in the
Further packages and environments can then be bootstrapped from the
base environment, allowing developers to install just the
packages needed, and nothing more.
If you do not wish to use Miniconda you can use virtualenv and the conda-like helper commands provided by virtualenvwrapper; you can not use this with conda. As the name suggests, virtualenvwrapper is a wrapper around virtualenv.
Another well-maintained guide to Python virtualenvs (specifically pipenv and virtualenv, though it does not discuss conda) which has been translated into multiple languages is the Hitchhiker’s Guide to Python chapter on the subject.
Set up for virtual environments¶
pipenv: Install the
pipenvcommand using your default pip (the pip in the default Python environment):
pip install --user pipenv
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.
conda info -e
you will always have at least one environment, called
your active environment is indicated by a
pipenv does not have a concept of listing virtualenvs; it instead automatically generates the virtualenv associated with a project directory (e.g. the Astropy source repository on your computer).
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 default 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 default Python environment.
The easiest way to get started is to include in your virtual environment the packages installed in your your default Python environment; the instructions below do that.
In everything that follows,
ENV represents the name you give your virtual
The name you choose cannot have spaces in it.
Make an environment called
ENVwith all of the packages in your
conda create -n ENV
As a general good practice, it is best to keep
baseuntouched, and install any packages you may need into isolated environments. This way, even if you create new environments starting from
base, you control exactly which packages are installed, saving you from subtle dependency issues down the road.
Next activate the environment
conda activate ENV
Your command-line prompt will contain
ENVin parentheses by default.
If Astropy is installed in your
ENVenvironment, 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
Depending on your development use case, you may want to install additional packages into this environment in order to carry out tests, build documentation, extend specific additional features etc. See Testing Dependencies, Building Documentation, and Requirements for Astropy respectively to get started according to your use case.
Make an environment called
ENVwith all of the packages in your default Python environment:
mkvirtualenv --system-site-packages ENV
Omit the option
--system-site-packagesto create an environment without the Python packages installed in your default Python environment.
More details and examples are in the virtualenvwrapper command documentation.
Make sure you are in the Astropy source directory. See Try the development version if you are unsure how to get the source code. After running
git clone <your-astropy-fork>run
pipenv install -e .
This both creates the virtual environment for the project automatically, and also installs all of Astropy’s dependencies, and adds your Astropy repository as the version of Astropy to use in the environment.
You can activate the environment any time you’re in the top-level
astropy/directory (cloned from git) by running:
This will open a new shell with the appropriate virtualenv enabled.
You can also run individual commands from the virtualenv without activating it in the shell like:
pipenv run python
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):
bindirectory for the virtual environment at the front of your
Adds the name of the virtual environment to your command prompt. If you have successfully switched to a new environment called
ENVyour prompt should look something like this:
The commands below allow you to switch between virtual environments in addition to activating new ones.
Deactivate a virtual environment¶
At some point you may want to go back to your default Python environment. Do that with:
Note that in
virtualenvwrapper 4.1.1the output of
mkvirtualenvsays you should use
source deactivate; that does not seem to actually work.
pipenvdoes not manipulate environment variables in your current shell session. Instead it launches a subshell which is a copy of your previous shell, in which it can then change some environment variables. Therefore, any environment variables you change in the
pipenvshell will be restored to their previous value (or lost entirely) when
exit-ing the subshell.
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. pipenv includes a command for deleting the
virtual environment associated with the current directory: