Installation¶
Requirements¶
Astropy has the following strict requirements:
- Python 2.7, 3.4, 3.5 or 3.6
- Prior to Astropy v1.0, Python 3.1 and 3.2 were also supported.
- Prior to Astropy v1.2, Python 2.6 was supported.
- Prior to Astropy v2.0, Python 3.3 was supported.
- Numpy 1.9.0 or later
- pytest 2.8 or later
Astropy also depends on other packages for optional features:
- scipy: To power a variety of features in several modules.
- h5py: To read/write
Table
objects from/to HDF5 files. - BeautifulSoup: To read
Table
objects from HTML files. - bleach: Used to sanitize text when
disabling HTML escaping in the
Table
HTML writer. - PyYAML: To read/write
Table
objects from/to the Enhanced CSV ASCII table format. - xmllint: To validate VOTABLE XML files.
- pandas: To read/write
Table
objects from/to pandas DataFrame objects. - bintrees for faster
FastRBT
andFastBST
indexing engines withTable
, although these will still be slower in most cases than the default indexing engine. - pytz: To specify and convert between timezones.
- jplephem: To retrieve JPL ephemeris of Solar System objects.
- matplotlib 1.5 or later: To provide plotting
functionality that
astropy.visualization
enhances. - scikit-image: To downsample a data array in
astropy.nddata.utils
. - setuptools: Used for discovery of
entry points which are used to insert fitters into
astropy.modeling.fitting
. - mpmath: Used for the ‘kraft-burrows-nousek’
interval in
poisson_conf_interval
. - objgraph: Used only in tests to test for reference leaks.
- mock (python <= 3.2) or unittest.mock (python > 3.3):
Used for testing the entry point discovery functionality in
astropy.modeling.fitting
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.
Installing Astropy¶
Using pip¶
To install Astropy with pip, simply run:
pip install astropy --no-deps
Warning
Users of the Anaconda python distribution should follow the instructions for Using conda.
Note
You will need a C compiler (e.g. gcc
or clang
) to be installed (see
Building from source below) for the installation to succeed.
Note
The --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.
Note
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 --user
option
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 sudo
unless you are fully aware of the risks.
Using conda¶
Astropy is installed by default with the Anaconda Distribution. To update to the latest version run:
conda update astropy
Note
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
.
Note
Attempting to use pip to upgrade your installation of Astropy may result in a corrupted installation.
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.
Note
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.
Note
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¶
Prerequisites¶
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 release. (The released 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 Linux distribution.
For Debian/Ubuntu:
sudo apt-get install python-dev
For Fedora/RHEL:
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:
xcode-select --install
Follow the onscreen instructions to install the command line tools required. Note that you do not need to install the full XCode distribution (assuming you are using MacOS X 10.9 or later).
The instructions for building Numpy from source are also a good resource for setting up your environment to build Python packages.
Obtaining the source packages¶
Source packages¶
The latest stable source package for Astropy can be downloaded here.
Development repository¶
The latest development version of Astropy can be cloned from github using this command:
git clone --recursive git://github.com/astropy/astropy.git
Note
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
Troubleshooting¶
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
installing with:
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
setup.cfg
file:
[build]
use_system_expat=1
The C libraries currently bundled with Astropy include:
Installing Astropy into CASA¶
If you want to be able to use Astropy inside CASA, the easiest way is to do so from inside CASA.
First, we need to make sure pip is installed. Start up CASA as normal, and type:
CASA <2>: from setuptools.command import easy_install
CASA <3>: easy_install.main(['--user', 'pip'])
Now, quit CASA and re-open it, then type the following to install Astropy:
CASA <2>: import pip
CASA <3>: pip.main(['install', 'astropy', '--user'])
Then close CASA again and open it, and you should be able to import Astropy:
CASA <2>: import astropy
Any astropy affiliated package can be installed the same way (e.g. the spectral-cube or other packages that may be useful for radioastronomy).
Note
The above instructions have been tested and are known to work on MacOS X with CASA 4.3.1 and Linux with CASA 4.3.1, 4.4.0, 4.5.3, and pre-releases of CASA 4.7. However, due to missing header files in CASA, they are known to not work on Linux with CASA 4.2.1 and CASA 4.6.0.
Building documentation¶
Note
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 (and its dependencies) 1.0 or later
- Graphviz
- Astropy-helpers (Astropy and most affiliated packages include this as a submodule in the source repository, so it does not need to be installed separately.)
- Pillow
- (optional) sphinx-gallery
Note
If sphinx-gallery is not installed, you will see many Sphinx warnings building the documentation, e.g.:
.../docs/coordinates/frames.rst:278: WARNING: undefined label:
sphx_glr_generated_examples_coordinates_plot_sgr-coordinate-frame.py
(if the link has no caption the label must precede a section header)
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_docs
The documentation will be built in the docs/_build/html
directory, and can
be read by pointing a web browser to docs/_build/html/index.html
.
The LaTeX documentation can be generated by using the command:
python setup.py build_docs -b latex
The LaTeX file Astropy.tex
will be created in the docs/_build/latex
directory, and can be compiled using pdflatex
.
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.
Testing a source code build of Astropy¶
The easiest way to test that your Astropy built correctly (without installing astropy) is to run this from the root of the source tree:
python setup.py test
There are also alternative methods of Running Tests. Note that you will need pytest to be installed for this to work.