yq
Command-line YAML/XML processor - jq wrapper for YAML/XML documents
Decision gist · record as of 2026-08-14
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.AI-flagged interpretation of the facts on this page — verify before relying
Before you install
- jq must be installed separately on your system before yq can run; see jq installation instructions for your platform.
- Low install friction: pure Python wheel with four runtime dependencies (argcomplete, pyyaml, tomlkit, xmltodict).
- Active maintenance with a recent release 34 days ago.
License · maintenance · safety
Apache Software License (permissive) — 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.
last release 2026-07-11 (34 days) · last repo commit 2026-07-11 · 2,965 stars
0 known vulnerabilities (OSV.dev, 2026-08-14) · 4,422,596 downloads/mo, #2,308 on PyPI
Alternatives
Verify before relying
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- 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
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 on it.
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
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.
jq must be installed separately on your system before yq can run; see jq installation instructions for your platform.
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.barVerify 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 the current Python release >=3.8 |
| Install friction | Low. Pure-Python wheel |
| Runtime dependencies | 4 packagesargcompletepyyamltomlkitxmltodict |
| Maintenance | Actively maintained 34 days since the last release |
| Last repo commit | |
| First released | |
| Downloads | 4,422,596 / month, #2,308 on PyPI 30-day window, as of 2026-08-14 |
| Known vulnerabilities | None known OSV.dev, checked 2026-08-14 |
| Classifiers | Development Status :: 5 - Production/StableIntended Audience :: DevelopersLicense :: OSI Approved :: Apache Software LicenseOperating System :: MacOS :: MacOS XOperating System :: POSIXProgramming Language :: PythonProgramming Language :: Python :: 3Programming Language :: Python :: 3.10Programming Language :: Python :: 3.11Programming Language :: Python :: 3.12Programming Language :: Python :: 3.13Programming Language :: Python :: 3.8Programming Language :: Python :: 3.9Programming Language :: Python :: Implementation :: CPythonProgramming Language :: Python :: Implementation :: PyPyTopic :: Software DevelopmentTopic :: Software Development :: Libraries :: Python Modules |
Evidence: yq-4.1.2-py3-none-any.whl
Tags
Let your AI agent find packages like this
Example. Real query, live index.
You found this page by searching. An agent finds it by wishing: SkillFed indexes 14,416 PyPI packages by what they can do, searchable in plain language.
wish › “yaml command line processor”
- yqyq is a command-line processor that applies jq filters to YAML, XML,…
- jinjanatorA command-line tool that renders Jinja2 templates using data from…
- docutilsDocutils converts plaintext documentation in reStructuredText format…
Give your agent the search over MCP, or paste the wish link into any chat.
More Software Development packages
Provides backported and experimental type hints for Python 3.9+, allowing use of newer typing features on older Python versions and enabling early experimentation with type system PEPs before they enter the standard library.
NumPy provides an N-dimensional array object and a comprehensive suite of mathematical, linear algebra, Fourier transform, and random number functions for scientific computing in Python.
FastAPI is a Python web framework for building REST APIs using type hints, with automatic request validation, serialization, and interactive API documentation.
Provides a way to document function parameters, class attributes, return types, and variables inline using Python's `Annotated` type hint syntax instead of traditional docstrings.
Typer builds command-line applications from Python functions using type hints, automatically generating help text, argument parsing, and shell completion.
Install it if you are building CLIs in Python.
Distlib provides low-level packaging utilities for building, distributing, and managing Python software—including metadata handling, version specifiers, wheel support, script installation, and dependency resolution.
See also jq · niet · sceptre-file-resolver · dmiparser · xmltojson · yamlpath · sceptre-cmd-resolver · PyYAML · codemod-yaml · pybtex