Sphinx rtd theme:





pip install Sphinx
sphinx-build -aE . _build/


make html


Insert link to download file:

:download:`A Detailed Example <conda-cheatsheet.pdf>`


.. include:: ../README.txt

Some text:

$ first command
$ second command


-L tunneling
-N non entering to bash
-f background run
-i <private_key>
-p port
A B A and B
False False False
True False False
False True False
True True True

  • Python 2.6, 2.7, 3.4, 3.5
  • NumPy (base N-dimensional array package)


  • For extra functionality: SciPy (library for scientific computing)
  • For ase.gui: PyGTK (GTK+ for Python) and Matplotlib (2D Plotting)

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)

Mac users may be familiar with Homebrew; while there is not a specific ASE package, Homebrew can be used to install the pyGTK dependency of ase.gui

$ brew install pygtk

before installing ASE with pip as described in the next section. Homebrew’s python package provides an up-to-date version of Python 2.7.x and sets up pip for you:

$ brew install python

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
This will install ASE in a local folder where Python can
automatically find it (``~/.local`` on Unix, see here_ for details).  Some
:ref:`cli` 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, please 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 <http://xkcd.com/1168/>`__ for the
latest stable release (ase-3.12.0.tar.gz_) or the latest
development snapshot (`<snapshot.tar.gz>`_).

Unpack and make a soft link::

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

or if you want the development version:

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

Add ~/ase to your PYTHONPATH environment variable and add ~/ase/tools 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 :ref:`releasenotes` for which tags are available.  Also the
    dates of older releases can be found there.

.. _ase-3.12.0.tar.gz: https://pypi.python.org/packages/ab/d4/

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:

$ python -m ase.test  # takes 1 min.

and send us the output if there are failing tests.