install.rst

Installation

Overview

The first step to installing astropy is to ensure that you have a Python environment which is isolated from your system Python installation. This is important because astropy has many dependencies, and you do not want to accidentally break your system by installing incompatible versions of these dependencies.

For this installation guide we use the conda package manager provided by miniforge. This is a popular choice and works well, especially for newcomers. It is easy to install and use on all platforms and it makes it easy to install the latest Python version. If you already have a miniforge-based Python environment then you can skip to :ref:`installing-astropy-with-pip`.

Another option for more experienced users is a virtual environment manager such as the Python standard library venv module. There are numerous resources available to help you set up a virtual environment in this manner if you choose this option.

Note

We do not recommend using astropy with an existing miniconda or Anaconda Python distribution. The astropy package provided by Anaconda Inc. in the defaults channel can be outdated and these distributions can require a license for use at a large organisation. Instead, use miniforge as described below.

Once you have a Python environment set up, you will install astropy using |pip| or |conda|. Here we document using |pip| because it is easier to install the optional dependencies, but feel free to use |conda| if you prefer.

Install miniforge

You will install Python by first installing miniforge. This provides the conda package manager with the default remote package repository set to the community-led conda-forge channel.

In a new terminal (miniforge Prompt on Windows) run conda list to test that the install has worked.

Create Python Environment

To create a new Python environment for astropy and other packages, start by launching a terminal (under a UNIX-like system) or the miniforge Prompt (under Windows). Now we will create and activate a new virtual environment to install astropy into:

$ conda create --channel conda-forge  --name astropy python
$ conda activate astropy

In this case the environment we have created is named astropy but you can use any name you like.

In the future when you make a new terminal, you will need to run conda activate astropy to activate this environment.

Install astropy

You can install astropy and the rest of your dependencies using either |pip| or |conda|. Both methods are fully supported and will work well.

Warning

Once you have created your base Python environment with |conda|, you should try to stick with one method for installing new packages in your environment. In particular, |conda| is not aware of packages installed with |pip| and may overwrite them.

Using pip

To install astropy and your choice of :ref:`dependencies <astropy-main-req>`, run one of the following commands:

python -m pip install astropy                # Minimum required dependencies
python -m pip install "astropy[recommended]" # Recommended dependencies
python -m pip install "astropy[all]"         # All optional dependencies
python -m pip install "astropy[dev_all]"     # All optional and test dependencies

In most cases, this will install a pre-compiled version of astropy (called a wheel). However, if you are installing astropy on an uncommon platform, astropy will be installed from a source file. In this unusual case you will need a C compiler to be installed (see Build from source below) for the installation to succeed.

Warning

Do not install astropy or other packages using sudo or any elevated privilege.

Using conda

To install astropy and the minimal set of required dependencies, run:

conda install --channel conda-forge astropy

Install the recommended dependencies with:

conda install --channel conda-forge scipy matplotlib

Install the optional dependencies with:

conda install --channel conda-forge ipython jupyter dask h5py pyarrow \
   beautifulsoup4 html5lib bleach pandas sortedcontainers pytz jplephem mpmath \
   asdf-astropy bottleneck fsspec s3fs certifi

Testing

You can test that your newly installed version of astropy is working via the documentation on how to test your installed version of astropy.

Requirements

astropy has the following strict requirements:

• |Python| |minimum_python_version| or later
• |NumPy| |minimum_numpy_version| or later
• |PyERFA| |minimum_pyerfa_version| or later
• PyYAML |minimum_pyyaml_version| or later
• |packaging| |minimum_packaging_version| or later

astropy also depends on a number of other packages for optional features. The following are particularly recommended:

• |SciPy| |minimum_scipy_version| or later: To power a variety of features in several modules.
• |Matplotlib| |minimum_matplotlib_version| or later: To provide plotting functionality that astropy.visualization enhances.

The further dependencies provide more specific features:

• 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.
• 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.
• sortedcontainers for faster SCEngine indexing 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.
• 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-astropy |minimum_asdf_astropy_version| 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 requests package).
• pyarrow |minimum_pyarrow_version| or later: To read/write :class:`~astropy.table.Table` objects from/to Parquet files.
• |fsspec| |minimum_fsspec_version| or later: Enables access to :ref:`subsets of remote FITS files <fits_io_cloud>` without having to download the entire file.
• |s3fs| |minimum_s3fs_version| or later: Enables access to files hosted in AWS S3 cloud storage.

However, note that these packages require installation only if those particular features are needed. astropy will import even if these dependencies are not installed.

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| |minimum_ipython_version| or later: Used for testing the notebook interface of ~astropy.table.Table.
• coverage: Used for code coverage measurements.
• skyfield: Used for testing Solar System coordinates.
• sgp4: Used for testing satellite positions.
• tox: Used to automate testing and documentation builds.

Build from Source

If you want to build the code from source, follow the instructions for :ref:`contributing_environment`. Note that instead of cloning from your fork, you can choose to clone from the main repository:

git clone https://github.com/astropy/astropy.git
cd astropy

Building the documentation is typically not necessary unless you are developing code or documentation or do not have internet access, because the stable, latest, and archived versions of Astropy's documentation are available at docs.astropy.org . The process is described in Building the Documentation from Source.

Test Source Code Build

{% if is_development %}

The easiest way to run the tests in a source checkout of astropy is to use tox:

tox -e test-alldeps

There are also alternative methods of :ref:`running-tests` if you would like more control over the testing process.

{%else%}

See the latest documentation on how to run the tests in a source checkout of astropy.

{%endif%}

Install Pre-built Development Version

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:

python -m pip install --upgrade --extra-index-url https://pypi.anaconda.org/astropy/simple astropy --pre

The extra index URL tells pip to check the pip index on pypi.anaconda.org, where the nightlies are stored, and the --pre command tells pip to install pre-release versions (in this case .dev releases).

You can test this installation by running the tests as described in the section Running tests on an installed astropy.