Astropy: the core Python library for astronomy data, units and coordinates

What Astropy solves that plain NumPy cannot

A magnitude, a Julian Date, a pixel coordinate and a sky position are all numbers, and all of them are meaningless without a frame of reference. Astropy exists to carry that reference alongside the value. The project describes itself as a community effort to develop a single core package for astronomy in Python and to encourage interoperability between packages used in the field, and the repository topics list the concrete areas: units, coordinates, time, tables, FITS, WCS and modeling.

The audience is narrow by design. If you are reducing spectra, cross-matching a catalogue against a sky survey, converting between UTC and barycentric time, or writing a FITS file another observatory will read, Astropy is the layer that keeps the conventions consistent. If you are training a generic model on tabular data that happens to come from a telescope, most of the library is overhead. The keyword list in pyproject.toml (astronomy, astrophysics, cosmology, units, table, wcs, samp, coordinate, fits, modeling) is a fair summary of the scope and also of the boundary.

How the package is assembled: a compiled core with a data dependency

Astropy is not pure Python. The top level of the repository contains a cextern directory for bundled C sources, and setup.py calls get_extensions() from extension_helpers to collect the compiled extension modules. The same file sets NPY_TARGET_VERSION to NPY_1_25_API_VERSION and NPY_NO_DEPRECATED_API to NPY_1_7_API_VERSION on any extension that includes the NumPy headers, which is how the build pins the C API it targets. A pip install therefore needs a working compiler unless a wheel matches your platform.

The runtime dependencies are short: numpy>=2.0, pyerfa>=2.0.1.3, PyYAML>=6.0.1, packaging>=25.0, and astropy-iers-data>=0.2026.7.27.0.56.29. That last one is the interesting part. Earth rotation and leap-second tables change, and they are shipped as a separate versioned data package rather than baked into the library, so the accuracy of time and coordinate transforms depends on how current that package is in your environment. The recommended extras add scipy>=1.13, matplotlib>=3.8.4 and narwhals>=1.42.0, and the comment in pyproject.toml notes narwhals is kept in sync with a dependency group named dataframe.

One build detail worth knowing: setup.py defines InstallWithStubs and EditableInstallWithStubs, which call create_stubs from astropy.units.typing_utils after installation to generate type stubs. Type information for units is produced at install time, not shipped as a static file.

Installing Astropy and the first thing to do with it

The README gives one install command and points at the install guide in the docs for anything more detailed. The Python floor is 3.12: pyproject.toml sets requires-python to >=3.12 and classifies 3.12, 3.13 and 3.14.

pip install astropy

That is the whole documented install path for users. The README does not list platform-specific commands, conda channels or wheel names, so the install guide at docs.astropy.org is where anything beyond this line lives. If you want the optional dependency set the project labels recommended (scipy, matplotlib, narwhals), pyproject.toml declares it under [project.optional-dependencies], which is the standard extras mechanism, but the README itself does not spell out an extras install command, so check the install guide before assuming the spelling.

For development rather than use, the README points at a dev container in .devcontainer/devcontainer.json and a GitHub Codespaces badge, which is the shortest path to a working build environment without assembling compilers by hand. The README does not document a first-use example, so the practical starting point is the documentation rather than anything in the repository root.

Where Astropy is the wrong dependency

The compiled extensions are the first constraint. On a platform without a matching wheel, installation compiles C and Cython sources, which is slow and fails outright on a machine with no toolchain. Container images built for slimness routinely hit this.

The second constraint is the IERS data package. Time and coordinate transformations rely on astropy-iers-data being reasonably current, and the pin in pyproject.toml is a floor, not a ceiling. A long-lived virtual environment with a frozen lockfile will keep producing answers computed from old Earth orientation parameters, and the library will not warn you that the tables have aged. That is a reproducibility feature in some workflows and a silent accuracy problem in others.

The third is scope. Astropy does not replace a dataframe library, a plotting library or a general statistics package. The recommended extras pull in scipy and matplotlib, and narwhals appears specifically for dataframe interchange. If your task is fitting a curve to a CSV, NumPy and SciPy are the smaller answer. The modeling and fitting subpackage exists, but reaching for it when you have no astronomical units, no FITS file and no sky coordinates means paying the build cost for nothing.

Astropy against SciPy and the wider scientific Python stack

The honest comparison is not Astropy versus another astronomy library. It is Astropy versus assembling the same behaviour from NumPy, SciPy and a handful of file parsers yourself.

The difference in approach is that SciPy solves general numerical problems and says nothing about what a number means. Astropy attaches physical units, reference frames and time scales to values and then makes arithmetic respect them. A quantity in Astropy carries its unit through multiplication and division; a bare float in SciPy does not, so unit errors surface as wrong answers rather than exceptions. The same split applies to FITS: you can parse the header blocks by hand, and people did for years, but Astropy maintains that reader as part of its core.

What you give up is weight. SciPy installs without a data package that needs refreshing, and without a compiled astronomy core. For a service that does statistics on instrument telemetry, SciPy plus pandas is the leaner choice. For anything that has to agree with another observatory's output, Astropy is the cheaper choice in the long run.

Maintenance, releases and the BSD-3-Clause licence

The repository is not archived, and the last push was on 2026-09-22. Recent releases are v8.0.1 and v7.2.2, both dated 2026-07-08, with v8.0.0 on 2026-06-17. Two maintained release lines are visible in that list, so a project pinned to 7.x is not stranded, but the 8.x line is where new work lands.

Upgrade cost is dominated by the Python floor and the NumPy floor. requires-python is >=3.12 and numpy>=2.0, which means an environment still on Python 3.11 or NumPy 1.x cannot take a current release without upgrading both. The dependency on astropy-iers-data is also a moving part: a version bump there changes the numbers your time and coordinate conversions return, which can shift regression baselines even when your own code has not changed. Pin it deliberately if you compare outputs across runs.

Licensing is a 3-clause BSD style license, recorded in pyproject.toml as license = "BSD-3-Clause" with license-files pointing at LICENSE.rst and licenses/*.rst. A permissive licence of that shape generally allows commercial and closed-source use with attribution, but the repository also bundles C sources under cextern and carries a licenses directory, so anyone redistributing a binary should read those files rather than assume a single set of terms. That is a description of what the repository contains, not legal advice.

Editorial conclusion

Adopt Astropy if your work involves astronomical quantities, FITS files, sky coordinates or time scales, and you want the conventions the field already agrees on. Do not adopt it for general numeric work, plotting or dataframe wrangling where NumPy, SciPy, Matplotlib or narwhals alone are enough, since Astropy would only add a dependency. Before committing, verify the Python floor in pyproject.toml (requires-python is >=3.12), the pin on astropy-iers-data, and whether your pipeline needs the recommended extras scipy, matplotlib and narwhals.

Frequently asked questions

Official sources

1. astropy/astropy on GitHub
2. License: BSD-3-Clause
3. Project website
4. README
5. Releases