s0sta
EN NL عربي
Filters
How to search
  • Plain words find names, texts and examples.
  • "two words" finds the exact phrase.
  • --name or -x finds an option.
  • #word looks only inside commands.
  • @grep finds lessons and labs that use grep.
  • Filters: cat:network · in:labs · in:notes · level:rhcsa · ch:8 · root:yes. Put ! before a word to leave it out. OR between words means one of them.
  • ↑ ↓ to move · Enter to open · Esc to close · / to search

yq

Read and change YAML files from the command line — Kubernetes manifests, Helm values, CI files — like jq does for JSON.

Level
DevOps tool
Group
Text and search
Needs root
No
Package
yq

What it does

yq (the Go version by Mike Farah, v4) uses the same filter language as jq, but for YAML (and JSON, XML, TOML). It keeps comments and the order of keys, so it is safe for files in Git.

Typical use: set an image tag in a manifest in a pipeline, read a value from values.yaml, merge two YAML files, or turn YAML into JSON.

Note

there is also an older Python yq; the commands here are for the Go yq v4 (yq --version shows "mikefarah").

How to write it

yq [eval|eval-all] [OPTIONS] EXPRESSION [FILE ...]

Options 16

Most used

Main options

-i, --inplace
Change the file in place.
-o, --output-format FMT
Output as yaml, json, props, csv, tsv, xml.
-p, --input-format FMT
Input format (yaml, json, xml, toml, props).
-r, --unwrapScalar
Print plain values without quotes (default on).
-e, --exit-status
Exit 1 if there is no match.
-n, --null-input
Start from nothing (make new YAML).
-I N
Indent with N spaces.
ea, eval-all
Read all files together (for merges).
-s EXPR
Split the output into files named by EXPR.

Expressions

.a.b / .a[0]
A value / the first item.
.x = "v"
Set a value.
del(.x)
Remove a key.
select(COND)
Keep matching documents or items.
strenv(VAR) / env(VAR)
Use an environment variable (string / typed).
*+ / *
Deep merge of two documents.
document_index / di
Pick documents in a multi-document file.

Examples 12

$ run as a normal user# run as root (or with sudo)

  1. 1Read one value

    yq '.image.tag' values.yaml
v1.3.2

  2. 2Set the image tag in place (in a pipeline)

    TAG=v1.4.0 yq -i '.image.tag = strenv(TAG)' charts/shop/values.yaml

  3. 3Change the image of a Deployment

    yq -i '(.spec.template.spec.containers[] | select(.name == "app")).image = "ghcr.io/acme/shop:1.4.0"' deploy.yaml

  4. 4YAML to JSON and back

    yq -o=json deploy.yaml > deploy.json
yq -p=json -o=yaml deploy.json

  5. 5Merge a base and an override file

    yq ea '. as $item ireduce ({}; . * $item)' values.yaml values-prod.yaml > merged.yaml

  6. 6Only the Services in a multi-document file

    yq 'select(.kind == "Service")' all.yaml

  7. 7Count the documents

    yq ea '[.] | length' all.yaml

  8. 8Remove a key

    yq -i 'del(.metadata.annotations."kubectl.kubernetes.io/last-applied-configuration")' svc.yaml

  9. 9Add an item to a list

    yq -i '.env += [{"name": "LOG_LEVEL", "value": "info"}]' container.yaml

  10. 10Read the jobs of a GitHub Actions workflow

    yq '.jobs | keys' .github/workflows/ci.yml

  11. 11Split a big file into one file per resource

    yq -s '.kind + "-" + .metadata.name' all.yaml

  12. 12Check that a value exists (CI gate)

    yq -e '.resources.limits.memory' values.yaml >/dev/null || echo "memory limit missing"

Watch out

  • -i changes the file without a backup; commit first or work on a copy.
  • Use strenv(VAR) for versions like 1.10 — env(VAR) would turn them into the number 1.1.
  • Two different tools are called yq; check yq --version.

Tips to remember

  • Kustomize or Helm is better for big changes; yq is great for one value in CI.

Exit codes

0OK.
1Error, or no match with -e.

Full manual

This page explains the command in simple words. The original manual has every detail.

In your terminal: man yq

Open the man page (linux.die.net)