Install & Compatibility
Where this runs
tested against v0.2.7 · 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.910 runs
installs and imports cleanly · install 0.0s · import 0.044s · 18.9MB
glibcpy 3.10–3.910 runs
installs and imports cleanly · install 1.8s · import 0.038s · 19MB
17MB installed
● package 17MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
YAML
✓ from ruamel.yaml import YAML
The 'jinja2' functionality is enabled by passing typ='jinja2' to the YAML constructor, not a direct import from ruamel.yaml.jinja2.
This quickstart demonstrates loading a YAML string that contains Jinja2 directives. It then modifies a value within the loaded data structure and dumps it back to `stdout`, preserving the Jinja2 template elements. It is crucial to use `YAML(typ='jinja2')` to enable the pre- and post-processing and use the *same* `YAML` instance for both loading and dumping.
import sys
from ruamel.yaml import YAML
yaml_str = """
- {{ name }}: "{% include 'ethnicity.jinja2' with context %}"
age: 43
hobbies: {% include 'hobbies.jinja2' with context %}
"""
yaml = YAML(typ='jinja2')
yaml.preserve_quotes = True
data = yaml.load(yaml_str)
data[0]['age'] = 18
yaml.dump(data, sys.stdout)
Debug
Known issues
breakingUsing different `YAML(typ='jinja2')` instances for loading and dumping will result in an `AttributeError` because the instance used for loading stores crucial internal information required for the subsequent dumping process.fixAlways use the *same* `YAML(typ='jinja2')` instance for both `load()` and `dump()` operations on a given YAML document.
affects: All versions
gotchaCertain complex Jinja2 constructs, especially those that result in invalid YAML when not rendered (e.g., `{{- with ... }}` on a line of its own, or undocumented `jinja2` constructs), may not be handled correctly by `ruamel.yaml.jinja2` and might require manual pre-processing or lead to unexpected parsing errors.fixSimplify complex Jinja2 constructs within YAML or comment them out before loading if they are not meant to be processed by `ruamel.yaml.jinja2` for modification, or preprocess the data to make the YAML valid before loading.
affects: All versions
gotchaThe installation command `pip install ruamel.yaml[jinja2]` is the recommended way to ensure `ruamel.yaml.jinja2` is correctly integrated with `ruamel.yaml`. Direct installation of `ruamel-yaml-jinja2` might not set up the necessary plugin mechanism correctly, leading to unexpected behavior or an inability to use `typ='jinja2'`.fixAlways install `ruamel.yaml.jinja2` as an extra feature of `ruamel.yaml` using `pip install 'ruamel.yaml[jinja2]'`.
affects: All versions
deprecatedThe `ruamel.yaml` project, which `ruamel.yaml.jinja2` extends, has discussed potential breaking changes regarding its PyPI package name to comply with PEP 625 (possibly changing to `ruamel_yaml`). While this specific plugin is not directly affected by a name change, its core dependency might experience installation or import path changes in the future, although `ruamel.yaml` has indicated they are trying to avoid this for older versions.fixMonitor `ruamel.yaml`'s official documentation for updates on its package name and installation procedures, especially if upgrading `ruamel.yaml` to a major new version.
affects: Future versions of ruamel.yaml (potential)
Upgrade
Version history
0.2.7latest on PyPI · released Sep 23, 2021
Audit
Dependencies
ruamel.yamlrequiredCore dependency for YAML parsing and round-trip preservation, this package is an extension.
Jinja2requiredRequired for templating functionality.