Install & Compatibility
Where this runs
tested against v0.1.0 · 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.940 runs
installs and imports cleanly · install 0.0s · import 0.000s · 20.5MB
glibcpy 3.10–3.940 runs
installs and imports cleanly · install 1.9s · import 0.000s · 22MB
19MB installed
● package 19MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
load_yaml
✓ from annotatedyaml import load_yaml
✗ from annotated_yaml import load
dump
✓ from annotatedyaml import dump
YAMLException
✓ from annotatedyaml import YAMLException
This quickstart demonstrates basic loading and dumping of YAML data. For secrets support, install `annotatedyaml[secrets]` and set the `ENCRYPTED_SECRETS_KEY` environment variable.
import io
from annotated_yaml import load, dump
yaml_config_str = io.StringIO("""
app_name: MyConfigApp
version: 1.0.0
database:
host: localhost
port: 5432
features:
- user_profiles
- notifications
""")
# Load configuration from a string (or file-like object)
config = load(yaml_config_str)
print(f"Application Name: {config['app_name']}")
print(f"Database Host: {config['database']['host']}")
print(f"Enabled Features: {', '.join(config['features'])}")
# You can also dump the configuration back to YAML
print("\n--- Dumped YAML ---")
dump(config, io.StringIO().write) # Dumps to a string, or sys.stdout to print directly
Debug
Known issues
breakingAnnotated YAML requires Python 3.13 or newer. Projects on older Python versions (e.g., 3.10, 3.11, 3.12) are not supported and will fail during installation or runtime.fixUpgrade your Python environment to 3.13 or higher. If unable to upgrade, consider using an older version of `annotatedyaml` if available and compatible, or an alternative YAML library.
affects: >=1.0.0
breakingVersion 1.0.0 introduced significant internal refactoring and updated its core `ruamel.yaml` dependency to `>=0.18.0`. While primary `load`/`dump` APIs are generally stable, users relying on specific `ruamel.yaml` internals or behaviors might experience subtle changes from pre-1.0 versions.fixThoroughly test existing YAML configurations and loading logic when upgrading from `0.x.x` to `1.0.0+`. Consult the `ruamel.yaml` changelog for `0.18.0` if you suspect behavior differences.
affects: >=1.0.0
gotchaHandling encrypted secrets requires the `cryptography` library to be installed (`pip install annotatedyaml[secrets]`) and the `ENCRYPTED_SECRETS_KEY` environment variable to be set with a valid key. Missing either will lead to runtime errors when accessing `!secret` values.fixEnsure you install `annotatedyaml[secrets]`. Before loading YAML with secrets, set `os.environ["ENCRYPTED_SECRETS_KEY"]` to your decryption key. Generate a strong key for production use.
affects: All versions with secrets support
gotchaAnnotated YAML uses `ruamel.yaml` internally, which has some behavioral differences compared to `PyYAML` (e.g., preserving comments, handling duplicate keys differently). Users accustomed to `PyYAML` might encounter unexpected parsing results or serialization outputs.fixFamiliarize yourself with `ruamel.yaml`'s documentation, especially regarding round-trip preservation and comment handling. Test your YAML inputs thoroughly with `annotatedyaml`.
affects: All versions
Upgrade
Version history
1.0.2latest on PyPI · released Oct 4, 2025
Audit
Dependencies
ruamel.yamlrequiredCore YAML parsing and dumping engine.
cryptographyoptionalRequired for encrypting and decrypting secrets within YAML files.