{"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":"python","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,"search_vec":"'3.4.3':54 'act':23 'activ':58 'base':12 'cadenc':60 'cli':69 'command':3,14,42,74 'command-lin':2,13,41,73 'convert':30 'current':51 'data':70 'document':22 'fix':65 'format':32 'jq':40,72 'json':34 'lightweight':26 'line':4,15,43,75 'maintain':56 'manipul':48 'pipe':36 'process':71 'processor':6,16 'python':11 'python-bas':10 'queri':46 'regular':62 'releas':59 'toml':21,68 'tool':44,76 'transpar':29 'updat':63 'version':53 'wrapper':27 'xml':19,67 'yaml':18,66 'yaml/xml/toml':5 'yq':1,7","created_at":"2026-04-09T18:54:56.346989+00:00","updated_at":"2026-04-17T01:09:18.147371+00:00","problems":[{"fix":"Install yq using `pip install yq` and ensure your system's PATH environment variable includes the directory where pip installs executables (e.g., `~/.local/bin` on Linux/macOS or `C:\\PythonXX\\Scripts` on Windows).","cause":"The yq executable is not in your system's PATH, typically due to an incomplete installation or the pip binary directory not being included in PATH.","error":"yq: command not found"},{"fix":"Install `jq` separately for your operating system (e.g., `brew install jq` on macOS, `sudo apt-get install jq` on Debian/Ubuntu, `choco install jq` on Windows) and verify it's in your PATH.","cause":"The `kislyuk/yq` tool relies on the `jq` command-line utility for processing JSON, which is not installed or not accessible in your system's PATH.","error":"Error: `jq` command not found"},{"fix":"Wrap your `jq` query in a single set of quotes (e.g., `yq '.foo | .bar' my_file.yaml`) to ensure it is parsed as one argument.","cause":"You have provided multiple positional arguments where `yq` expects a single `jq` query string, followed by optional input file paths.","error":"yq: error: argument 'query': expected one argument"},{"fix":"Pass `jq` flags within the `jq` query string (e.g., `yq -y '.foo | @text' my_file.yaml` for raw text output), or pipe `yq`'s output to `jq` directly (e.g., `yq .foo my_file.yaml | jq -r .`).","cause":"You are attempting to pass `jq`-specific flags (like `-r` for raw output, or `-c` for compact output) directly to `yq`, which only recognizes its own limited set of flags.","error":"yq: error: unrecognized arguments: -r"}],"ecosystem":"pypi","meta_description":null,"install_score":null,"quickstart_score":null,"quickstart_tag":null,"pypi_latest":null,"cli_name":"yq","cli_version":"yq 3.4.3","type":"library","homepage":null,"github":"https://github.com/kislyuk/yq","docs":null,"changelog":null,"pypi":"https://pypi.org/project/yq/","npm":null,"openapi_spec":null,"status_page":null,"smithery":null,"categories":["data","devops"],"base_url":null,"auth_type":null,"provenance":{"verified_status":null,"verified_at":null,"last_verified":"2026-04-09","next_check":"2026-07-08","install_tag":null}}