Skip to content
Get packs

Guide · Open source

How to use yq: read, update and convert YAML from the command line

Updated · written with AI from the project's own documentation and checked against our catalogue data

yq is a command-line program for reading and changing structured data files such as YAML, JSON, XML, CSV and properties. It uses a syntax similar to jq, so people who know jq can pick it up quickly. This guide shows how to install yq, read and update values, merge files and convert between formats, so you can change configuration from a script instead of editing files by hand.

yqmikefarah/yq · ★ 16.2k · MIT

Quick start

  1. 1Install yq. Run brew install yq on macOS or Linux, or snap install yq on Linux.
  2. 2Test a read. Run yq '.a.b[0].c' file.yaml on a sample file to confirm it prints the value you expect.
  3. 3Try an expression on a copy. Before changing real files, run your update without -i so the result prints to the terminal.
  4. 4Update in place. Add -i to write the change to the file, or use strenv() to pass a value from an environment variable.
  5. 5Convert formats if needed. Use -o json, -o yaml or -Poy to change the output format.

Install yq with a package manager

The simplest route is a package manager. On macOS or Linux you can use Homebrew, and on Linux you can use Snap. You can also install it with Go if you already have a Go toolchain.

yq is written in Go and is distributed as a dependency-free binary, so once it is on your path you can run it directly. The README also lists Chocolatey, scoop and winget for Windows, and MacPorts and Nix among other options.

  • Homebrew (macOS / Linux)
  • Snap (Linux). Snap installs yq with strict confinement, so it cannot read root-owned files directly; the README shows workarounds using sudo cat and sponge or a temporary file.
  • Go: go install github.com/mikefarah/yq/v4@latest
brew install yq

Read a value from a YAML file

Pass a query expression and a file name. The expression uses jq-like path syntax. You can also pipe data in on standard input instead of naming a file.

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

Update values in place

Add the -i flag to write changes back to the file. Without it, yq prints the result to the terminal and leaves the file unchanged.

To set a value from an environment variable, use strenv() in the expression. To apply several changes at once, separate expressions with a pipe inside one quoted block.

  • Use (.[] | select(.name == "foo") | .address) = "12 cat st" to update an item in an array. The README notes that this form needs an input file at the end of the command.
yq -i '.a.b[0].c = "cool"' file.yaml NAME=mike yq -i '.a.b[0].c = strenv(NAME)' file.yaml

Merge multiple files

To merge two files, use load() inside an expression with -n, which tells yq not to read standard input. To merge many files with a glob, use the ea option, which evaluates all files at once instead of in sequence.

yq -n 'load("file1.yaml") * load("file2.yaml")' yq ea '. as $item ireduce ({}; . * $item )' path/to/*.yml

Convert between formats

Use -o to choose the output format. The README shows JSON to YAML with pretty printing, YAML to JSON, and XML to YAML. The -P flag pretty prints, and -oy selects YAML output.

  • JSON to YAML: yq -Poy sample.json
  • YAML to JSON: yq -o json file.yaml
  • XML to YAML: yq -o yaml file.xml
yq -Poy sample.json

Run yq in Docker or Podman

If you do not want a local install, the official image runs with Docker or Podman. Mount your current directory into /workdir so yq can see your files. For piped input, add -i to the container command.

The image no longer runs as root. If you hit permission errors, the README suggests running as root for a one-off shell or adding a USER step in your Dockerfile.

  • Use the :z volume flag with Podman when SELinux is enabled.
  • The Alpine-based image does not include timezone data, which the tz operator needs. The README shows how to add tzdata in a Dockerfile.
docker run --rm -v "${PWD}":/workdir mikefarah/yq '.a.b[0].c' file.yaml

Use yq in CI pipelines

yq also ships as a GitHub Action. In the action's cmd input you pass the same yq command you would run locally, and later steps can reuse the output through the step's outputs.

- name: Set foobar to cool uses: mikefarah/yq@master with: cmd: yq -i '.foo.bar = "cool"' 'config.yml'

What people use it for

  • Changing a setting in a YAML config file from a shell script
  • Updating image tags or values in Kubernetes or deployment manifests from a CI job
  • Converting a JSON file to YAML for a config tool that expects YAML
  • Merging several YAML files into one with a glob pattern
  • Reading a single value from a file in a pipeline step

Frequently asked questions

Is yq free to use?

yq is released under the MIT licence, according to its repository listing. You can use, modify and redistribute it under that licence's terms.

Does yq need any other software installed?

The README lists no prerequisites. It describes yq as a dependency-free binary written in Go, so you can download the binary for your platform and run it.

How do I install yq?

Use brew install yq on macOS or Linux, snap install yq on Linux, or go install github.com/mikefarah/yq/v4@latest if you have Go. Docker and Podman are also supported.

Is yq the same as jq?

No. yq uses jq-like syntax but works on YAML, JSON, XML, CSV and other formats. The README says it does not yet support everything jq does, though it covers the most common operations.

What is the difference between yq and the Python yq?

The Python yq is a separate wrapper project listed among comparable tools. This page covers mikefarah/yq, the Go program described in the README.

Why does yq fail with permission errors in Docker?

The container image no longer runs as root. The README suggests running with --user="root" for troubleshooting, or adding a USER root step in a Dockerfile to install what you need.

New agent skills, repos and AI tools — every week

The best new skills and open-source projects, the fastest-growing repos, and one free prompt. Five minutes to read. Unsubscribe anytime.

Our verdict

Use yq if you script changes to YAML configs, manifests or CI files, or if you need to convert between formats and already know jq. Skip it if you only edit files in a text editor, need full jq compatibility, or want a graphical interface, since the README says it is command-line only and does not yet cover everything jq does.

Install options & downloads