yq turns structured-file edits into shell-sized commands
The yq README shows the basic appeal in one line: read .a.b[0].c from YAML with syntax familiar to jq users. The same expression language can update a file in place, select an array item, merge several documents, pull values from environment variables, or convert among YAML, JSON, XML, CSV, TOML, HCL, properties, and INI. That removes a surprising amount of throwaway Python, Ruby, or JavaScript from build scripts.
A downloadable Go binary keeps the execution model simple. There is no daemon, user account, language runtime, or remote service. The repository was 1.7 MB with 546 files in our checkout, and official binaries cover common Linux, macOS, and Windows architectures. Homebrew, snap, winget, Chocolatey, Docker, Podman, and go install provide other routes. This portability is yq's strongest practical advantage over a collection of format-specific scripts.
jq-like syntax is useful, but yq is not jq
Existing jq knowledge transfers to paths, pipes, selections, assignments, reductions, and many functions. It does not transfer perfectly. The README says yq does not yet implement everything jq does. Scripts copied from a JSON pipeline should be checked against the operator documentation and representative YAML, especially where missing nodes, tags, aliases, or multi-document streams change evaluation.
Issue 2782 gives a precise compatibility trap in version 4.53.3. Collecting a missing key normally produces an array containing null, but inside select, and, or or, the key can disappear and change the result. The report compares this with jq's behavior. A configuration gate built around optional fields could therefore select the wrong documents without producing a syntax error. Add fixtures for absence, null, false, and empty collections.
What happened when we ran it
Our sandbox installed commit c14f446 in 19 seconds and fetched 56 Go packages. The build succeeded in 31 seconds inside a fresh unprivileged Debian container with 3 CPUs and 8 GB of RAM. The project has a Dockerfile, 8 CI workflow files, and a tests directory. No secrets or network services were needed after dependencies had been resolved.
Go tests finished in 9 seconds with exit 1. Three packages passed: the main module, cmd, and pkg/yqlib. The test package failed TestFormatStringFromFilename. For file.unknown, FormatStringFromFilename returned yaml; the assertion expected unknown. That is a concrete format-detection mismatch, not a general parser or expression failure.
Only 4 package results appeared in our supplied summary, so the 3 passing results should not be inflated into a claim about every documented operator and format. The failure matters most to code that trusts automatic detection from filenames. For stdin or ambiguous extensions, the README already recommends the -p input-format flag. Explicit -p yaml, -p xml, or another known format is safer in automation than relying on a filename guess.
In-place editing preserves meaning better than exact presentation
YAML comments, anchors, aliases, tags, and style carry information that a simple JSON conversion loses. yq understands and can manipulate these features, and the README says in-place updates keep formatting and comments while acknowledging whitespace issues. That is useful for changing an image tag in a human-maintained manifest. It is not a promise that parse and print will reproduce every byte. Review diffs before committing automated rewrites.
Two open reports show the boundary. Issue 2819 says a single-quoted multiline scalar ending in a blank line loses the expected indentation when passed through yq .. Issue 2797 says some UTF-8 characters cause loaded multiline text to be emitted as a quoted single line with escaped newlines. Both concern valid content whose presentation matters to downstream tools or reviewers.
Package choice changes permissions and timezone behavior
The standalone binary has the fewest surprises. Snap uses strict confinement, so it cannot directly read root-owned files; the README shows piping privileged input into yq and writing through sponge or a temporary file. The container image runs as a non-root user. That is a sound default, though bind-mounted files must be readable and writable by the container user when -i is used.
Timezone operations require another container adjustment. The Alpine image omits timezone data, and the documented fix adds tzdata in a derived image. Podman on an SELinux host needs :z on the mounted working directory. These are packaging constraints rather than yq-language flaws, yet each can turn a correct expression into an access error or missing-timezone failure. Put the exact install form in CI documentation.
Version 4.53.6 is current, with active edge-case repair
Release 4.53.6 shipped on 2026-08-20 with a release-build fix, a line-wrapping repair, and dependency updates. The repository was pushed on 2026-08-25. It had 15,874 stars and 285 open issues and pull requests when fetched. Current pull requests addressed file-descriptor closing, integer overflow, missing keys, and output formatting, which shows maintenance continuing beyond the latest tag.
yq belongs in a developer's shell toolbox because it makes common YAML work short and readable while covering several neighboring formats. Its limits are equally concrete: partial jq compatibility, packaging-specific permissions, and imperfect style round trips. For JSON-only work, jq remains the reference. For YAML automation, yq wins when you pin a release, specify ambiguous formats, and keep golden-file tests around important edits.