{"id":4861,"library":"yamlfix","title":"Yamlfix","description":"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.","status":"active","version":"1.19.1","language":"en","source_language":"en","source_url":"https://github.com/lyz-code/yamlfix","tags":["yaml","formatter","linter","automation","code quality","cli"],"install":[{"cmd":"pip install yamlfix","lang":"bash","label":"Install with pip"}],"dependencies":[{"reason":"Used for parsing YAML documents while preserving comments and order.","package":"ruyaml","optional":false},{"reason":"Used for creating the command-line interface.","package":"Click","optional":false},{"reason":"Used for finding, reading, and parsing configuration options from files or environment variables.","package":"maison"}],"imports":[{"note":"For fixing multiple YAML files programmatically.","symbol":"fix_files","correct":"from yamlfix import fix_files"},{"note":"For fixing YAML content passed as a string.","symbol":"fix_code","correct":"from yamlfix import fix_code"}],"quickstart":{"code":"import os\nimport stat\nfrom yamlfix import fix_files, fix_code\n\n# --- CLI Usage Example ---\n# Create a malformed YAML file\nmalformed_cli_yaml = \"\"\"\nkey: value\n  another_key:    nested_value\n- item1\n-    item2\n\"\"\"\n\nwith open(\"malformed.yaml\", \"w\") as f:\n    f.write(malformed_cli_yaml)\n\n# Run yamlfix via CLI (simulate for quickstart)\n# In a real scenario, you would run: !yamlfix malformed.yaml\nprint(\"\\n--- CLI (Simulated) ---\")\nprint(\"Original malformed.yaml:\")\nwith open(\"malformed.yaml\", \"r\") as f:\n    print(f.read())\n\n# Simulate fixing by reading, fixing with fix_code, and writing back\nfixed_content_cli = fix_code(malformed_cli_yaml)\nwith open(\"malformed.yaml\", \"w\") as f:\n    f.write(fixed_content_cli)\n\nprint(\"Fixed malformed.yaml:\")\nwith open(\"malformed.yaml\", \"r\") as f:\n    print(f.read())\n\n# --- Programmatic Usage Example (fix_files) ---\n# Create another malformed YAML file\nmalformed_file_yaml = \"\"\"\nlist:\n- item_a\n  - item_b\n  # A comment\n  -item_c\n\"\"\"\n\nwith open(\"another_malformed.yml\", \"w\") as f:\n    f.write(malformed_file_yaml)\n\nprint(\"\\n--- Programmatic (fix_files) ---\")\nprint(\"Original another_malformed.yml:\")\nwith open(\"another_malformed.yml\", \"r\") as f:\n    print(f.read())\n\n# Fix the file(s) programmatically\nfix_files([\"another_malformed.yml\"])\n\nprint(\"Fixed another_malformed.yml:\")\nwith open(\"another_malformed.yml\", \"r\") as f:\n    print(f.read())\n\n# --- Programmatic Usage Example (fix_code) ---\nprint(\"\\n--- Programmatic (fix_code) ---\")\ncode_to_fix = \"\"\"\n  key1:  value1\nkey2: value2\n\"\"\"\nprint(\"Original code string:\\n\" + code_to_fix)\nfixed_code_string = fix_code(code_to_fix)\nprint(\"Fixed code string:\\n\" + fixed_code_string)\n\n# Cleanup generated files\nos.remove(\"malformed.yaml\")\nos.remove(\"another_malformed.yml\")","lang":"python","description":"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."},"warnings":[{"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`).","message":"Yamlfix 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.","severity":"gotcha","affected_versions":"All versions"},{"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.","message":"The 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.","severity":"gotcha","affected_versions":"All versions"},{"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.","message":"Configuration 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.","severity":"gotcha","affected_versions":"All versions"}],"env_vars":null,"last_verified":"2026-04-12T00:00:00.000Z","next_check":"2026-07-11T00:00:00.000Z"}