{"id":2366,"library":"yq","title":"yq: Command-line YAML/XML/TOML Processor","description":"yq is a Python-based command-line processor for YAML, XML, and TOML documents, acting as a lightweight wrapper that transparently converts these formats to JSON and pipes them to the `jq` command-line tool for querying and manipulation. It's currently at version 3.4.3 and maintains an active release cadence with regular updates and fixes.","status":"active","version":"3.4.3","language":"en","source_language":"en","source_url":"https://github.com/kislyuk/yq","tags":["YAML","XML","TOML","CLI","data processing","jq","command-line tool"],"install":[{"cmd":"pip install yq","lang":"bash","label":"Install yq"}],"dependencies":[{"reason":"Required for YAML parsing and serialization.","package":"PyYAML"},{"reason":"Required for XML parsing and serialization.","package":"lxml"},{"reason":"Required for TOML parsing and serialization.","package":"tomlkit"}],"imports":[],"quickstart":{"code":"import subprocess\nimport os\n\n# Create a sample YAML file\nyaml_content = \"\"\"\nname: Jane Doe\nage: 28\ncity: San Francisco\ndetails:\n  occupation: Developer\n  hobbies: [coding, gaming]\n\"\"\"\nwith open(\"sample.yaml\", \"w\") as f:\n    f.write(yaml_content)\n\nprint(\"--- Original YAML ---\")\nprint(yaml_content)\n\n# Process the YAML file using yq to extract the name\ntry:\n    # Example 1: Get the name\n    result_name = subprocess.run(\n        [\"yq\", \".name\", \"sample.yaml\"],\n        capture_output=True, text=True, check=True\n    )\n    print(f\"\\n--- Extracted Name ---\n{result_name.stdout.strip()}\")\n\n    # Example 2: Update the age and city using a jq-like expression\n    result_updated = subprocess.run(\n        [\"yq\", '.age = 29 | .city = \"Seattle\"', \"sample.yaml\"],\n        capture_output=True, text=True, check=True\n    )\n    print(\"\\n--- Updated YAML (age 29, city Seattle) ---\")\n    print(result_updated.stdout.strip())\n\nexcept FileNotFoundError:\n    print(\"\\nError: 'yq' command not found. Please ensure yq (this Python package and the external 'jq' binary) is installed and in your system PATH.\")\nexcept subprocess.CalledProcessError as e:\n    print(f\"\\nError processing YAML with yq: {e}\")\n    print(f\"Stderr: {e.stderr.strip()}\")\nfinally:\n    # Clean up the sample file\n    if os.path.exists(\"sample.yaml\"):\n        os.remove(\"sample.yaml\")","lang":"python","description":"The `yq` library primarily provides command-line utilities (`yq`, `xq`, `tomlq`). To use it programmatically in Python, you typically invoke these commands via `subprocess`. This example demonstrates how to create a YAML file, extract a value, and perform a transformation using `yq`."},"warnings":[{"fix":"Install `jq` via your system's package manager (e.g., `brew install jq` on macOS, `sudo apt-get install jq` on Debian/Ubuntu).","message":"The `yq` Python library depends on the external `jq` command-line tool. You must have `jq` installed and available in your system's PATH for `yq` to function correctly. This is not a Python dependency.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Review outputs for YAML documents containing strings starting with '08' or '09'. If consistent non-quoted output is required, consider post-processing or adjusting input data if possible.","message":"Version 3.4.0 changed the behavior of `yq -y` to induce quoting for string scalars that start with '08' or '09' to prevent them from being interpreted as octal numbers by some YAML parsers. This might change the output format for certain string values.","severity":"breaking","affected_versions":">=3.4.0"},{"fix":"Be cautious when handling YAML/XML/TOML data that might contain strings like '08' or '09'. Ensure your version of `yq` (and `PyYAML` indirectly) handles these as strings or explicitly quote them in your source data.","message":"Versions 3.3.0 and 3.3.1 had conflicting behaviors regarding the interpretation of characters that cannot be parsed in octal as integers. Version 3.3.0 attempted to prevent this, but 3.3.1 reverted that change. This could lead to inconsistent data interpretation if documents contain strings resembling octal numbers.","severity":"gotcha","affected_versions":"3.3.0 - 3.3.1"},{"fix":"Ensure you are using `yq` version 3.2.0 or newer for improved TOML parsing capabilities, especially if round-trip fidelity is important.","message":"Earlier versions used the `toml` library for TOML processing. Version 3.2.0 switched to `tomlkit` for better round-trip preservation and more robust handling. While this was an internal change, it's good to be aware of the underlying parser for TOML files.","severity":"deprecated","affected_versions":"<3.2.0"}],"env_vars":null,"last_verified":"2026-04-09T00:00:00.000Z","next_check":"2026-07-08T00:00:00.000Z"}