Tool to launch AiiDAlab on a local workstation.
AiiDAlab Launch makes it easy to run AiiDAlab on your own workstation or laptop.
To use AiiDAlab launch you will have to
Install AiiDAlab launch with pipx (recommended):
pipx install aiidalab-launch
Or directly with pip (
pip install aiidalab-launch).
Start AiiDAlab with
Follow the instructions on screen to open AiiDAlab in the browser.
aiidalab-launch --help for detailed help.
You can inspect the status of all configured AiiDAlab profiles with:
The tool allows to manage multiple profiles, e.g., with different home directories or ports.
aiidalab-launch profile --help for more information.
By default AiiDAlab will store all of its data in a Docker volume defined in the profile configuration option
You can also provide an absolute path to the AiiDAlab home directory on the host system (so called bind mount).
If this directory does not exist, AiiDAlab launch will try to create it on startup.
Additional volumes to be mounted to the the AiiDAlab container can be specified via the
extra_mounts option using the "docker-compose "short syntax"
source is either a volume name or an absolute path to an existing directory on the host system,
target is a path within the AiiDAlab container,
and mode is either
rw for read-write volume (default) or
ro for read-only volume.
As an example, here's how you can mount a quantum chemistry program installed on the host system to make it accessible to AiiDA inside the AiiDAlab container:
extra_mounts = ["/path/to/qcprogram:/opt/qcprogram:ro",]
Finally, AiiDAlab launch will create a dedicated volume for the local conda environment (
That is because some conda packages are not compatible with non-linux file systems, meaning that they cannot be installed if the home directory was, for example, bound to a Mac OS-X file system on the host.
Forward AiiDAlab from a remote server via SSH
Please see here for instructions on how to run AiiDAlab on a remote machine and then forward it to your local terminal.
This package follows the Python compatibility and deprecation schedule specified by NEP 29.
Using Podman instead of Docker
You should be able to use Podman as as a drop-in replacement for Docker, with just a little extra setup. The following was tested on Fedora 39 which comes with Podman pre-installed.
systemctl --user enable podman.socket
systemctl --user start podman.socket
systemctl --user status podman.socket
Setting up a development environment
To develop this package, first clone it and then install the development dependencies with
pip install -e '.[dev]'.
We recommend to install the pre-commit hooks to avoid unnecessary iterations when pushing new changes.
To install the pre-commit hooks, switch into the repository root directly and execute:
Run automated tests
To run the automated tests suite, clone the repository, install test dependencies with
pip install -e '.[tests]', and then execute tests with
for all standard tests, and
to run the full test suite, including tests that will start docker instances and may take multiple minutes.
The continuous integration workflow will run all tests, including the "slow" ones.
Note: On Mac OS-X you may have to override the standard temporary base directory to successfully run all tests (e.g.
pytest --basetemp=$HOME/tmp) since the default base directory may not be accessible to the Docker runtime.
Creating a new release
To create a new release, clone the repository, install development dependencies with
pip install -e '.[dev]', and then execute
- Create a tagged release with bumped version and push it to the repository.
- Trigger a GitHub actions workflow that creates a GitHub release.
- Use the
--dryoption to preview the release change.
- The release should be created directly on the
mainbranch, and as such you need special permissions for writing to it.
- The release tag (e.g. a/b/rc) is determined from the last release.
--tagoption to switch the release tag.
See also the list of contributors.
Users of AiiDAlab are kindly asked to cite the following publication in their own work:
A. V. Yakutovich et al., Comp. Mat. Sci. 188, 110165 (2021). DOI:10.1016/j.commatsci.2020.110165
Contributions in any form are very welcome. Please see CONTRIBUTING.md for contribution guidelines.
Copyright (c) 2021 Carl Simon Adorf (EPFL)
All rights reserved.
Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
This work is supported by the MARVEL National Centre for Competency in Research funded by the Swiss National Science Foundation, the MARKETPLACE project funded by Horizon 2020 under the H2020-NMBP-25-2017 call (Grant No. 760173), as well as by the MaX European Centre of Excellence funded by the Horizon 2020 EINFRA-5 program, Grant No. 676598.
Release history Release notifications | RSS feed
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.
Hashes for aiidalab_launch-2024.1020.tar.gz
Hashes for aiidalab_launch-2024.1020-py3-none-any.whl