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
      $ 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
    $ sudo service postgresql start
  1. Install RabbitMQ following the instructions applicable to your system.

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


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 pip venv ~/envs/aiida
$ source ~/envs/aiida/bin/activate
(aiida) $ pip install aiida-core
(aiida) $ reentry scan


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

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 -n aiida -c conda-forge aiida-core
    $ conda activate aiida
    (aiida) $ reentry scan

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

Open a terminal and execute:

$ git clone
$ cd aiida-core/
$ python -m pip venv ~/envs/aiida
$ source ~/envs/aiida/bin/activate
(aiida) $ pip install .
(aiida) $ reentry scan

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):
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


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


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
✓ config dir:  /home/ubuntu/.aiida
✓ profile:     On profile me
✓ repository:  /home/ubuntu/.aiida/repository/me
✓ postgres:    Connected as aiida_qs_ubuntu_c6a4f69d255fbe9cdb7385dcdcf3c050@localhost:5432
✓ rabbitmq:    Connected as amqp://
✓ daemon:      Daemon is running as PID 16430 since 2020-04-29 12:17:31

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

Missing a checkmark or ecountered some other issue?

See the troubleshooting section.

What’s next?