---
id: yq
version: "4.1.2"
license: Apache Software License
license_treatment: permissive
maintenance: active
---

# yq — Command-line YAML/XML processor - jq wrapper for YAML/XML documents

License: permissive · Maintenance: active · Downloads: 4.4M/mo

## 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 above — 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

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

- License: Apache Software License (permissive)
- Python support: supports_current
- Install friction: low
- Maintenance: active
- Downloads: 4.4M/month (top 5,000 on PyPI)
- Known vulnerabilities: none known

## Tags

yaml command line processor, jq wrapper for yaml, query yaml files cli, xml json conversion tool, toml command line editor, yaml xml toml processor, structured data cli filter, cli-tool, data-format-conversion, config-management

[View on SkillFed](https://skillfed.io/packages/yq) · [View on PyPI](https://pypi.org/project/yq/)