Installation

Requirements

Optional:

Installation using system package managers

Linux

Major GNU/Linux distributions (including Debian and Ubuntu derivatives, Arch, Fedora, Red Hat and CentOS) have a python-ase package available that you can install on your system. This will manage dependencies and make ASE available for all users.

Note

Depending on the distribution, this may not be the latest release of ASE.

Max OSX (Homebrew)

It is generally not recommended to rely on the Mac system Python. Mac OSX versions before 12.3 included an old Python, incompatible with ASE and missing the pip package manager. Since 12.3 MacOS has moved to newer Python versions but it may not be installed by default. Over time, different approaches to Python on Mac have been popular and things can get a bit messy.

Before installing ASE with pip as described in the next section, Mac users need to install an appropriate Python version. One approach uses the Homebrew package manager, which provides an up-to-date version of Python 3 and the tkinter library needed for ase gui:

$ brew install python-tk

Note that Homebrew only allows pip to install to virtual environments. For more information about the quirks of brewed Python see this guide.

Installation from PyPI using pip

The simplest way to install ASE is to use pip which will automatically get the source code from PyPI:

$ pip install --upgrade ase

If you intend to run the tests, use:

$ pip install --upgrade ase[test]

Local user installation

The above commands should work if you are using a virtualenv, Conda or some other user-level Python installation.

If your Python/pip was provided by a system administrator or package manager, you might not have appropriate permissions to install ASE and its dependencies to the default locations. In that case install with e.g.:

$ pip install --upgrade --user ase

This will install ASE in a local folder where Python can automatically find it (~/.local on Unix, see here for details). The Command line tool will be installed in the following location:

Unix and Mac OS X

~/.local/bin

Windows

%APPDATA%/Python/Scripts

Make sure you have that path in your PATH environment variable.

Installation from source

As an alternative to PyPI, you can also get the source from a tar-file or from Git.

Tar-file:

You can get the source as a tar-file for the latest stable release (ase-3.23.0.tar.gz) or the latest development snapshot (ase-3.23.1b1.tar.gz).

Unpack and make a soft link:

$ tar -xf ase-3.23.0.tar.gz
$ ln -s ase-3.23.0 ase

Here is a list of tarballs.

Git clone:

Alternatively, you can get the source for the latest stable release from https://gitlab.com/ase/ase like this:

$ git clone -b 3.23.0 https://gitlab.com/ase/ase.git

or if you want the development version:

$ git clone https://gitlab.com/ase/ase.git

With the source from a Git clone or tar file, you can install the code with pip install /path/to/source, which will manage dependencies as though installing from PyPI. (See Local user installation above if there are permissions problems.) Alternatively, you can add ~/ase to your PYTHONPATH environment variable and add ~/ase/bin to PATH (assuming ~/ase is where your ASE folder is). In this case you are responsible for also installing the dependencies listed in pyproject.toml.

Finally, please run the tests.

Pip install directly from git source

This is a convenient way to install the “bleeding-edge” master branch directly with pip, if you don’t intend to do further development:

$ pip install --upgrade git+https://gitlab.com/ase/ase.git@master

The --upgrade ensures that you always reinstall even if the version number hasn’t changed.

Note

We also have Git-tags for older stable versions of ASE. See the Release notes for which tags are available. Also the dates of older releases can be found there.

Test your installation

Before running the tests, make sure you have set your PATH environment variable correctly as described in the relevant section above. Run the tests like this:

$ ase test  # takes 1 min.

and send us the output if there are failing tests.