System-wide installation

The system-wide installation will install the prerequisite services (PostgreSQL and RabbitMQ) via standard package managers such that their startup and shut-down is largely managed by the operating system. The AiiDA (core) Python package is then installed either with Conda or pip.

This is the recommended installation method to setup AiiDA on a personal laptop or workstation for the majority of users.

Install prerequisite services

AiiDA is designed to run on Unix operating systems and requires a bash or zsh shell, and Python >= 3.7.

AiiDA is tested on Ubuntu versions 16.04, 18.04, and 20.04.

Open a terminal and execute:

$ sudo apt install git python3-dev python3-pip postgresql postgresql-server-dev-all postgresql-client rabbitmq-server

The recommended installation method for Mac OS X is to use Homebrew.

  1. Follow this guide to install Homebrew on your system if not installed yet.

  2. Open a terminal and execute:

    $ brew install postgresql rabbitmq git python
$ brew services start postgresql
$ brew services start rabbitmq

The following instructions are for setting up AiiDA on WSL 1/2 in combination with Ubuntu.

  1. Installing RabbitMQ:

    • (WSL 1) Install and start the Windows native RabbitMQ.

    • (WSL 2) Install RabbitMQ inside the the WSL:

      $ sudo apt install rabbitmq-server

      then start the rabbitmq server:

      $ sudo service rabbitmq-server start

  2. Install Python and PostgreSQL:

    $ sudo apt install postgresql postgresql-server-dev-all postgresql-client git python3-dev python-pip

    then start the PostgreSQL server:

    $ sudo service postgresql start
How to setup WSL to automatically start services after system boot.

Create a file start_aiida_services.sh containing the following lines:

$ service postgresql start
$ service rabbitmq-server start # Only for WSL 2!

and store it in your preferred location, e.g., the home directory. Then make the file executable, and editable only by root users with:

$ chmod a+x,go-w /path/to/start_aiida_services.sh
$ sudo chown root:root /path/to/start_aiida_services.sh

Next, run

$ sudo visudo

and add the line

<username> ALL=(root) NOPASSWD: /path/to/start_aiida_services.sh

replacing <username> with your Ubuntu username. This will allow you to run only this specific .sh file with root access (without password), without lowering security on the rest of your system.

Now you can use the Windows Task Scheduler to automatically execute this file on startup:

  1. Open Task Scheduler.

  2. In the “Actions” menu, click “Create Task”.

  3. In “General/Security options”, select “Run whether user is logged on or not”.

  4. In the “Triggers” tab, click “New…”.

    1. In the “Begin the task:” dropdown, select “At startup”.

    2. Click “OK” to confirm.

  5. In the “Actions” tab, click “New…”.

    1. In the “Action” dropdown, select “Start a program”.

    2. In the “Program/script” text field, add C:\Windows\System32\bash.exe.

    3. In the “Add arguments (optional)” text field, add -c "sudo /path/to/start_aiida_services.sh".

    4. Click “OK” to confirm.

  6. Click “OK” to confirm the task.

You can tweak other details of this task to fit your needs.

  1. Install RabbitMQ following the instructions applicable to your system.

  2. Install PostgreSQL following the instructions applicable to your system.

Tip

Alternatively use the pure conda installation method.

Install AiiDA (core)

Install the aiida-core package from PyPI into a virtual environment.

Open a terminal and execute:

$ python -m venv ~/envs/aiida
$ source ~/envs/aiida/bin/activate
(aiida) $ pip install aiida-core

Important

Make sure the python executable is for a Python version that is supported by AiiDA. You can see the version using:

$ python --version

You can find the supported Python versions for the latest version of AiiDA on the PyPI page.

Tip

See the venv documentation if the activation command fails. The exact command for activating a virtual environment differs slightly based on the used shell.

Installation extras

There are additional optional packages that you may want to install, which are grouped in the following categories:

  • atomic_tools: packages that allow importing and manipulating crystal structure from various formats

  • ssh_kerberos: adds support for ssh transport authentication through Kerberos

  • REST: allows a REST server to be ran locally to serve AiiDA data

  • docs: tools to build the documentation

  • notebook: jupyter notebook - to allow it to import AiiDA modules

  • tests: python modules required to run the automatic unit tests

  • pre-commit: pre-commit tools required for developers to enable automatic code linting and formatting

In order to install any of these package groups, simply append them as a comma separated list in the pip install command, for example:

(aiida) $ pip install aiida-core[atomic_tools,docs]
Kerberos on Ubuntu

If you are installing the optional ssh_kerberos and you are on Ubuntu you might encounter an error related to the gss package. To fix this you need to install the libffi-dev and libkrb5-dev packages:

$ sudo apt-get install libffi-dev libkrb5-dev

Install the aiida-core package in a Conda environment.

  1. Make sure that conda is installed, e.g., by following the instructions on installing Miniconda.

  2. Open a terminal and execute:

    $ conda create -yn aiida -c conda-forge aiida-core
$ conda activate aiida

Install the aiida-core package directly from the cloned repository.

Open a terminal and execute:

$ git clone https://github.com/aiidateam/aiida-core.git
$ cd aiida-core/
$ python -m venv ~/envs/aiida
$ source ~/envs/aiida/bin/activate
(aiida) $ pip install .
Setup profile

Next, set up an AiiDA configuration profile and related data storage, with the verdi quicksetup command.

(aiida) $ verdi quicksetup
Info: enter "?" for help
Info: enter "!" to ignore the default and set no value
Profile name: me
Email Address (for sharing data): me@user.com
First name: my
Last name: name
Institution: where-i-work

Is AiiDA unable to auto-detect the PostgreSQL setup?

If you get an error saying that AiiDA has trouble autodetecting the PostgreSQL setup, you will need to do the manual setup explained in the troubleshooting section.

Start verdi daemons

Start the verdi daemon(s) that are used to run AiiDA workflows.

(aiida) $ verdi daemon start 2

Important

The verdi daemon(s) must be restarted after a system reboot.

Tip

Do not start more daemons then there are physical processors on your system.

Check setup

To check that everything is set up correctly, execute:

(aiida) $ verdi status
✓ version:     AiiDA v2.0.0
✓ config:      /path/to/.aiida
✓ profile:     default
✓ storage:     Storage for 'default' @ postgresql://username:***@localhost:5432/db_name / file:///path/to/repository
✓ rabbitmq:    Connected as amqp://127.0.0.1?heartbeat=600
✓ daemon:      Daemon is running as PID 2809 since 2019-03-15 16:27:52

At this point you should now have a working AiiDA environment, from which you can add and retrieve data.

Missing a checkmark or encountered some other issue?

See the troubleshooting section.

What’s next?

previous

Getting started

next

Installation into Conda environment