What is yq and what file formats does it support?

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.