Install & Compatibility
Where this runs
tested against v3.9.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.910 runs
installs and imports cleanly · install 0.0s · import 0.124s · 21.3MB
glibcpy 3.10–3.910 runs
installs and imports cleanly · install 2.0s · import 0.117s · 22MB
20MB installed
● package 20MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
YAMLPath
✓ from yamlpath import YAMLPath
Processor
✓ from yamlpath.processor import Processor
YAMLPathException
✓ from yamlpath.enums import YAMLPathException
✗ from yamlpath.exceptions import YAMLPathException
Exceptions are primarily exposed via `yamlpath.enums` for consistent access, though they also exist in `yamlpath.exceptions`.
This quickstart demonstrates how to load YAML data using `ruamel.yaml`, create `YAMLPath` objects for specific nodes, and then use `Processor` to get, set, and append values within the data structure. A logger is required for `Processor`.
import io
from ruamel.yaml import YAML
from yamlpath import YAMLPath
from yamlpath.processor import Processor
import logging
# Configure a basic logger (required by Processor)
logger = logging.getLogger()
logger.setLevel(logging.INFO)
yaml_data = """
config:
name: My App
version: 1.0.0
features:
- auth
- logging
settings:
debug: false
"""
# Load YAML data
yaml = YAML()
data = yaml.load(io.StringIO(yaml_data))
# Initialize Processor with the data and logger
processor = Processor(logger, data)
# Example 1: Get a value
path_to_name = YAMLPath("$.config.name")
for value, parent, key in processor.get_nodes(path_to_name):
print(f"Current config name: {value}")
# Example 2: Set a value
path_to_version = YAMLPath("$.config.version")
processor.set_value(path_to_version, "1.1.0")
print(f"Set config version to 1.1.0")
# Example 3: Add an item to a list
path_to_features = YAMLPath("$.config.features")
processor.append_value(path_to_features, "analytics")
print(f"Added 'analytics' to features")
# Output the modified YAML
output_stream = io.StringIO()
yaml.dump(data, output_stream)
print("\nModified YAML:\n" + output_stream.getvalue())
yamlpath --version
Debug
Known issues
breakingSupport for Python 3.6 was dropped. Python 3.7 support is 'tepid' and not fully guaranteed. Users on these versions must upgrade Python or pin an older `yamlpath` version.fixUpgrade Python to 3.8+ (3.10+ recommended) or downgrade `yamlpath` to <3.8.2.
affects: 3.8.2 and newer
gotchaWhen using `ruamel.yaml` (which `yamlpath` relies on), YAML timestamp values are often forced to UTC during loading, potentially stripping original timezone information.fixBe aware of this behavior when dealing with timezone-specific timestamps. If original timezone is critical, custom pre/post-processing may be needed.
affects: All versions using `ruamel.yaml`
gotchaWhen outputting JSON via command-line tools like `yaml-set` or `yaml-merge`, the default output is a single-line document. For pretty-printed JSON, a specific option is required.fixUse the `--json-indent` or `-J` option with an integer value (e.g., `--json-indent 2`) to specify the indentation level for JSON output.
affects: 3.8.0 and newer
breakingFor developers using EYAML integration, Ruby 3.3 is now the minimum supported version for development due to end-of-life status of older Ruby versions. This mainly affects testing and development environments.fixEnsure your development environment uses Ruby 3.3 or newer if you are working with EYAML.
affects: 3.9.0 and newer
Errors
Common errors & fixes
TypeError: 'collections.OrderedDict' object has no attribute 'insert'
Attempting to update bare Python `dict` or `collections.OrderedDict` data structures directly, which lack the `insert` method required by `ruamel.yaml` for certain operations. This was partially removed and then restored in 3.6.9 but still indicates a mismatch if not using `ruamel.yaml` objects.
fixAlways load YAML/JSON data using `ruamel.yaml.YAML().load()` to ensure `ruamel.yaml`'s enhanced data structures (e.g., `ruamel.yaml.comments.CommentedMap`) are used, which support the necessary methods.
Command 'yaml-merge' with Array/Array-of-Hash data in RHS causes interminable loop or maxed CPU.
A bug (Issue #220) in `yaml-merge` where novel `mergeat` paths with Array or Array-of-Hash data in the right-hand-side (RHS) document could lead to an infinite loop.
fixUpgrade `yamlpath` to version 3.8.1 or newer, where this bug was resolved.
Package 'yamlpath' is missing required ruamel.yaml patch 'yamlpath.patches.timestamp'.
Version 3.6.6 shipped with a broken package that unexpectedly omitted a critical `ruamel.yaml` patch.
fixDo not use `yamlpath` version 3.6.6. Upgrade to 3.6.7 or newer to get the corrected package.
Upgrade
Version history
3.9.1latest on PyPI · released May 2, 2026
Audit
Dependencies
ruamel.yamlrequiredCore dependency for YAML/JSON parsing and manipulation.
python-dateutilrequiredUsed for date/time object handling within YAML data.