Astropy has the following strict requirements:
- Python 2.6 (>=2.6.5), 2.7, 3.3, 3.4 or 3.5
- Prior to Astropy v1.0 Python 3.1 and 3.2 are also supported.
- Numpy 1.6.0 or later
Astropy also depends on other packages for optional features:
- h5py: To read/write
Tableobjects from/to HDF5 files
- BeautifulSoup: To read
Tableobjects from HTML files
- PyYAML: To read/write
Tableobjects from/to the Enhanced CSV ASCII table format.
- scipy: To power a variety of features (currently mainly cosmology-related functionality)
- xmllint: To validate VOTABLE XML files.
- matplotlib: To provide plotting functionality that
- WCSAxes: To use
astropy.wcsto define projections in Matplotlib.
- objgraph: Used only in tests to test for reference leaks.
However, note that these only need to be installed if those particular features are needed. Astropy will import even if these dependencies are not installed.
To install Astropy with pip, simply run:
pip install --no-deps astropy
Users of the Anaconda python distribution should follow the instructions for Anaconda python distribution.
You will need a C compiler (e.g.
clang) to be installed (see
Building from source below) for the installation to succeed.
--no-deps flag is optional, but highly recommended if you already
have Numpy installed, since otherwise pip will sometimes try to “help” you
by upgrading your Numpy installation, which may not always be desired.
If you get a
PermissionError this means that you do not have the
required administrative access to install new packages to your Python
installation. In this case you may consider using the
to install the package into your home directory. You can read more
about how to do this in the pip documentation.
Alternatively, if you intend to do development on other software that uses Astropy, such as an affiliated package, consider installing Astropy into a virtualenv.
Do not install Astropy or other third-party packages using
unless you are fully aware of the risks.
Anaconda python distribution¶
Astropy is installed by default with Anaconda. To update to the latest version run:
conda update astropy
There may be a delay of a day or two between when a new version of Astropy
is released and when a package is available for Anaconda. You can check
for the list of available versions with
conda search astropy.
Attempting to use
pip to upgrade your installation of Astropy may result
in a corrupted installation.
Binary installers are available on Windows for Python 2.6, 2.7, and >= 3.3 at PyPI.
Testing an installed Astropy¶
The easiest way to test your installed version of astropy is running correctly is to use the astropy.test() function:
import astropy astropy.test()
The tests should run and print out any failures, which you can report at the Astropy issue tracker.
This way of running the tests may not work if you do it in the astropy source distribution. See Testing a source code build of Astropy for how to run the tests from the source code directory, or Running Tests for more details.
Running the tests this way is currently disabled in the IPython REPL due to conflicts with some common display settings in IPython. Please run the Astropy tests under the standard Python command-line interpreter.
Building from source¶
You will need a compiler suite and the development headers for Python and Numpy in order to build Astropy.
You will also need Cython (v0.21 or later) and jinja2 (v2.7 or later) installed to build from source, unless you are installing a numbered release. (The releases packages have the necessary C files packaged with them, and hence do not require Cython.)
Prerequisites for Linux¶
On Linux, using the package manager for your distribution will usually be the easiest route. In order to build from source, you’ll need the python development package for your distro.
sudo apt-get install python-dev
sudo yum install python-devel
Prerequisites for Mac OS X¶
On MacOS X you will need the XCode command line tools which can be installed using
For installing XCode command line tools:
and follow the onscreen instructions to install the command line tools required.
You’ll also need the python development package for Mac OS X to proceed in building astropy from source.
To install the python development package for Mac OS X, from a package manager like brew, macports or fink.
The instructions for building Numpy from source are also a good resource for setting up your environment to build Python packages.
If you are using MacOS X, you will need to the XCode command line tools. One way to get them is to install XCode. If you are using OS X 10.7 (Lion) or later, you must also explicitly install the command line tools. You can do this by opening the XCode application, going to Preferences, then Downloads, and then under Components, click on the Install button to the right of Command Line Tools. Alternatively, on 10.7 (Lion) or later, you do not need to install XCode, you can download just the command line tools from https://developer.apple.com/downloads/index.action (requires an Apple developer account).
Obtaining the source packages¶
The latest development version of Astropy can be cloned from github using this command:
git clone git://github.com/astropy/astropy.git
If you wish to participate in the development of Astropy, see Developer Documentation. This document covers only the basics necessary to install Astropy.
Building and Installing¶
Astropy uses the Python distutils framework for building and
installing and requires the
distribute extension–the later is
automatically downloaded when running
python setup.py if it is not already
provided by your system.
If Numpy is not already installed in your Python environment, the astropy setup process will try to download and install it before continuing to install astropy.
To build Astropy (from the root of the source tree):
python setup.py build
To install Astropy (from the root of the source tree):
python setup.py install
If you get an error mentioning that you do not have the correct permissions to
install Astropy into the default
site-packages directory, you can try
python setup.py install --user
which will install into a default directory in your home directory.
External C libraries¶
The Astropy source ships with the C source code of a number of
libraries. By default, these internal copies are used to build
Astropy. However, if you wish to use the system-wide installation of
one of those libraries, you can pass one or more of the
--use-system-X flags to the
setup.py build command.
For example, to build Astropy using the system libexpat, use:
python setup.py build --use-system-expat
To build using all of the system libraries, use:
python setup.py build --use-system-libraries
To see which system libraries Astropy knows how to build against, use:
python setup.py build --help
As with all distutils commandline options, they may also be provided in a
setup.cfg in the same directory as
setup.py. For example, to use
the system libexpat, add the following to the
The required version of setuptools is not available¶
If upon running the
setup.py script you get a message like
The required version of setuptools (>=0.9.8) is not available, and can’t be installed while this script is running. Please install a more recent version first, using ‘easy_install -U setuptools’.
(Currently using setuptools 0.6c11 (/path/to/setuptools-0.6c11-py2.7.egg))
this is because you have a very outdated version of the setuptools package which is used to install
Python packages. Normally Astropy will bootstrap newer version of
setuptools via the network, but setuptools suggests that you first
uninstall the old version (the
easy_install -U setuptools command).
However, in the likely case that your version of setuptools was installed by an
OS system package (on Linux check your package manager like apt or yum for a
python-setuptools), trying to uninstall with
easy_install and without using
sudo may not work, or may leave your
system package in an inconsistent state.
As the best course of action at this point depends largely on the individual system and how it is configured, if you are not sure yourself what do please ask on the Astropy mailing list.
The Windows installer can’t find Python in the registry¶
This is a common issue with Windows installers for Python packages that do not
support the new User Access Control (UAC) framework added in Windows Vista and
later. In particular, when a Python is installed “for all users” (as opposed
to for a single user) it adds entries for that Python installation under the
HKEY_LOCAL_MACHINE (HKLM) hierarchy and not under the
HKEY_CURRENT_USER (HKCU) hierarchy. However, depending on your UAC
settings, if the Astropy installer is not executed with elevated privileges it
will not be able to check in HKLM for the required information about your
In short: If you encounter this problem it’s because you need the appropriate entries in the Windows registry for Python. You can download this script and execute it with the same Python as the one you want to install Astropy into. For example to add the missing registry entries to your Python 2.7:
Building the documentation is in general not necessary unless you are writing new documentation or do not have internet access, because the latest (and archive) versions of astropy’s documentation should be available at docs.astropy.org .
Building the documentation requires the Astropy source code and some additional packages:
Sphinx also requires a reasonably modern LaTeX installation to render equations. Per the Sphinx documentation, for the TexLive distribution the following packages are required to be installed:
For other LaTeX distributions your mileage may vary. To build the PDF
documentation using LaTeX, the
fonts-extra TexLive package or the
inconsolata CTAN package are also required.
There are two ways to build the Astropy documentation. The most straightforward way is to execute the command (from the astropy source directory):
python setup.py build_sphinx
The documentation will be built in the
docs/_build/html directory, and can
be read by pointing a web browser to
The LaTeX documentation can be generated by using the command:
python setup.py build_sphinx -b latex
The LaTeX file
Astropy.tex will be created in the
directory, and can be compiled using
The above method builds the API documentation from the source code. Alternatively, you can do:
cd docs make html
And the documentation will be generated in the same location, but using the installed version of Astropy.