mikefarah/yq

What it does

yq is a command-line processor for YAML, JSON, XML, CSV, TSV, TOML, HCL, INI and properties data. Its expression syntax follows jq, so users who already know jq can reuse basic traversal, selection and assignment patterns across formats. It is written in Go and ships as a dependency-free binary, which makes it a practical fit for shell scripts, CI jobs and container images that need to read or rewrite structured configuration without a language runtime.

The tool is aimed at developers, DevOps engineers and anyone who edits configuration files from the terminal. Beyond simple reads, it can update files in place, keep YAML comments and formatting where possible, merge documents, split output across files, handle front matter, and convert between supported formats.

Quick start

Install via Homebrew on macOS or Linux:

brew install yq

Or download a release binary for your platform from the latest release page. A Linux x86_64 binary can be placed on PATH with:

wget https://github.com/mikefarah/yq/releases/latest/download/yq_linux_amd64 -O /usr/local/bin/yq && chmod +x /usr/local/bin/yq

Given a YAML file file.yaml, read a nested value:

yq '.a.b[0].c' file.yaml

Edit it in place:

yq -i '.a.b[0].c = "cool"' file.yaml

Convert YAML to JSON:

yq -o json file.yaml

Format is usually inferred from the file extension or STDIN; -p/--input-format and -o/--output-format override detection explicitly. More command syntax is in the usage section, with recipes for common transformations.

Use constraints

• YAML comments and whitespace are preserved as far as possible, but not every case is handled correctly.
• yq follows YAML 1.2, where yes and no are not booleans; files relying on YAML 1.1 boolean behavior need attention.
• The syntax resembles jq but is not fully jq-compatible; some flags, such as slurp semantics, differ.
• The Snap package runs under strict confinement, so reading or writing root-owned files requires piping through sudo or a temporary file.
• The official Docker image no longer runs as root by default; use --user root or a Dockerfile USER root step when extra packages are needed.
• The container image does not include timezone data, so the tz operator needs tzdata installed.

HotRepo's take

On the Go daily list for 2026-11-07, the project recorded 16,233 stars and gained 7 stars, placing 7th for that day. Those numbers describe a single snapshot rather than a trend, but they match a long-running utility that sits in the daily toolchain of many Go and Kubernetes users rather than a fast-rising new project.

The discussion around the 2023 Hacker News thread is more revealing than the star count: commenters debated how yq handled tricky YAML constructs such as anchors and unquoted version strings (thread, example comment), and others compared it with gojq over jq compatibility and key-order preservation. The practical takeaway is that yq is a mature, widely used formatter/editor, but users should expect occasional YAML edge cases and verify behavior against their own files.