How to Install yq on Your Platform

Updated

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

Method Best for What you need to know
Dependency-free binary Most users; machines without Go or package managers Download the binary for your OS/architecture and run it directly
Package managers Users who prefer managed updates A variety of package managers are supported; see the GitHub page for the list
Docker Containerized or CI environments Run yq inside a container without installing it on the host
Podman Rootless or daemonless container setups Same container approach as Docker

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.