If you are new to Python and/or do not have familiarity with Python virtual environments, then we recommend starting by installing the Anaconda Distribution. This works on all platforms (linux, Mac, Windows) and installs a full-featured scientific Python in a user directory without requiring root permissions.
Users of the Anaconda Python distribution should follow the instructions for Using Conda.
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]
In most cases, this will install a pre-compiled version (called a wheel) of
astropy, but if you are using a very recent version of Python, if a new version
of astropy has just been released, or if you are building astropy for a platform
that is not common, astropy will be installed from a source file. Note that in
this case you will need a C compiler (e.g.,
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
Alternatively, if you intend to do development on other software that uses
astropy, such as an affiliated package, consider installing
into a virtualenv.
Do not install
astropy or other third-party packages using
unless you are fully aware of the risks.
astropy using conda run:
conda install astropy
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
is released and when a package is available for conda. You can check
for the list of available versions with
conda search astropy.
It is highly recommended that you install all of the optional dependencies with:
conda install -c astropy -c defaults \ scipy h5py beautifulsoup4 html5lib bleach pyyaml pandas sortedcontainers \ pytz matplotlib setuptools mpmath bottleneck jplephem asdf
To also be able to run tests (see below) and support Building Documentation use the
following. We use
pip for these packages to ensure getting the latest
releases which are compatible with the latest
pip install pytest-astropy sphinx-astropy
Attempting to use pip to upgrade your installation
astropy itself may result in a corrupted installation.
Testing an Installed
astropy has the following strict requirements:
astropy also depends on other packages for optional features:
scipy >=1.1 or later: To power a variety of features in several modules.
xmllint: To validate VOTABLE XML files. This is a command line tool installed outside of Python.
sortedcontainers for faster
SCEngineindexing engine with
Table, 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.
asdf >=2.6 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.
certifi: Useful when downloading files from HTTPS or FTP+TLS sites in case Python is not able to locate up-to-date root CA certificates on your system; this package is usually already included in many Python installations (e.g., as a dependency of the
However, note that these packages require installation only if those particular
features are needed.
astropy will import even if these dependencies are not
The following packages can optionally be used when testing:
pytest-xdist: Used for distributed testing.
pytest-mpl: Used for testing with Matplotlib figures.
objgraph: Used only in tests to test for reference leaks.
coverage: Used for code coverage measurements.
skyfield: Used for testing Solar System coordinates.
spgp4: Used for testing satellite positions.
tox: Used to automate testing and documentation builds.
Building from Source¶
You will need a compiler suite and the development headers for Python in order
astropy. You do not need to install any other specific build
dependencies (such as Cython or
jinja2) since these are
declared in the
pyproject.toml file and will be automatically installed into
a temporary build environment by pip.
Prerequisites for Linux¶
On Linux, using the package manager for your distribution will usually be the
easiest route to making sure you have the prerequisites to build
order to build from source, you will need the Python development
package for your Linux distribution, as well as pip.
sudo apt-get install python3-dev python3-numpy-dev python3-setuptools cython3 python3-jinja2 python3-pytest-astropy
sudo yum install python3-devel python3-numpy python3-setuptools python3-Cython python3-jinja2 python3-pytest-astropy
Building the developer version of
astropy may require
newer versions of the above packages than are available in
your distribution’s repository. If so, you could either try
a more up-to-date distribution (such as Debian
or install more up-to-date versions of the packages using
conda in a virtual environment.
Prerequisites for Mac OS X¶
On MacOS X you will need the XCode command line tools which can be installed using:
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.
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 the
Developer Documentation. The present document covers only the basics necessary to
Building and Installing¶
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 .
astropy in develop/editable mode – this then 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
astropy into the default
site-packages directory, you can try
pip install . --user
which will install into a default directory in your home directory.
External C Libraries¶
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 set environment variables with the
1 when building/installing
For example, to build
astropy using the system’s expat parser
ASTROPY_USE_SYSTEM_EXPAT=1 pip install -e .
To build using all of the system libraries, use:
ASTROPY_USE_SYSTEM_ALL=1 pip install -e .
The C libraries currently bundled with
cextern/wcslib/READMEfor the bundled version. To use the system version, set
cextern/cfitsio/changes.txtfor the bundled version. To use the system version, set
cextern/expat/READMEfor the bundled version. To use the system version, set
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 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
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
CASA <2>: import astropy
astropy affiliated package can be installed the same way (e.g. the
spectral-cube or other
packages that may be useful for radio astronomy).
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.
Installing pre-built Development Versions of
Most nights a development snapshot of
astropy will be compiled.
This is useful if you want to test against a development version of astropy but
do not want to have to build it yourselves. You can see the
available astropy dev snapshots page
to find out what is currently being offered.
Installing these “nightlies” of
astropy can be achieved by using
$ pip install --extra-index-url=https://pkgs.dev.azure.com/astropy-project/astropy/_packaging/nightly/pypi/simple/ --pre astropy
The extra index URL tells
pip to check the
pip index on Azure Pipelines, where the
nightlies are built, and the
--pre command tells
pip to install pre-release
versions (in this case
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. The easiest way to build the documentation is to use tox as detailed in
Building. If you are happy to do this, you can skip the rest
of this section.
On the other hand, if you wish to call Sphinx manually to build the documentation, you will need to make sure that a number of dependencies are installed. If you use conda, the easiest way to install the dependencies is with:
conda install -c astropy sphinx-astropy
Without conda, you install the dependencies by specifying
astropy with pip:
pip install -e '.[docs]'
You can alternatively install the sphinx-astropy package with pip:
pip install 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
astropyand 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
Graphviz - generate inheritance graphs (available as a conda package or a system install but not in pip)
Both of the
pip install methods above do not include Graphviz. If you do not install this package separately
then the documentation build process will produce a very large number of
lengthy warnings (which can obscure bona fide warnings) and also not
generate inheritance graphs.
There are two ways to build the Astropy documentation. The easiest way is to
execute the following tox command (from the
astropy source directory):
tox -e build_docs
If you do this, you do not need to install any of the documentation dependencies
as this will be done automatically. The documentation will be built in the
docs/_build/html directory, and can be read by pointing a web browser to
Alternatively, you can do:
cd docs make html
And the documentation will be generated in the same location. Note that this uses the installed version of astropy, so if you want to make sure the current repository version is used, you will need to install it with e.g.:
pip install -e .[docs]
before changing to the
In the second way, LaTeX documentation can be generated by using the command:
The LaTeX file
Astropy.tex will be created in the
directory, and can be compiled using
Reporting Issues/Requesting Features¶
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.