Registry / serialization / yamlfix

yamlfix

JSON →
library1.19.1pypypi✓ verified 21d ago

Yamlfix is a simple, opinionated YAML formatter that automatically corrects formatting issues and preserves comments. It ensures consistent styling, adds document headers, corrects truthy strings, removes unnecessary apostrophes, and handles line endings and list styles. The library is actively maintained, with version 1.19.1 released in December 2025, and has a consistent release cadence with frequent updates.

pip install yamlfix
INSTALL
IMPORT
SIG · YAMLFIX
Y
yamlfix
serializationpythonv1.19.1
Install
5.2s avg
Import
435ms
Disk
46MB
Pass rate
10/ 10
Env Coverage10 / 10
glibc
3.93.13
musl
3.93.13
Install & Compatibility
Where this runs
tested against v1.19.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
py 3.103.95 runs
installs and imports cleanly · install 0.0s · import 0.448s · 44.6MB
glibc
py 3.103.95 runs
installs and imports cleanly · install 5.2s · import 0.422s · 44MB
46MB installed
● package 46MB
Code
Verified usage

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

fix_files
from yamlfix import fix_files
For fixing multiple YAML files programmatically.
fix_code
from yamlfix import fix_code
For fixing YAML content passed as a string.

This quickstart demonstrates how to use `yamlfix` both as a command-line tool (simulated) and programmatically using `fix_files` to modify a file in place, and `fix_code` to format a YAML string. It highlights how the tool corrects common formatting inconsistencies like indentation, missing document headers, and list styling.

import os import stat from yamlfix import fix_files, fix_code # --- CLI Usage Example --- # Create a malformed YAML file malformed_cli_yaml = """ key: value another_key: nested_value - item1 - item2 """ with open("malformed.yaml", "w") as f: f.write(malformed_cli_yaml) # Run yamlfix via CLI (simulate for quickstart) # In a real scenario, you would run: !yamlfix malformed.yaml print("\n--- CLI (Simulated) ---") print("Original malformed.yaml:") with open("malformed.yaml", "r") as f: print(f.read()) # Simulate fixing by reading, fixing with fix_code, and writing back fixed_content_cli = fix_code(malformed_cli_yaml) with open("malformed.yaml", "w") as f: f.write(fixed_content_cli) print("Fixed malformed.yaml:") with open("malformed.yaml", "r") as f: print(f.read()) # --- Programmatic Usage Example (fix_files) --- # Create another malformed YAML file malformed_file_yaml = """ list: - item_a - item_b # A comment -item_c """ with open("another_malformed.yml", "w") as f: f.write(malformed_file_yaml) print("\n--- Programmatic (fix_files) ---") print("Original another_malformed.yml:") with open("another_malformed.yml", "r") as f: print(f.read()) # Fix the file(s) programmatically fix_files(["another_malformed.yml"]) print("Fixed another_malformed.yml:") with open("another_malformed.yml", "r") as f: print(f.read()) # --- Programmatic Usage Example (fix_code) --- print("\n--- Programmatic (fix_code) ---") code_to_fix = """ key1: value1 key2: value2 """ print("Original code string:\n" + code_to_fix) fixed_code_string = fix_code(code_to_fix) print("Fixed code string:\n" + fixed_code_string) # Cleanup generated files os.remove("malformed.yaml") os.remove("another_malformed.yml")
yamlfix --version
Debug
Known issues
gotchaYamlfix can sometimes inadvertently alter the structure or quoting of certain YAML constructs, particularly multi-line strings, volumes definitions (e.g., in Docker Compose), or long keys, leading to functional changes if not carefully reviewed.
fix
Always review changes made by `yamlfix` using version control (e.g., `git diff`) before committing. Consider using `--check` flag or `fix_code` with manual comparison for critical files. Report unexpected behavior to the project's GitHub issues. Explicitly configure quoting behavior if specific styles are required (e.g., `preserve_quotes`, `quote_basic_values`).
affects: All versions
gotchaThe tool might move YAML 'shebangs' (e.g., `#!/usr/bin/env yaml`) to the left or introduce unexpected header separators (`---`) even if the file is correctly formed without one, which might break scripts relying on specific file content or existing YAML standards.
fix
If a file should not have a `---` header or a shebang needs to remain at a specific position, verify `yamlfix`'s behavior and consider excluding such files or configuring `explicit_document_start` if available. For shebangs, manual intervention or a pre-commit hook specifically for shebangs might be necessary. Check the `explicit_document_start` configuration option.
affects: All versions
gotchaConfiguration via `pyproject.toml`, `.yamlfix.toml`, or environment variables is powerful but can be overridden by conflicting settings, and values are parsed by Pydantic, which enforces type. Providing a value with the wrong type (e.g., a string for a boolean) will result in errors.
fix
Ensure configuration keys and their types strictly match those defined in the `YamlfixConfig` class. When using environment variables, be mindful that all values are initially strings and Pydantic will attempt to cast them to the expected type (e.g., 'true'/'false' to boolean, numeric strings to int/float). Consult the official documentation for available configuration options and their expected types.
affects: All versions
Errors
Common errors & fixes
ModuleNotFoundError: No module named 'yamlfix'
The yamlfix library has not been installed in the current Python environment.
fix
pip install yamlfix
yamlfix: command not found
The yamlfix command-line tool is either not installed or not in the system's PATH.
fix
pip install yamlfix (if not already installed) or ensure your Python environment's script directory is in your system's PATH.
yamlfix: error: failed to parse YAML file 'your_file.yaml': while scanning a simple key ...
The input YAML file contains syntax errors that prevent yamlfix from parsing it correctly.
fix
Correct the YAML syntax errors in 'your_file.yaml' to ensure it is valid YAML. Review the error message for specific details about the parsing issue.
yaml.parser.ParserError: while scanning a simple key
The string or file content provided to `yamlfix.fix_string()` or `yamlfix.fix_file()` via the Python API contains invalid YAML syntax.
fix
Ensure the YAML string or content of the file being processed is syntactically valid YAML. Review the error message for line and column details to pinpoint the issue.
Upgrade
Version history
1.19.1latest on PyPI · released Dec 18, 2025
Audit
Dependencies
ruyamlrequiredUsed for parsing YAML documents while preserving comments and order.
ClickrequiredUsed for creating the command-line interface.
maisonrequiredUsed for finding, reading, and parsing configuration options from files or environment variables.
Agent activity
23 hits · last 30 days
node
20
OpenAI (training)
1
Resources
yamlfix — pip install yamlfix · libregistry