asdf

library5.3.1pypypi✓ verified 85d ago

Python implementation of the ASDF Standard, a language-agnostic serialization format for scientific data. It handles serialization of Python objects (including NumPy arrays, Astropy objects, and custom types) into ASDF files, which are YAML-based with support for binary data. The library is actively developed with several releases per year, and the current version is 5.2.0.

serialization data

pip install asdf

github ↗package ↗homepage ↗docs ↗

INSTALL

IMPORT

SIG · ASDF

asdf

serializationpythonv5.3.1

Install

5.9s avg

Import

809ms

Disk

109MB

Pass rate

5/ 10

Env Coverage5 / 10

glibc

3.9–3.13

musl

3.9–3.13

Install & Compatibility

Where this runs

tested against v5.3.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

musl

glibc

py 3.10

4/8 runs

✓ 6.29s

py 3.11

4/8 runs

✓ 5.75s

py 3.12

4/8 runs

✓ 4.91s

py 3.13

4/8 runs

✓ 5.11s

py 3.9

4/8 runs

✓ 7.55s

109MB installed

● package 109MB

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

AsdfFile

✓ from asdf import AsdfFile

✗ from asdf.asdffile import AsdfFile

While technically correct, the top-level import is preferred and canonical.

open

✓ import asdf; asdf.open(...)

This quickstart demonstrates how to create a simple ASDF data structure, write it to a file, and then read the data back. It uses a dictionary for the tree structure and includes a NumPy array, a common use case for ASDF.

import asdf import numpy as np import os # Create some data tree = { 'scientific_name': 'M42', 'coordinates': { 'ra': 83.822083, 'dec': -5.391111 }, 'data': np.array([[1, 2], [3, 4]], dtype=np.int64) } # Create an ASDF file object ff = asdf.AsdfFile(tree) # Define file path file_path = "example.asdf" # Write the file ff.write_to(file_path) print(f"ASDF file written to {file_path}") # Read the file back with asdf.open(file_path) as af: print(f"Read data:\n{af.tree['data']}") print(f"Read coordinates: {af.tree['coordinates']}") # Clean up the created file os.remove(file_path)

asdf --version

Debug

Known issues

breakingThe `AsdfFile.tree` attribute is now read-only. Direct assignment like `ff.tree = new_tree` will raise an `AttributeError` in `asdf` 5.0 and later.

fix

Instead of reassigning `ff.tree`, use `ff.update(new_dict)` to update the tree's content or create a new `AsdfFile` instance with the modified tree.

affects: >=5.0.0

breakingMinimum Python version increased to 3.10. Users on older Python versions will encounter `ImportError` or environment resolution issues.

fix

Upgrade your Python environment to version 3.10 or newer. Refer to the official Python documentation for upgrade instructions.

affects: >=5.0.0

breakingThe `AsdfFile.open()` function no longer supports `mode='r+'` for read-write operations. Using it will raise a `ValueError` in `asdf` 4.0 and later.

fix

Open the file in read mode (`'r'`), make any necessary modifications to the loaded data, and then write the data to a new file or overwrite the existing one using `AsdfFile.write_to()`.

affects: >=4.0.0

gotchaCustom Python types require explicit registration with ASDF. Without proper registration (via an `Extension`, `Tag`, and `Converter`), ASDF may not be able to serialize/deserialize them correctly, often leading to `ValidationError` or loss of type information.

fix

Implement a custom `asdf.extension.Extension` (which typically includes a `Tag` and `Converter`) and register it using `asdf.converters.add_extension` or by installing a package that provides the extension.

affects: all

Errors

Common errors & fixes

AttributeError: property 'tree' of 'AsdfFile' object has no setter

Attempting to directly replace the entire `AsdfFile.tree` attribute in `asdf` version 5.0 or later.

fix

Use `asdf_file.update(new_dict)` to modify the contents of the tree, or create a new `asdf.AsdfFile` instance if a complete replacement of the tree structure is needed.

asdf.exceptions.ValidationError: <unknown>: 'tag:stsci.edu:asdf/custom-type-1.0.0' is not a valid ASDF tag.

ASDF cannot find a registered converter for a custom Python object type that was attempted to be serialized or deserialized.

fix

Ensure that the custom type has a corresponding `asdf.extension.Tag` and `asdf.extension.Converter` registered with ASDF. This usually involves defining an `asdf.extension.Extension` and adding it to the ASDF context.

ValueError: 'r+' is not a supported mode for AsdfFile.open()

Using `mode='r+'` when opening an ASDF file with `asdf.open()` in versions 4.0 or newer.

fix

Remove the `mode='r+'` argument. Open the file in read-only mode (`'r'`), then if modifications are required, load the data, apply changes, and save the updated data to a new ASDF file using `AsdfFile.write_to()`.

Upgrade

Version history

5.3.1latest on PyPI · released Jun 8, 2026

Audit

Dependencies

numpyrequiredEssential for serialization and deserialization of array data.

pyyamlrequiredUsed for parsing and emitting YAML content.

jsonschemarequiredRequired for ASDF schema validation.

astropyoptionalWidely used for astronomical data, provides many types directly supported by ASDF.

Agent activity

38 hits · last 30 days

node

OpenAI (training)

Resources

githubhttps://github.com/asdf-format/asdf ↗

packagehttps://pypi.org/project/asdf/ ↗

homepagehttps://asdf-standard.readthedocs.io ↗

docshttps://asdf.readthedocs.io/en/stable/ ↗