SunPy: a Python package for working with solar physics data

What the SunPy core package is for

SunPy is a Python software package that, in the README's own words, "provides fundamental tools for accessing, loading and interacting with solar physics data in Python". The name of the repository, sunpy/sunpy, identifies it as the core package, with the wider SunPy project sitting around it and the affiliated packages listed separately on the project site.

The audience is solar physicists, graduate students and the people who teach them. That audience shows in the three capabilities the README lists: an interface for searching and downloading data from multiple data providers, data containers for image and time series data, and the solar coordinate frames with their associated transformations.

Those three capabilities are the whole point of the package. Solar data is scattered across archives that each have their own access model, and comparing two observations taken at different times, or from different instruments, means putting them in a common frame and often reprojecting them. A library that handles the download, the metadata parsing and the coordinate transformations is what turns a pile of FITS files into something you can plot.

The project is also organised the way a scientific community organises. It is a NumFOCUS-sponsored project with a pyOpenSci submission, a Matrix chat room, an OpenAstronomy Discourse forum, a Google Groups mailing list, a Zenodo DOI for citation, and a stable documentation site on Read the Docs. A citation guide and a CITATION.cff file sit in the repository. For a package whose output ends up in published papers, that apparatus is part of the product, not decoration around it.

How SunPy fetches and loads data

The download side is built on two libraries that do different jobs. parfive, listed with the ftp extra, is the client that searches providers and pulls files down. fsspec provides the filesystem abstraction that sits underneath the data access layer, and that single choice is what makes SunPy work with data that never touches the local disk.

That matters more than it sounds. Solar archives hold large volumes of FITS data, and the common workflow is to search an archive, look at what is available, and download a subset. With an fsspec-backed layer, a remote file can be opened in the same way as a local one, so a script that works against a downloaded directory works against a remote archive. requests is in the dependency list for the plain HTTP cases, and pyerfa handles the astronomy coordinate conversions that sit underneath SunPy's own frame definitions.

The second load is the container. A Map holds a two-dimensional solar image with its coordinate metadata, and a TimeSeries holds a series of measurements with time as the index. The README mentions both as included functionality, and the examples directory breaks them out into separate folders, which is a good indication of how central they are.

The third piece is the coordinate machinery. SunPy ships the commonly used solar frames and the transformations between them, and the topics on the package list wcs and coordinates, the two standards the astronomy ecosystem uses to describe where a pixel sits on the sky. Building on astropy means the frames compose with the wider ecosystem rather than sitting in a separate universe.

The examples directory as a map of the library

The repository's examples/ directory is the closest thing the project has to a feature list, and reading the folder names tells you what the library considers its core competencies.

There is a folder for acquiring_data, which covers the search and download path. Then map, map_transformations and time_series, the three containers and the coordinate work, each with its own set of worked examples. A plotting folder covers rendering, and a units_and_coordinates folder covers the unit and frame system. saving_and_loading_data covers serialisation, and a further folder collects longer, more complete applications.

Two folder names are more unusual and worth attention. differential_rotation suggests worked examples of the Sun's rotation, which is the effect that makes solar longitude comparisons subtle, since features do not stay at a fixed heliographic longitude. computer_vision_techniques suggests that the project also covers feature detection on solar images, which is where a lot of the interesting analysis in the field actually happens: tracking active regions, following filaments, measuring how spots evolve.

The benchmarking setup is worth noting too. The repository has a benchmarks/ directory with an asv.conf.json, which is the configuration for asv, the Python benchmarking tool, and a .test_package_pins.txt file that pins the versions of test dependencies. SunPy is a project where a change in a dependency can move a number, and that infrastructure is how the project keeps track of that.

Installing SunPy and choosing the extras

The README does not give a one-line install, and it says why: it recommends following the installation guide in the documentation, which walks through installing SunPy and all of its dependencies.

The guide matters because the runtime dependencies are not trivial. The pyproject.toml in the repository lists them, and it is a short list with some sharp edges:

dependencies = [
  "astropy>=7.0.0",
  "fsspec>=2024.9.0",
  "numpy>=1.26.0",  # Not bumping numpy to 2.0 until we need to
  "numpy>=2.3.0;python_version=='3.14'",
  "packaging>=24.1",
  "parfive[ftp]>=2.2.0",
  "pyerfa>=2.0.1.1",
  "requests>=2.33.0",
]

