index | modules | gitlab | page source

# Installation

## Requirements

- Python 3.6 or newer

- NumPy (base N-dimensional array package)

- SciPy (library for scientific computing)

Optional but strongly recommended:

- Matplotlib for plotting

- `tkinter` for `ase.gui`

Optional:

- Flask for `ase.db` web-interface

- pytest for running tests

- pytest-xdist for running tests in parallel

- spglib for certain symmetry-related features

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