Skip to main content
`Ctrl`+`K`

# Installation

## Requirements

- Python 3.9 or newer

- NumPy (base N-dimensional array package)

- SciPy (library for scientific computing)

- Matplotlib (plotting)

Optional:

- Flask for `ase.db` web-interface

- pytest for running tests

- pytest-mock for running some more tests

- pytest-xdist for running tests in parallel

- spglib for certain symmetry-related features

## Installation using system package managers

### Linux

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

Red Hat requires the EPEL repository.

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 here: ase-3.26.0.tar.gz

  Unpack and make a soft link:

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

  Here is a list of tarballs.

Git clone:

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

      $ git clone -b 3.26.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.