• Python 3.8 or newer

  • NumPy (base N-dimensional array package)

  • SciPy (library for scientific computing)

Optional but strongly recommended:


Installation using system package managers


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.


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

Max OSX (Homebrew)

The old version of Python included in Mac OSX is incompatible with ASE and does not include the pip package manager.

Before installing ASE with pip as described in the next section, Mac users need to install an appropriate Python version. One option is to use the Homebrew package manager, which provides an up-to-date version of Python 3 including pip and the tkinter graphical interface bindings:

$ brew install python

For more information about the quirks of brewed Python see this guide.

Installation using pip

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

$ pip install --upgrade --user ase

If you intend to run the tests, use:

$ pip install --upgrade --user ase[test]

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

Unix and Mac OS X






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

Now you should be ready to use ASE, but before you start, you may wish to run the tests as described below.


If your OS doesn’t have numpy, scipy and matplotlib packages installed, you can install them with:

$ pip install --upgrade --user numpy scipy matplotlib

Installation from source

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


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 like this:

$ git clone -b 3.23.0

or if you want the development version:

$ git clone

install git master directly with pip:

$ pip install --upgrade git+

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

Add ~/ase to your PYTHONPATH environment variable and add ~/ase/bin to PATH (assuming ~/ase is where your ASE folder is). Alternatively, you can install the code with python install --user and add ~/.local/bin to the front of your PATH environment variable (if you don’t already have that).

Finally, please run the tests.


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.

Environment variables


Colon-separated paths where programs can be found.


Colon-separated paths where Python modules can be found.

Set these permanently in your ~/.bashrc file:

$ export PYTHONPATH=<path-to-ase-package>:$PYTHONPATH
$ export PATH=<path-to-ase-command-line-tools>:$PATH

or your ~/.cshrc file:

$ setenv PYTHONPATH <path-to-ase-package>:${PYTHONPATH}
$ setenv PATH <path-to-ase-command-line-tools>:${PATH}


If running on Mac OSX: be aware that terminal sessions will source ~/.bash_profile by default and not ~/.bashrc. Either put any export commands into ~/.bash_profile or source ~/.bashrc in all Bash sessions by adding

if [ -f ${HOME}/.bashrc ]; then
source ${HOME}/.bashrc

to your ~/.bash_profile.

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.