Installation guide — ASE documentation

### Navigation

- index
- modules |

# Installation guide

In order to choose the right method for installing ASE identify your computer system and your goals related to ASE. Is it a personal laptop or maybe an HPC cluster? Are you just trying out ASE or need a full development environment in order to participate in developing ASE?

For the installation on personal laptops we recommend the binary packages provided for popular Linux distributions (Installation with package manager on Linux) and MS Windows (Installation on Windows).

Please skip to Manual installation if you prefer to install from sources.

If you are on Mac OSX, please follow Installation on OS X.

## Installation with package manager on Linux

Install the binaries with the software package manager of your Linux distribution.

This is the preferred way to install on a Linux system.

If you prefer to install from sources follow Manual installation.

The currently supported systems include (issue the commands below as root):

- Fedora:

      yum install -y python-ase

- RHEL/CentOS - available after enabling https://fedoraproject.org/wiki/EPEL:

      yum install -y python-ase

- openSUSE 13.1:

      zypper ar -f http://download.opensuse.org/repositories/home:/dtufys/openSUSE_13.1/home:dtufys.repo
      yast -i python-ase
      yast -i python-matplotlib # optionally

- Debian 7.0:

      sudo bash -c 'echo "deb http://download.opensuse.org/repositories/home:/dtufys/Debian_7.0 /" > /etc/apt/sources.list.d/home_dtufys.sources.list'
      wget http://download.opensuse.org/repositories/home:/dtufys/Debian_7.0/Release.key && sudo apt-key add Release.key && rm Release.key
      sudo apt-get update
      sudo apt-get -y install python-ase
      sudo apt-get -y install python-matplotlib # optionally

- Ubuntu 14.04:

      sudo bash -c 'echo "deb http://download.opensuse.org/repositories/home:/dtufys/xUbuntu_14.04 /" > /etc/apt/sources.list.d/home_dtufys.sources.list'
      wget http://download.opensuse.org/repositories/home:/dtufys/xUbuntu_14.04/Release.key && sudo apt-key add Release.key && rm Release.key
      sudo apt-get update
      sudo apt-get -y install python-ase
      sudo apt-get -y install python-matplotlib # optionally

For the full list of supported distributions check https://build.opensuse.org/package/show?package=python-ase&project=home%3Adtufys

After performing the installation do not forget to Run the tests!

## Installation on OS X

For installation with http://brew.sh please follow instructions at Homebrew.

After performing the installation do not forget to Run the tests!

## Installation on Windows

Note

ASE is not yet fully functional on Windows! https://trac.fysik.dtu.dk/projects/ase/ticket/62

On Windows the following packages need to installed. On the command prompt:

Note

installation assumes the python TARGETDIR C:\Python27, leave also the default C:\Program Files\pythonxy.

- pythonxy. Download the exe installer and install with:

      Python(x,y)-2.7.2.2.exe /Log="%TMP%\pythonxy_install.log" /S

Note

Open Task Manager and control when the process in finished.

- pygtk_win32. Download the msi pygtk-all-in-one installer. Specify the correct TARGETDIR and install:

      pygtk-all-in-one-2.24.2.win32-py2.7.msi TARGETDIR="%HOMEDRIVE%\Python27" ALLUSERS=1 /l*vx "%TMP%\pygtk_install.log" /passive

Note

If performing clicking-installation make sure that the default python Windows TARGETDIR is selected.

- Download the python-ase-win32.msi installer and install with:

      python-ase-X.X.X.win32.msi /l*vx "%TMP%\python-ase_install.log" /passive

Note

You can build the msi ASE package on Windows with:

    python setup.py bdist_msi

The msi package will be created under the dist directory.

After performing the installation do not forget to Run the tests!

## Manual installation

ASE binaries are available only for the Latest stable release, and all available ASE releases are listed at the Download page.

If you need a development version (or a historic version) of ASE perform a manual installation according to instructions below. Follow the same instructions if you are configuring ASE on an HPC cluster.

This is the preferred way of manually installing ASE. It offers the following advantages:

- installation is limited to standard user’s account: it does not pollute the root filesystem,
- user gains access to version control updates, if necessary.

### Requirements

The following packages are required for basic ASE functionality:

1. Python2 version 2.6 or newer. Python3 is not supported yet.
2. NumPy.

It is highly recommended (but not required) to install also these:

3. matplotlib.
4. libpng.
5. pygtk.
6. SciPy.

Matplotlib and libpng are needed for `writing png files`, and together with pygtk are needed for ASE’s simple GUI (called ase-gui, see `ase.gui`). Some of these packages may already be installed on your system.

### Installation process

After the Download of ASE source create the link to the requested version, e.g.:

- if retrieved from `svn`:

      $ cd $HOME
      $ ln -s ase-3.9.0 ase

- if retrieved as tar-file:

      $ cd $HOME
      $ tar -xf python-ase-3.9.0.4465.tar.gz
      $ ln -s python-ase-3.9.0.4465 ase

