Why a virtual environment?¶
AiiDA depends on third party python packages and very often on specific versions of those packages. If AiiDA were to be installed system wide, it may up- or downgrade third party packages used by other parts of the system and leave them potentially broken. Conversely, if a different version of a package is later installed which is incompatible with AiiDA, it too will become broken.
In short, installing AiiDA might interfere with installed python packages and installing other packages might interfere with AiiDA. Since your scientific data is important to you and to us, we strongly recommend isolating AiiDA in what is called a virtual environment.
For a single purpose machine, only meant to run AiiDA and nothing else, you may at your own risk opt to omit working in a virtual environment.
In this case, you may want to install AiiDA and its dependencies in user space by using a
--user flag, to avoid the need for administrative rights to install them system wide.
What is a virtual environment?¶
A python virtual environment is essentially a folder, that contains everything that is needed to run python programs, including
- python executable
- python standard packages
- package managers such as
- an activation script that sets the
python executable might be a link to an executable elsewhere, depending on the way the environment is created.
The activation script ensures that the python executable of the virtualenv is the first in
PATH, and that python programs have access only to packages installed inside the virtualenv (unless specified otherwise during creation).
This allows to have an isolated environment for programs that rely on running with a specific version of python or specific versions of third party python packages.
A virtual environment as well as the packages that will be installed within it, will often be installed in the home space of the user such that administrative rights are not required, therefore also making this technique very useful on machines where one has restricted access.
Creating a virtual environment¶
There are different programs that can create and work with virtual environments.
An example for python virtual environments is called
virtualenv and can be installed with for example
pip by running:
$ pip install --user -U virtualenv
As explained before, a virtual environment is in essence little more than a directory containing everything it needs. In principle a virtual environment can thus be created anywhere where you can create a directory. You could for example opt to create a directory for all your virtual environments in your home folder:
$ mkdir ~/.virtualenvs
virtualenv you can then create a new virtual environment with python 2.7 by running:
$ virtualenv --python=<path/to/python2.7> ~/.virtualenvs/my_env
This will create the environment
my_env and automatically activate it for you.
If you open a new terminal, or you have deactivated the environment, you can reactivate it as follows:
If it is activated successfully, you should see that your prompt is prefixed with the name of the environment:
To leave or deactivate the environment and set all the settings back to default, simply run:
(my_env) $ deactivate
.aiida folder in your virtualenvironment¶
When you run AiiDA in multiple virtual environments, it can be convenient to use a separate
.aiida folder for each virtualenv. To do this, you can use the AIIDA_PATH mechanism as follows:
Create your virtualenv, as described above
.aiidadirectory in your virtualenv directory:
$ mkdir ~/.virtualenvs/my_env/.aiida
At the end of
~/.virtualenvs/my_env/bin/activate, add the following line:
Deactivate and re-activate the virtualenv
You can test that everything is set up correctly if you can reproduce the following:
(my_env)$ echo $AIIDA_PATH >>> ~/.virtualenvs/my_env (my_env)$ verdi profile list >>> Configuration folder: /home/my_username/.virtualenvs/my_env/.aiida >>> Stopping: No configuration file found >>> Note: if no configuration file was found, it means that you have not run >>> 'verdi setup' yet to configure at least one AiiDA profile.
Continue setting up AiiDA with