The astropy floor is the line that decides whether an environment is usable. astropy>=7.0.0 is a recent major version of a package with its own release schedule, and a research group with a locked, working analysis environment will find that floor is the constraint rather than SunPy itself. The numpy requirement is drawn with a marker comment, and the build backend requires numpy>=2.0.0rc1, which is a slightly odd combination of floors between the build step and the runtime.

The optional extras are grouped by capability, and the pyproject gives the exact names: asdf for the ASDF serialisation format, dask for parallel array computation, image for scipy, and jpeg2000 for glymur with lxml, which the comment explains is there because JPEG2000 files are written directly and there were version issues with lxml.

The Python requirement is requires-python = ">=3.12", although the classifier list still includes Python 3.11 alongside 3.12, 3.13 and 3.14. The classifier is the leftover, not the rule, and it is the kind of small inconsistency that makes an automated environment file wrong if you trust the wrong line.

Where SunPy is the wrong tool

The first case is general astronomy. SunPy is solar-specific, and for anything that spans stars, galaxies or spectra across wavelengths, astropy is the package built for it. The difference in approach is scope and the domain model underneath: astropy gives you a general coordinate and unit framework, while SunPy builds on top of it and adds the solar frames, the Heliographic-style transformations, the FITS-derived Map and TimeSeries containers, and the providers that serve solar instruments. Choosing SunPy for non-solar work means carrying solar assumptions you do not need.

The second case is instrument-level work. SunPy is a data analysis layer, not a reduction pipeline. If your problem is turning raw detector counts into a calibrated image, that is upstream of this package, and the data providers here hand you science-ready products rather than building them.

The third case is production service work, and the reason is version cadence. The release history shows v7.1.1 on 2026-04-29, v8.0.0 on 2026-06-30 and v8.0.1 on 2026-10-09, with the last push on 2026-10-15. A major release every few months, paired with a moving astropy floor, is fine for research code that is re-run and checked. It is a different proposition for a service that has to keep running unattended.

The fourth case is data volume. The library is built for analysis of observations, with dask available as an extra for larger arrays. Very large statistical surveys of a catalogue rather than a time series of images are a different problem, and the parallel path is an extra you opt into rather than something you get by default.

Release practice, community rules and the licence

The cadence is regular and the version numbers carry meaning. v8.0.0 landed on 2026-06-30, v8.0.1 on 2026-10-09, and the repository is not archived, with the last push on 2026-10-15. Between major versions the patch releases do the work of dependency compatibility fixes, which is the pattern you want in a package whose dependencies move on their own schedule.

The repository shows the discipline behind that. There is a CHANGELOG.rst and a changelog/ directory, tox.ini for environment management, pytest.ini for the test configuration, a .pre-commit-config.yaml, and both .flake8 and .ruff.toml alongside .isort.cfg and .codespellrc, which is a picture of a project that has moved to modern Python tooling without throwing away the old configuration. A .cruft.json file suggests the project is templated from an upstream cookiecutter, so a new release branch inherits a known-good structure. .zenodo.json and CITATION.cff exist so that the software itself is citable, and the README asks users to cite SunPy in publications.

The licence deserves a note, because the two sources do not agree. The release listing for this project shows BSD-2-Clause, while the license field in pyproject.toml says BSD-3-Clause, and the repository carries a LICENSE.rst plus a licenses/ directory. Both are permissive and both are close, but anyone who needs the exact text for an internal compliance check should read the LICENSE.rst in the tree rather than a summary of it, since the two-clause and three-clause versions differ in their patent and attribution clauses.

One community rule is unusual enough to be worth knowing before contributing. The README has a section on the usage of generative AI, asking that if you use AI tools while developing code or documentation you fully understand the proposed changes and can explain why they are the correct approach, and pointing to a fair and appropriate AI usage page in the developer guide. The rest of the contribution path is conventional: the Developers Guide, the chat room, the issues page for known outstanding items, and a Newcomers' guide for first-time contributors.

Editorial conclusion

SunPy is the right choice for a researcher or graduate student who needs reproducible access to solar observations and the transformations that make them comparable, and for teaching, since the examples directory doubles as a curriculum. It is the wrong choice for general astronomy, for instrument-level pipeline work, or for a production service that cannot tolerate a major release every year. Verify first that your instrument and data products are covered by the providers, install the version whose astropy requirement matches your environment, and read the changelog for the 8.0 series before migrating code written against 7.x.

Frequently asked questions

Official sources

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