mikefarah.gitbook.io

yq is a command-line processor that borrows jq's filter syntax but applies it to YAML, JSON, INI, XML, properties, CSV, and TSV files. If you already know jq, most common expressions — .a.b[0].c, assignments like .a.b[0].c = "cool", and strenv() for environment variables — carry over directly. The gaps are at the edges: yq does not yet implement everything jq does, and its handling of comments and whitespace, while deliberate, is not exhaustive. The sections below cover where the two tools align, where they diverge, and what to check before relying on yq for a given task.

Where yq and jq Align

yq's documentation describes it as using "jq like syntax" while working across YAML and other formats, not just JSON. In practice this means:

• Path expressions work the same way. yq '.a.b[0].c' file.yaml reads a nested value, and piping from STDIN with yq '.a.b[0].c' < file.yaml behaves as you would expect from jq.
• In-place updates are a first-class operation: yq -i '.a.b[0].c = "cool"' file.yaml rewrites the file directly.
• Environment variable injection uses the same strenv() function: NAME=mike yq -i '.a.b[0].c = strenv(NAME)' file.yaml.
• Multi-file merging is supported through load() and reduce expressions, e.g. yq -n 'load("file1.yaml") * load("file2.yaml")', or glob-based merging with yq ea '. as $item ireduce ({}; . * $item)' path/to/*.yml.

The documentation states that yq "does support the most common operations and functions, and more is being added continuously." So for everyday read, update, and merge work, the jq mental model transfers without much friction.

Where yq Diverges from jq

The most important difference is scope of formats. jq is a JSON processor; yq is built for YAML first and extends to JSON, XML, INI, properties, CSV, and TSV. If your pipeline is JSON-only, jq remains the more complete implementation. If your pipeline touches YAML — Kubernetes manifests, CI configs, application settings — yq is the tool that understands the format natively rather than requiring a JSON round-trip.

A second difference is distribution. yq is written in Go, so the documentation notes you can "download a dependency free binary for your platform and you are good to go," with additional options through package managers, Docker, and Podman. That matters in minimal containers or air-gapped environments where installing a runtime is inconvenient.

Known Limitations to Plan Around

The documentation's "Known Issues / Missing Features" section names two concrete caveats:

1. Comment and whitespace preservation is best-effort. yq "attempts to preserve comment positions and whitespace as much as possible, but it does not handle all scenarios," with a pointer to the underlying go-yaml v3 library for details. If your YAML files carry meaningful comments — annotated configs, documented manifests — verify the output after an in-place edit rather than assuming comments survive untouched.
2. PowerShell quoting is problematic. The docs note that "Powershell has its own... opinions on quoting yq." On Windows, expect to adjust quoting or escape characters when passing filters, and consult the project's tips and tricks page for common workarounds.

Beyond these, the docs are explicit that yq "doesn't yet support everything jq does." The safe approach: if a filter depends on an advanced jq builtin, test it against your actual yq version before committing it to a script. The documentation index (llms.txt) and the recipes page are the places to confirm current coverage.

Choosing Between Them

A practical pattern is to prototype the filter in jq against a JSON export, then port it to yq once you confirm the expression is within yq's supported set — and re-run it against the real YAML to catch comment or formatting changes.

yq is a lightweight, portable command-line processor for YAML, JSON, INI, and XML. It uses jq-like syntax but works across YAML, JSON, XML, INI, properties, CSV, and TSV files. If you already know jq, you can apply similar expressions to YAML and the other supported formats. yq is written in Go, so you can download a dependency-free binary for your platform and run it directly; package managers, Docker, and Podman are also listed as installation options.

Supported formats and syntax

The jq compatibility note matters: yq covers common operations and functions, and more is being added continuously, but it does not yet support everything jq does. If your workflow depends on a specific jq feature, check that yq supports it before switching.

Common operations

The quick usage guide shows the core patterns:

Read a value from a file:

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

Pipe from STDIN:

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

Update a YAML file in place:

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

Update using an environment variable:

NAME=mike yq -i '.a.b[0].c = strenv(NAME)' file.yaml

Merge two files:

yq -n 'load("file1.yaml") * load("file2.yaml")'

Merge using globs, evaluating all files at once with ea:

yq ea '. as $item ireduce ({}; . * $item)' path/to/*.yml

The -i flag writes changes back to the file, so the input file is modified in place. The ea flag evaluates all files at once rather than in sequence, which is what makes the glob merge work as expected.

Known limitations

yq tries to preserve comment positions and whitespace as much as possible, but it does not handle all scenarios. If comment or whitespace fidelity in your output is critical, verify the result on a sample file first. PowerShell also has its own quoting behavior that can affect yq commands, so quoting may need adjustment on Windows.

When to use it

Choose yq when you need one command-line tool to query and edit YAML alongside JSON, XML, INI, properties, CSV, or TSV, and when a dependency-free binary is convenient for scripts or containers. If you need full jq feature parity on YAML, confirm the specific functions you rely on are supported. For more examples, the project points to its recipes and documentation, and common questions are collected in its discussions.

yq is a lightweight, portable command-line processor for YAML, JSON, INI, XML, properties, CSV, and TSV files. Because it is written in Go, you can install it in several ways: download a dependency-free binary for your platform, use a package manager, or run it through Docker or Podman. The official install instructions live on the GitHub page linked from the yq documentation site (mikefarah.gitbook.io), which lists the specific options for each method.

Choose Your Installation Method

The documentation does not list specific package manager names or version numbers, so check the GitHub page for the current, complete list before choosing.

Verify the Installation

After installing, confirm yq is available and check its version:

yq --version

A successful install prints the version number (the docs describe the current line as v4.x). If the command is not found, the binary is likely not on your PATH or the package manager install did not complete.

Run Your First Commands

Once installed, yq uses jq-like syntax but works across YAML and the other supported formats. The quick usage guide gives these starting points:

Read a value from a file:

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

Pipe from standard input:

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

Update a YAML file in place:

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

Update using an environment variable:

NAME=mike yq -i '.a.b[0].c = strenv(NAME)' file.yaml

Merge two files:

yq -n 'load("file1.yaml") * load("file2.yaml")'

Merge many files at once using globs (note ea evaluates all files together rather than in sequence):

yq ea '. as $item ireduce ({}; . * $item)' path/to/*.yml

Common Installation and Usage Pitfalls

• Comments and whitespace: yq tries to preserve comment positions and whitespace, but it does not handle every scenario. If formatting matters, check the output after in-place edits.
• PowerShell quoting: PowerShell has its own quoting rules that can interfere with yq expressions. The docs point to a tips and tricks page for these cases.
• Feature gaps: yq does not yet support everything jq does, though it covers the most common operations and functions, with more added over time.

For more examples, the documentation links to a recipes section, and common questions are collected in the project discussions.

yq is a command-line processor that uses jq-like syntax to read and modify YAML, JSON, XML, INI, properties, CSV, and TSV files. To read a value, run yq '.a.b[0].c' file.yaml; to update a file in place, add the -i flag; to merge files, use load() with * or combine ea with ireduce. The examples below assume yq v4.x and a file named file.yaml containing nested keys, arrays, and comments.

Read a value from a file

Pass an expression and a filename. The expression is a path into the document, and yq prints the matching value.

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

• Input: file.yaml with a structure like a: {b: [{c: ...}]}.
• Action: yq evaluates the path expression.
• Expected result: the value at .a.b[0].c is printed to stdout. The file is not changed.

You can also pipe the document in through STDIN instead of naming a file:

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

This is useful when another command produces the YAML. The expression and output behavior are the same.

Update a YAML file in place

Add -i to write the result back to the same file. Without -i, yq prints the modified document to stdout and leaves the file untouched.

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

• Input: the existing file.yaml.
• Action: the assignment sets .a.b[0].c to the string cool, and -i overwrites the file.
• Expected result: file.yaml now contains the new value; other content is preserved as far as yq can preserve it.

To update from an environment variable, use strenv() so the value is read as a string:

NAME=mike yq -i '.a.b[0].c = strenv(NAME)' file.yaml

• Input: the environment variable NAME set to mike.
• Action: strenv(NAME) resolves to the variable's value at evaluation time.
• Expected result: .a.b[0].c becomes mike in the file.

This pattern is handy in scripts and CI, where values come from the environment rather than being hard-coded.

To find and update an item inside an array, select the element first and then assign. The documentation points to recipes and the full docs for concrete array examples; the general shape is a select/path expression followed by = value, run with -i to persist the change.

Merge multiple files

There are two documented approaches, and they behave differently.

Merge two named files with load() and *

yq -n 'load("file1.yaml") * load("file2.yaml")'

• Input: two files, loaded explicitly by name.
• Action: -n means "no input file"; the expression loads both documents and * merges them.
• Expected result: the merged document is printed to stdout.

Merge many files with a glob, ea, and ireduce

yq ea '. as $item ireduce ({}; . * $item )' path/to/*.yml

• Input: every .yml file matching the glob.
• Action: ea evaluates all files at once instead of in sequence; ireduce folds them one by one into an accumulator starting from {}, merging each with *.
• Expected result: a single merged document printed to stdout.

The ea flag matters here: the docs note it evaluates all files at once rather than in sequence, which is what makes the reduce over the whole set work as intended.

Things to watch for

• Comments and whitespace: yq tries to preserve comment positions and whitespace, but it does not handle every scenario. If formatting matters, check the output before committing.
• PowerShell quoting: PowerShell has its own quoting rules that can interfere with yq expressions. The docs point to tips and tricks for common problems and solutions.
• Coverage vs. jq: yq uses jq-like syntax but does not support everything jq does. The most common operations and functions are supported, and more are added over time.
• Installation: yq is written in Go, so you can download a dependency-free binary for your platform, or install via package managers, Docker, or Podman. The GitHub page lists the available methods.

For more examples, see the recipes and the full documentation; the discussions cover common questions.