astropy
has the following strict requirements:
- Python |minimum_python_version| or later
- `Numpy`_ |minimum_numpy_version| or later
- pytest 3.1 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 :class:`~astropy.table.Table` objects from/to HDF5 files.
- BeautifulSoup: To read :class:`~astropy.table.table.Table` objects from HTML files.
- html5lib: To read :class:`~astropy.table.table.Table` objects from HTML files using the pandas reader.
- bleach: Used to sanitize text when disabling HTML escaping in the :class:`~astropy.table.Table` HTML writer.
- PyYAML: To read/write :class:`~astropy.table.Table` objects from/to the Enhanced CSV ASCII table format and to serialize mixins for various formats.
- xmllint: To validate VOTABLE XML files. This is a command line tool installed outside of Python.
- pandas: To convert :class:`~astropy.table.Table` objects from/to pandas DataFrame objects. Version 0.14 or higher is required to use the :ref:`table_io_pandas` I/O functions to read/write :class:`~astropy.table.Table` objects.
- bintrees for faster
FastRBT
andFastBST
indexing engines withTable
, although these will still be slower in most cases than the default indexing engine. - sortedcontainers for faster
SCEngine
indexing engine withTable
, although this may still be slower in some cases than the default indexing engine. - pytz: To specify and convert between timezones.
- jplephem: To retrieve JPL ephemeris of Solar System objects.
- matplotlib 2.0 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 ~astropy.stats.poisson_conf_interval.
- asdf 2.3 or later: Enables the serialization of various Astropy classes into a portable, hierarchical, human-readable representation.
- bottleneck: Improves the performance of sigma-clipping and other functionality that may require computing statistics on arrays with NaN values.
And the following packages can optionally be used when testing:
- pytest-astropy: See :ref:`sourcebuildtest`
- pytest-xdist: Used for distributed testing.
- pytest-mpl: Used for testing with Matplotlib figures.
- objgraph: Used only in tests to test for reference leaks.
- IPython: Used for testing the notebook interface of ~astropy.table.Table.
- coverage: Used for code coverage measurements.
- skyfield: Used for testing Solar System coordinates.
However, note that these packages require installation only if those particular
features are needed. astropy
will import even if these dependencies are not
installed.
Warning
Users of the Anaconda Python distribution should follow the instructions for :ref:`anaconda_install`.
To install astropy
with pip, run:
pip install astropy
If you want to make sure none of your existing dependencies get upgraded, you can also do:
pip install astropy --no-deps
On the other hand, if you want to install astropy
along with all of the
available optional dependencies, you can do:
pip install astropy[all]
Note that you will need a C compiler (e.g. gcc
or clang
) to be installed
(see Building from source below) for the installation to succeed.
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
:ref:`virtualenv<using-virtualenv>`.
Do not install astropy
or other third-party packages using sudo
unless you are fully aware of the risks.
astropy
is installed by default with the Anaconda Distribution. 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
.
Warning
Attempting to use pip to upgrade your installation
of astropy
may result in a corrupted installation.
The easiest way to test if your installed version of astropy
is running
correctly is to use the :ref:`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 :ref:`sourcebuildtest` for how to run the tests from the
source code directory, or :ref:`running-tests` for more details.
You will need a compiler suite and the development headers for Python and
NumPy in order to build astropy
.
If you are building the latest developer version rather than using a stable release, you will also need Cython (v0.21 or later) and jinja2 (v2.7 or later) installed. The released packages have the necessary C files packaged with them, and hence do not require Cython.
On Linux, using the package manager for your distribution will usually be the
easiest route to making sure you have the prerequisites to build astropy
. In
order to build from source, you will 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
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 a good resource for setting up your environment to build Python packages.
The latest stable source package for astropy
can be downloaded here.
The latest development version of astropy
can be cloned from GitHub
using this command:
git clone --recursive git://github.com/astropy/astropy.git
If you wish to participate in the development of astropy
, see
:ref:`developer-docs`. This document covers only the basics necessary to
installing astropy
.
astropy
uses the Python built-in distutils framework for building and
installing, and requires the setuptools package.
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 and install astropy
(from the root of the source tree):
pip install .
If you install in this way and you make changes to the code, you will need to re-run the install command for changes to be reflected. Alternatively, you can use:
pip install -e .
which installs astropy
in develop/editable mode, which means that changes in
the code are immediately reflected in the installed version.
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:
pip install . --user
which will install into a default directory in your home directory.
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 command line 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:
- wcslib see
cextern/wcslib/README
for the bundled version. - cfitsio see
cextern/cfitsio/changes.txt
for the bundled version. - erfa see
cextern/erfa/README.rst
for the bundled version. - expat see
cextern/expat/README
for the bundled version.
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 then 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 subprocess, sys CASA <3>: subprocess.check_call([sys.executable, '-m', 'pip', 'install', '--user', 'astropy'])
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 radio astronomy).
Note
The above instructions have not been tested on all systems.
We know of a few examples that do work, but that is not a guarantee
that this will work on all systems. If you install astropy
and begin to
encounter issues with CASA, please look at the known CASA issues
and if you do not encounter your issue there, please post a new one.
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, including those in :ref:`astropy-main-req`. The easiest
way to install the extra dependencies for documentation is to install
the sphinx-astropy package,
either with pip:
pip install sphinx-astropy
or with Conda:
conda install -c astropy sphinx-astropy
In addition to providing configuration common to packages in the Astropy ecosystem, this package also serves as a way to automatically get the main dependencies, including:
- Sphinx - the main package we use to build the documentation
- astropy-sphinx-theme -
the default 'bootstrap' theme used by
astropy
and a number of affiliated packages - sphinx-automodapi - an extension that makes it easy to automatically generate API documentation
- sphinx-gallery - an extension to generate example galleries
- numpydoc - an extension to parse docstrings in NumPyDoc format
- pillow - used in one of the examples
In addition, if you want inheritance graphs to be generated, you will need to make sure that Graphviz is installed. If you install sphinx-astropy with Conda, Graphviz will automatically get installed, but if you use pip, you will need to install Graphviz separately as it is not a Python package.
There are two ways to build the Astropy documentation. The first 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
.
In the second way, 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
.
As mentioned above, building the documentation depends on a number of sphinx extensions and other packages. Since it is not always possible to know which package is causing issues or would need to have a new feature implemented, you can open an issue in the core astropy package issue tracker. However, if you wish, you can also open issues in the repositories for some of the dependencies:
- For requests/issues related to the appearance of the docs (e.g. related to the CSS), you can open an issue in the astropy-sphinx-theme issue tracker.
- For requests/issues related to the auto-generated API docs which appear to be general issues rather than an issue with a specific docstring, you can use the sphinx-automodapi issue tracker.
- For issues related to the default configuration (e.g which extensions are enabled by default), you can use the sphinx-astropy issue tracker.
Before running tests, it is necessary to make sure that Astropy's test dependencies are installed. This can be done with the following command:
pip install pytest-astropy
More information on what the pytest-astropy
package provides can be found
in :ref:`testing-dependencies`.
The most convenient 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 :ref:`running-tests`. Note that you will need pytest to be installed for this to work.