yq — Process YAML and JSON on the Command Line

yq is a lightweight command-line processor for structured data – think jq, but primarily for YAML (plus JSON, XML, CSV, TOML and properties). Pay attention to which yq you have installed: this guide targets the Go-based mikefarah/yq with its own jq-like expression syntax (yq eval, yq '.foo', -i for in-place editing, -o=json for output). The older kislyuk/yq is a Python wrapper around jq and uses a different syntax, so the examples below won't work there as written. With yq you read values, filter lists, edit files in place and convert between formats, slotting cleanly into pipelines with tools like kubectl or docker compose.

Read & Query

yq <file> — Pretty-print a YAML file.

yq config.yaml

yq '.<key>' <file> — Read a specific key.

yq '.server.port' config.yaml

yq '.<key>.<nested>' <file> — Read a nested value.

yq '.database.connection.host' config.yaml

yq '.<array>[<n>]' <file> — Read an array element by index.

yq '.services[0].name' docker-compose.yml

yq '.<array>[]' <file> — Iterate over all array elements.

yq '.users[].email' config.yaml

yq '.[] | key' <file> — List all top-level keys.

yq '.[] | key' config.yaml

Modify & Update

yq '.<key> = "<value>"' <file> — Set a value (outputs to stdout).

yq '.server.port = 8080' config.yaml

yq -i '.<key> = "<value>"' <file> — Set a value in-place (modifies the file).

yq -i '.version = "2.0.0"' config.yaml

yq '.<key> += "<value>"' <file> — Append a value to an array.

yq -i '.tags += ["new-tag"]' config.yaml

yq 'del(.<key>)' <file> — Delete a key.

yq -i 'del(.deprecated_setting)' config.yaml

yq '.<key> |= . + 1' <file> — Increment a numeric value.

yq -i '.build_number |= . + 1' version.yaml

Filter & Select

yq '.[] | select(.<key> == "<value>")' <file> — Select elements matching a condition.

yq '.users[] | select(.role == "admin")' users.yaml

yq '.[] | select(.<key> > <n>)' <file> — Select elements with numeric comparison.

yq '.items[] | select(.price > 100)' catalog.yaml

yq '.<array> | length' <file> — Count elements in an array.

yq '.services | length' docker-compose.yml

yq '.[] | keys' <file> — List keys of a map.

yq '.services | keys' docker-compose.yml

yq 'has("<key>")' <file> — Check if a key exists.

yq 'has("database")' config.yaml

Format Conversion

yq -o=json <file> — Convert YAML to JSON.

yq -o=json config.yaml > config.json

yq -p=json <file> — Read JSON input and output as YAML.

yq -p=json config.json > config.yaml

yq -p=json -o=yaml <file> — Convert JSON to YAML (explicit).

yq -p=json -o=yaml package.json

yq -o=xml <file> — Convert YAML to XML.

yq -o=xml config.yaml

yq -o=csv <file> — Convert YAML to CSV.

yq -o=csv '.users' data.yaml

yq -o=props <file> — Convert YAML to Java properties format.

yq -o=props config.yaml

Merge & Multi-Document

yq '. * load("<file>")' <base> — Deep merge two YAML files (second overrides first).

yq '. * load("overrides.yaml")' base.yaml

yq eval-all '. as $item ireduce ({}; . * $item)' <file1> <file2> — Merge multiple files together.

yq eval-all '. as $item ireduce ({}; . * $item)' defaults.yaml env.yaml

yq -s '"doc_" + $index' <file> — Split a multi-document YAML into separate files.

yq -s '"doc_" + $index' multi.yaml

yq 'select(documentIndex == 0)' <file> — Select a specific document from a multi-doc YAML.

yq 'select(documentIndex == 0)' multi.yaml

Piping & Common Patterns

cat <file> | yq '.<key>' — Read from stdin.

kubectl get pod mypod -o yaml | yq '.metadata.labels'

yq -r '.<key>' <file> — Raw output (no quotes around strings).

yq -r '.image' deployment.yaml

yq -i '.image = "nginx:1.25"' deployment.yaml — Update a container image version in a Kubernetes manifest.

yq -i '.spec.template.spec.containers[0].image = "nginx:1.25"' deployment.yaml

yq '.env_file' docker-compose.yml — Inspect Docker Compose config from the command line.

yq '.services.web.environment' docker-compose.yml

Conclusion

yq makes reading and reshaping YAML, JSON and friends on the command line as convenient as jq is for JSON – perfect for pipelines with kubectl, docker compose or CI scripts. Keep in mind, though, that every example here targets mikefarah/yq (Go); with the Python wrapper kislyuk/yq many expressions look different. Take particular care with -i (in-place): yq overwrites the file directly and without prompting – make a backup first or work under version control, and test new expressions without -i by checking the output on stdout first. Note too that while yq largely preserves comments and formatting when editing in place, it may still normalize the file.