yq — jq for YAML, JSON, XML, TOML, and .properties

Introduction

yq (Mike Farah's Go version — the most popular fork) brings jq's legendary query language to YAML, JSON, XML, TOML, .properties, and CSV. If you've ever had to patch a Kubernetes manifest or grab a value from a Helm chart, yq is the tool.

With over 15,000 GitHub stars, yq is essentially required for any DevOps pipeline that touches YAML. It's a single Go binary with no dependencies, runs everywhere, and handles the multi-document + comments + anchors quirks that make YAML hard.

What yq Does

yq applies jq-like expressions to structured documents. Read values, set values, delete keys, merge files, convert between formats (YAML ↔ JSON ↔ XML ↔ TOML), traverse with path expressions — everything jq does for JSON, plus format-specific features like preserving YAML comments and anchors.

Architecture Overview

Input file (YAML/JSON/XML/TOML/properties)
      |
[Parser — choose decoder]
      |
[Expression Evaluator]
   jq-compatible syntax:
   .key, .[0], .[], |, select, map, reduce, as, ireduce
      |
[Mutations]
   assign, delete, merge (with *+ or ea)
      |
[Encoder]
   output in any supported format
   preserves comments + anchors (YAML)
      |
Stdout or in-place update (-i)

Self-Hosting & Configuration

# Read nested values
yq '.metadata.labels.app' k8s/deploy.yaml

# Multi-value / array access
yq '.spec.template.spec.containers[].image' k8s/deploy.yaml

# Update and write back (preserves comments!)
yq -i '.spec.replicas = 10 | .metadata.labels.env = "prod"' k8s/deploy.yaml

# Merge patches (Kustomize-style)
yq ea '. as $item ireduce ({}; . * $item)' base.yaml overlay.yaml > merged.yaml

# Convert formats
yq -oj '.' config.yaml > config.json    # YAML -> JSON
yq -p json -oy '.' data.json > data.yaml  # JSON -> YAML
yq -p xml -oy '.' feed.xml > feed.yaml    # XML -> YAML

# Delete fields matching a pattern
yq -i 'del(.spec.template.spec.containers[].resources)' deploy.yaml

# Set values from shell vars
IMAGE="myorg/api:v1.2.3" yq -i '.spec.containers[0].image = strenv(IMAGE)' deploy.yaml

Key Features

• Multi-format — YAML, JSON, XML, TOML, .properties, CSV
• jq-compatible syntax — path expressions, pipes, select, map, reduce
• In-place edits — -i flag preserves comments, anchors, formatting
• Multi-document YAML — handle --- separator files natively
• Merge + patch — compose configs, overlay environments
• Format conversion — one flag changes output encoding
• strenv / env helpers — pull values from shell environment
• Cross-platform — single Go binary on macOS/Linux/Windows

Comparison with Similar Tools

FAQ

Q: Which yq do I want — mikefarah or kislyuk? A: Usually mikefarah's Go version (brew install yq). Kislyuk's Python version is a jq-wrapper — pick it only if you want strict jq semantics and are fine with a Python runtime. Most CI/CD uses mikefarah's.

Q: Does yq preserve YAML comments? A: Yes — mikefarah's version preserves comments, anchors, and formatting on in-place edits. That's one of its biggest advantages for config management.

Q: Can I use yq in a GitHub Actions workflow? A: Yes. yq is pre-installed on GitHub-hosted runners. Use yq -i '...' to patch manifest files before deploying.

Q: What about very large YAML files? A: Multi-document YAML (thousands of --- separated docs) works but can be slow. For very large files, consider yq -e to evaluate per-document or pipe through --split-exp.

Sources

• GitHub: https://github.com/mikefarah/yq
• Docs: https://mikefarah.gitbook.io/yq
• Author: Mike Farah
• License: MIT