Installation

Requirements

  • Python 3.6 or newer

  • NumPy (base N-dimensional array package)

  • SciPy (library for scientific computing)

Optional but strongly recommended:

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)

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

~/.local/bin

Homebrew

~/Library/Python/X.Y/bin

Windows

%APPDATA%/Python/Scripts

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.

Note

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.

Tar-file

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

Unpack and make a soft link:

$ tar -xf ase-3.22.1.tar.gz
$ ln -s ase-3.22.1 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.22.1 https://gitlab.com/ase/ase.git

or if you want the development version:

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

install git master directly with pip:

$ 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.

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 setup.py 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.

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.

Environment variables

PATH

Colon-separated paths where programs can be found.

PYTHONPATH

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}

Note

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
fi

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.