Install & Compatibility
Where this runs
tested against v0.7.1 · pip install
no network on importno background threads
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
muslpy 3.10–3.920 runs
installs and imports cleanly · install 0.0s · import 0.833s · 163.5MB
glibcpy 3.10–3.920 runs
installs and imports cleanly · install 7.7s · import 0.807s · 164MB
170MB installed
● package 170MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
AsdfFile
✓ from asdf import AsdfFile
Main class for creating and managing ASDF files.
open
✓ from asdf import open
Function for loading an ASDF file.
SkyCoord
✓ from astropy.coordinates import SkyCoord
Example of an Astropy object commonly serialized (no direct asdf-astropy import needed, as plugins auto-register).
This example demonstrates how to create an Astropy `SkyCoord` object, embed it within an ASDF tree, save it to a `.asdf` file, and then load it back. The `asdf-astropy` package automatically registers the necessary converters upon installation, allowing `asdf` to seamlessly handle Astropy types.
import asdf
from astropy.coordinates import SkyCoord
from astropy import units as u
# Create an Astropy object (e.g., a SkyCoord)
coord = SkyCoord(ra=10.68458 * u.deg, dec=41.26917 * u.deg, frame='icrs')
# Create an ASDF tree (a dictionary mapping keys to objects)
tree = {'my_coordinate': coord}
# Create an AsdfFile object
ff = asdf.AsdfFile(tree)
# Save the ASDF tree to a file
file_path = 'my_astropy_coord.asdf'
ff.write_to(file_path)
print(f"Saved SkyCoord to {file_path}")
# Load the ASDF file and access the object
with asdf.open(file_path) as af:
loaded_coord = af['my_coordinate']
print(f"Loaded SkyCoord: {loaded_coord}")
assert loaded_coord == coord
Debug
Known issues
breakingasdf-astropy 0.11.0 drops support for Python versions older than 3.11. Users on Python 3.8 or 3.10 must upgrade their Python environment to use this version.fixUpgrade Python to 3.11 or newer (`python -m pip install --upgrade python` or via conda/system package manager).
affects: <0.11.0
breakingThe `astropy.io.misc.asdf` module's functionality is superseded by `asdf-astropy`. When `asdf-astropy` is installed, Astropy's built-in plugins are ignored. The `astropy.io.misc.asdf` module will be removed in a future version of Astropy.fixEnsure `asdf-astropy` is installed and rely on its auto-registered converters rather than explicit imports or usage of `astropy.io.misc.asdf`.
affects: All versions when `astropy.io.misc.asdf` is used
gotchaRunning tests directly via `astropy.test()` can fail when `asdf-astropy` is installed, due to conflicts in test discovery or execution. Running `pytest` from the command line, however, typically works correctly.fixInstead of `astropy.test()`, use `pytest` from your terminal (e.g., `pytest --pyargs astropy` or `pytest path/to/astropy/tests`).
affects: All versions
gotchaWhen saving custom Astropy map subclasses to ASDF, they may be loaded back as `sunpy.map.GenericMap` instead of their specific class if the custom subclass is not registered with `sunpy.map.Map` upon loading, or if ASDF is invoked before the custom map sources are imported.fixEnsure all custom Astropy/SunPy map subclasses are imported and registered *before* any ASDF file operations (loading or saving) involving them.
affects: All versions
Errors
Common errors & fixes
Running tests from astropy.test() fails when asdf-astropy is installed #16165
Conflict or incompatibility in how astropy's internal test runner interacts with the `asdf-astropy` package's test setup, specifically affecting doctests.
fixUse the `pytest` command-line tool to run tests instead of `astropy.test()`. For example: `pytest --pyargs astropy`.
asdf.exceptions.ValidationError: tag:stsci.edu:asdf/core/xxx-1.0.0 is not a valid tag
Attempting to serialize an Astropy object for which `asdf-astropy` does not have a registered converter, or `asdf-astropy` is not correctly installed/loaded. The 'xxx' would be a specific type like 'complex' or a custom Astropy object.
fixEnsure `asdf-astropy` is installed in your environment (`pip install asdf-astropy`). If using custom Astropy-like classes, verify that `asdf-astropy` supports them or consider writing a custom ASDF converter.
UserWarning: The plugins in astropy.io.misc.asdf are superseded by asdf-astropy
This is a warning indicating that you have both the older, built-in Astropy ASDF plugins and `asdf-astropy` installed. `asdf-astropy` takes precedence.
fixThis is generally not a critical error, but it signals a deprecated path. Ensure you are relying on `asdf-astropy` for serialization. The `astropy.io.misc.asdf` module will eventually be removed from Astropy, so transition any explicit usage away from it.
Upgrade
Version history
0.11.0latest on PyPI · released Mar 27, 2026
Audit
Dependencies
asdfrequiredCore ASDF library for file format parsing and serialization. asdf-astropy provides converters for Astropy types to be used with ASDF.
astropyrequiredThe core astronomy library whose objects (e.g., coordinates, units, models) are serialized by asdf-astropy.