Install & Compatibility
Where this runs
tested against v0.2.15 · 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.95 runs
installs and imports cleanly · install 0.0s · import 0.000s · 19.5MB
glibcpy 3.10–3.95 runs
installs and imports cleanly · install 1.8s · import 0.000s · 21MB
18MB installed
● package 18MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
YAML
✓ from ruamel.yaml import YAML
ruamel-yaml-clib is a backend for ruamel.yaml and is not imported directly by user code. ruamel.yaml detects and utilizes ruamel-yaml-clib automatically if installed, unless pure Python parsing is explicitly requested (e.g., YAML(pure=True)).
This quickstart demonstrates basic loading and dumping of YAML using `ruamel.yaml`. If `ruamel-yaml-clib` is installed, `ruamel.yaml` will use its C extensions for improved performance without requiring any changes to user code. To explicitly use the pure Python implementation, instantiate `YAML(pure=True)`.
import sys
from ruamel.yaml import YAML
# ruamel.yaml will automatically use ruamel-yaml-clib if available
# For pure Python implementation, use: yaml = YAML(pure=True)
yaml = YAML()
data = {
'name': 'Alice',
'age': 30,
'details': {
'city': 'New York',
'occupation': 'Engineer'
}
}
# Dump to string
import io
string_stream = io.StringIO()
yaml.dump(data, string_stream)
yaml_string = string_stream.getvalue()
print('--- Dumped YAML ---')
print(yaml_string)
# Load from string
loaded_data = yaml.load(yaml_string)
print('--- Loaded Data ---')
print(loaded_data['name'])
print(loaded_data['details']['city'])
# Demonstrate round-trip preservation (if ruamel.yaml is configured for it)
config_yaml_str = """
# My config
key: value # inline comment
list:
- item1
- item2
"""
rt_yaml = YAML()
rt_data = rt_yaml.load(config_yaml_str)
rt_data['list'].append('item3')
output_stream = io.StringIO()
rt_yaml.dump(rt_data, output_stream)
print('--- Round-trip preserved ---')
print(output_stream.getvalue())
Debug
Known issues
breakingStarting with `ruamel.yaml` version 0.19.1, the library no longer automatically installs `ruamel-yaml-clib` as a direct dependency. To ensure the C-accelerated backend is installed, users must explicitly install `ruamel.yaml` with the `libyaml` extra, e.g., `pip install ruamel.yaml[libyaml]`.fixInstall `ruamel.yaml` with the `libyaml` extra: `pip install ruamel.yaml[libyaml]`. If `ruamel-yaml-clib` is installed directly, `ruamel.yaml` will still detect and use it.
affects: ruamel.yaml >= 0.19.1
gotchaCompilation issues may occur with newer `clang` versions (e.g., >= 16) when building `ruamel-yaml-clib` from source. This typically manifests in environments like FreeBSD where `clang` is the default compiler.fixWorkarounds may involve patching the source code or using an older/different compiler toolchain. Refer to `ruamel.yaml.clib` issue trackers or community discussions for specific patches.
affects: All versions when compiling with affected clang versions
gotchaWhen `ruamel-yaml-clib` is active (using the C-based SafeLoader/SafeDumper within `ruamel.yaml`), the `yaml.indent` setting applies uniformly to both mappings and sequences. The pure Python implementation of `ruamel.yaml` offers more granular control over indentation styles.fixIf different indentation settings for mappings and sequences are required, instantiate `ruamel.yaml.YAML(pure=True)` to force the pure Python implementation.
affects: All versions
deprecatedThe maintainer has indicated that `ruamel.yaml.clib` will not receive fixes for free-threading issues. `ruamel.yaml.clibz` is the designated replacement for future free-threading support. While `ruamel.yaml.clib` remains functional, this signals a future transition.fixFor applications requiring free-threading support with `ruamel.yaml`'s C backend in the future, monitor `ruamel.yaml`'s documentation for guidance on adopting `ruamel.yaml.clibz`.
affects: All versions
breaking`ruamel.yaml` is not installed. Attempting to import `ruamel.yaml` without it being present in the environment will result in a `ModuleNotFoundError`.fixInstall the package using pip: `pip install ruamel.yaml`.
affects: All versions
breakingThe `ruamel.yaml` package was not found, resulting in a `ModuleNotFoundError`. This indicates the library was not successfully installed in the environment.fixEnsure `ruamel.yaml` is installed in the test environment using `pip install ruamel.yaml`. Verify installation logs for any errors if the command was executed.
affects: All versions
Upgrade
Version history
0.2.15latest on PyPI · released Nov 16, 2025
Audit
Dependencies
No dependency data recorded yet.