yq

What it is and what it does

yq bridges the gap between jq and non-JSON structured data formats. Using pyyaml, xmltodict, and tomlkit as runtime dependencies, yq reads YAML, XML, or TOML files, converts them to JSON internally, pipes them through jq for filtering and transformation, and optionally converts the output back to the original format. This lets you use jq's query language on YAML configurations, XML documents, and TOML files without manual conversion.

The package includes three command-line tools: yq for YAML, xq for XML, and tomlq for TOML. Roundtrip modes preserve YAML tags and styles, or XML/TOML formatting metadata. You can use it as a command-line tool or import as a Python module. The package is actively maintained, supports Python 3.8 through 3.13, and has no known security vulnerabilities.

Use it for:

• Extract or modify values in Kubernetes config files or other YAML configurations using jq filters
• Convert between YAML, XML, and TOML formats while preserving document structure and metadata
• Query and transform AWS CloudFormation templates or other XML/YAML infrastructure-as-code files
• Edit TOML configuration files in place with jq expressions, preserving comments and formatting
• Stream large XML documents without loading the full file into memory using --xml-item-depth

Worth the install?

AI-flagged interpretation of the facts on this page — verify before relying

yq is a command-line processor that applies jq filters to YAML, XML, and TOML documents, converting them to JSON for processing and optionally back to their original format.

Yes. yq is actively maintained, has low install friction, carries no known vulnerabilities, and solves a real problem: applying jq's powerful query language to YAML, XML, and TOML. The main gotcha is the external jq dependency, which must be installed separately. If you work with structured data formats beyond JSON and want jq's filtering power, this is a solid choice.

Install

yq on PyPI

pip install yq

uv add yq

poetry add yq

Installing yq

Before you install

Low install friction: pure Python wheel with four runtime dependencies (argcomplete, pyyaml, tomlkit, xmltodict). Active maintenance with a recent release 34 days ago. External system dependency: jq must be installed separately before use.

License in practice

Apache License 2.0 (permissive): you can use, modify, and distribute yq freely in commercial and private projects, with minimal restrictions beyond attribution and liability disclaimers.

Quickstart

pip install yq

# Requires jq installed separately (brew install jq, apt-get install jq, etc.)
cat input.yml | yq .foo.bar

# Convert back to YAML output
cat input.yml | yq -y .foo.bar

jq must be installed separately on your system before yq can run; see jq installation instructions for your platform.

Verify before relying

• Performance characteristics with large YAML/XML/TOML files or deeply nested structures
• Whether the -Y (roundtrip) mode's metadata injection is compatible with your specific jq filters

Package facts

Evidence: yq-4.1.2-py3-none-any.whl

Tags

More Software Development packages