It is sufficient to put the directory `$HOME/ase` in your `PYTHONPATH` environment variable, and the directory `$HOME/ase/tools` in your `PATH` environment variable. Do this permanently in your `~/.bashrc` file:

    export PYTHONPATH=$HOME/ase:$PYTHONPATH
    export PATH=$HOME/ase/tools:$PATH

or your `~/.cshrc` file:

    setenv PYTHONPATH ${HOME}/ase:${PYTHONPATH}
    setenv PATH ${HOME}/ase/tools:${PATH}

Instead of `HOME`, you may use any other directory.

Alternatively, you can install ASE to the user-specific site-packages directory with:

    $ cd ase
    $ python setup.py install --user

This way, the ASE modules are found on the python path without any explicit configuration, though you still need to ensure that `$HOME/.local/bin` (or on Windows, `%APPDATA%/Python/Scripts`) is on your `PATH`.

Optional, NOT recommended way of installing ASE system-wide is:

    $ cd ase
    $ sudo python setup.py install

This is one of the best ways to ruin a Linux system.

### Download

#### Latest stable release

The latest stable release can be obtained from SVN or as a tar-file.

Note

The recommended installation path is `$HOME`.

When using svn please set the following variable:

- bash:

      export ASE_TAGS=https://svn.fysik.dtu.dk/projects/ase/tags/

- csh/tcsh:

      setenv ASE_TAGS https://svn.fysik.dtu.dk/projects/ase/tags/

Release | Date | Retrieve as svn checkout | Retrieve as tar-file
--- | --- | --- | ---
3.9.0 | May 28 2015 | `svn co -r 4465 $ASE_TAGS/3.9.0 ase-3.9.0` | python-ase-3.9.0.4465.tar.gz
3.8.1 | Nov 22 2013 | `svn co -r 3440 $ASE_TAGS/3.8.1 ase-3.8.1` | python-ase-3.8.1.3440.tar.gz
3.8.0 | Oct 22 2013 | `svn co -r 3420 $ASE_TAGS/3.8.0 ase-3.8.0` | python-ase-3.8.0.3420.tar.gz
3.7.1 | May 16 2013 | `svn co -r 3184 $ASE_TAGS/3.7.1 ase-3.7.1` | python-ase-3.7.1.3184.tar.gz
3.7.0 | May 13 2013 | `svn co -r 3168 $ASE_TAGS/3.7.0 ase-3.7.0` | python-ase-3.7.0.3168.tar.gz
3.6.0 | Feb 24 2012 | `svn co -r 2515 $ASE_TAGS/3.6.0 ase-3.6.0` | python-ase-3.6.0.2515.tar.gz
3.5.1 | May 24 2011 | `svn co -r 2175 $ASE_TAGS/3.5.1 ase-3.5.1` | python-ase-3.5.1.2175.tar.gz
3.4.1 | Aug 11 2010 | `svn co -r 1765 $ASE_TAGS/3.4.1 ase-3.4.1` | python-ase-3.4.1.1765.tar.gz
3.4.0 | Apr 23 2010 | `svn co -r 1574 $ASE_TAGS/3.4.0 ase-3.4.0` | python-ase-3.4.0.1574.tar.gz
3.3.1 | Jan 20 2010 | `svn co -r 1390 $ASE_TAGS/3.3.1 ase-3.3.1` | python-ase-3.3.1.1390.tar.gz
3.2.0 | Sep 4 2009 | `svn co -r 1121 $ASE_TAGS/3.2.0 ase-3.2.0` | python-ase-3.2.0.1121.tar.gz
3.1.0 | Mar 27 2009 | `svn co -r 846 $ASE_TAGS/3.1.0 ase-3.1.0` | python-ase-3.1.0.846.tar.gz
3.0.0 | Nov 13 2008 | `svn co -r 657 $ASE_TAGS/3.0.0 ase-3.0.0` | python-ase-3.0.0.657.tar.gz

#### Latest development release

The latest revision can be obtained like this:

    $ svn checkout https://svn.fysik.dtu.dk/projects/ase/trunk ase

or from the daily snapshot: snapshot.tar.gz.

Note

The recommended checkout path is `$HOME`.

## Run the tests

Make sure that everything works by running the test suite. This will create many files, so run the tests in a new directory (preferably using bash):

    $ bash
    $ mkdir /tmp/testase.$$; cd /tmp/testase.*
    $ python -c "from ase.test import test; test(verbosity=2, display=True)" 2>&1 | tee testase.log

Note

The last test ase/test/COCu111.py requires closing the graphics windows to terminate the whole test-suite.

Note

If matplotlib or pygtk is not installed, this test will fail - avoid this with `display=False`.

If any of the tests fail, then please send us `testase.log` (see Bugs!).

## Video tutorial

In the video: Overview of the features of ASE, followed by a Manual installation of ASE on a Linux system.

Note

Use “Right Click -> Play” to play.

### Navigation

- index
- modules |