yq Documentation

File: README.md Copy Chapter

yq

A lightweight and portable command-line YAML, JSON, INI and XML processor. yq uses jq (a popular JSON processor) like syntax but works with yaml files as well as json, kyaml, xml, ini, properties, csv and tsv. It doesn't yet support everything jq does - but it does support the most common operations and functions, and more is being added continuously.

yq is written in Go - so you can download a dependency free binary for your platform and you are good to go! If you prefer there are a variety of package managers that can be used as well as Docker and Podman, all listed below.

Quick Usage Guide Copy Chapter

Basic Operations Copy Section

Read a value:

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 environment variables:

NAME=mike yq -i '.a.b[0].c = strenv(NAME)' file.yaml

Advanced Operations Copy Section

Merge multiple files:

# merge two files
yq -n 'load("file1.yaml") * load("file2.yaml")'

# merge using globs (note: `ea` evaluates all files at once instead of in sequence)
yq ea '. as $item ireduce ({}; . * $item )' path/to/*.yml

Multiple updates to a yaml file:

yq -i '
  .a.b[0].c = "cool" |
  .x.y.z = "foobar" |
  .person.name = strenv(NAME)
' file.yaml

Find and update an item in an array:

# Note: requires input file - add your file at the end
yq -i '(.[] | select(.name == "foo") | .address) = "12 cat st"' data.yaml

Convert between formats:

# Convert JSON to YAML (pretty print)
yq -Poy sample.json

# Convert YAML to JSON
yq -o json file.yaml

# Convert XML to YAML
yq -o yaml file.xml

See recipes for more examples and the documentation for more information.

Take a look at the discussions for common questions, and cool ideas

Install Copy Chapter

[Download the latest binary](https://github.com/mikefarah/yq/releases/latest) Copy Section

wget Copy Section

Use wget to download pre-compiled binaries. Choose your platform and architecture:

For Linux (example):

# Set your platform variables (adjust as needed)
VERSION=v4.2.0
PLATFORM=linux_amd64

# Download compressed binary
wget https://github.com/mikefarah/yq/releases/download/${VERSION}/yq_${PLATFORM}.tar.gz -O - |\
  tar xz && sudo mv yq_${PLATFORM} /usr/local/bin/yq

# Or download plain binary
wget https://github.com/mikefarah/yq/releases/download/${VERSION}/yq_${PLATFORM} -O /usr/local/bin/yq &&\
    chmod +x /usr/local/bin/yq

Latest version (Linux AMD64):

wget https://github.com/mikefarah/yq/releases/latest/download/yq_linux_amd64 -O /usr/local/bin/yq &&\
    chmod +x /usr/local/bin/yq

Available platforms: linux_amd64, linux_arm64, linux_arm, linux_386, darwin_amd64, darwin_arm64, windows_amd64, windows_386, etc.

MacOS / Linux via Homebrew: Copy Section

Using Homebrew

brew install yq

Linux via snap: Copy Section

snap install yq

Snap notes

yq installs with strict confinement in snap, this means it doesn't have direct access to root files. To read root files you can:

sudo cat /etc/myfile | yq '.a.path'

And to write to a root file you can either use sponge:

sudo cat /etc/myfile | yq '.a.path = "value"' | sudo sponge /etc/myfile

or write to a temporary file:

sudo cat /etc/myfile | yq '.a.path = "value"' | sudo tee /etc/myfile.tmp
sudo mv /etc/myfile.tmp /etc/myfile
rm /etc/myfile.tmp

Run with Docker or Podman Copy Section

One-time use:

# Docker - process files in current directory
docker run --rm -v "${PWD}":/workdir mikefarah/yq '.a.b[0].c' file.yaml

# Podman - same usage as Docker
podman run --rm -v "${PWD}":/workdir mikefarah/yq '.a.b[0].c' file.yaml

Security note: You can run yq in Docker with restricted privileges:

docker run --rm --security-opt=no-new-privileges --cap-drop all --network none \
  -v "${PWD}":/workdir mikefarah/yq '.a.b[0].c' file.yaml

Pipe data via STDIN:

You'll need to pass the -i --interactive flag to Docker/Podman:

# Process piped data
docker run -i --rm mikefarah/yq '.this.thing' < myfile.yml

# Same with Podman
podman run -i --rm mikefarah/yq '.this.thing' < myfile.yml

Run commands interactively:

docker run --rm -it -v "${PWD}":/workdir --entrypoint sh mikefarah/yq

podman run --rm -it -v "${PWD}":/workdir --entrypoint sh mikefarah/yq

It can be useful to have a bash function to avoid typing the whole docker command:

yq() {
  docker run --rm -i -v "${PWD}":/workdir mikefarah/yq "$@"
}

yq() {
  podman run --rm -i -v "${PWD}":/workdir mikefarah/yq "$@"
}

Running as root:

yq's container image no longer runs under root (https://github.com/mikefarah/yq/pull/860). If you'd like to install more things in the container image, or you're having permissions issues when attempting to read/write files you'll need to either:

docker run --user="root" -it --entrypoint sh mikefarah/yq

podman run --user="root" -it --entrypoint sh mikefarah/yq

Or, in your Dockerfile:

FROM mikefarah/yq

USER root
RUN apk add --no-cache bash
USER yq

Missing timezone data

By default, the alpine image yq uses does not include timezone data. If you'd like to use the tz operator, you'll need to include this data:

FROM mikefarah/yq

USER root
RUN apk add --no-cache tzdata
USER yq

Podman with SELinux

If you are using podman with SELinux, you will need to set the shared volume flag :z on the volume mount:

-v "${PWD}":/workdir:z

GitHub Action Copy Section

- name: Set foobar to cool
    uses: mikefarah/yq@master
    with:
      cmd: yq -i '.foo.bar = "cool"' 'config.yml'
  - name: Get an entry with a variable that might contain dots or spaces
    id: get_username
    uses: mikefarah/yq@master
    with:
      cmd: yq '.all.children.["${{ matrix.ip_address }}"].username' ops/inventories/production.yml
  - name: Reuse a variable obtained in another step
    run: echo ${{ steps.get_username.outputs.result }}

See https://mikefarah.gitbook.io/yq/usage/github-action for more.

Go Install: Copy Section

go install github.com/mikefarah/yq/v4@latest

Community Supported Installation methods Copy Chapter

As these are supported by the community :heart: - however, they may be out of date with the officially supported releases.

Please note that the Debian package (previously supported by @rmescandon) is no longer maintained. Please use an alternative installation method.

X-CMD Copy Section

Checkout yq on x-cmd: https://x-cmd.com/mod/yq

• Instant Results: See the output of your yq filter in real-time.
• Error Handling: Encounter a syntax error? It will display the error message and the results of the closest valid filter

Thanks @edwinjhlee!

Nix Copy Section

nix profile install nixpkgs#yq-go

See here

Webi Copy Section

webi yq

See webi
Supported by @adithyasunil26 (https://github.com/webinstall/webi-installers/tree/master/yq)

Arch Linux Copy Section

pacman -S go-yq

Windows: Copy Section

Using Chocolatey

choco install yq

Supported by @chillum (https://chocolatey.org/packages/yq)

Using scoop

scoop install main/yq

Using winget

winget install --id MikeFarah.yq

MacPorts: Copy Section

Using MacPorts

sudo port selfupdate
sudo port install yq

Supported by @herbygillot (https://ports.macports.org/maintainer/github/herbygillot)

Alpine Linux Copy Section

Alpine Linux v3.20+ (and Edge):

apk add yq-go

Alpine Linux up to v3.19:

apk add yq

Supported by Tuan Hoang (https://pkgs.alpinelinux.org/packages?name=yq-go)

Flox: Copy Section

Flox can be used to install yq on Linux, MacOS, and Windows through WSL.

flox install yq

MacOS / Linux via gah: Copy Section

Using gah

gah install yq

Features Copy Chapter

• Detailed documentation with many examples
• Written in portable go, so you can download a lovely dependency free binary
• Uses similar syntax as jq but works with YAML, INI, JSON and XML files
• Fully supports multi document yaml files
• Supports yaml front matter blocks (e.g. jekyll/assemble)
• Colorized yaml output
• Date/Time manipulation and formatting with TZ
• Deep data structures
• Sort keys
• Manipulate yaml comments, styling, tags and anchors and aliases.
• Update in place
• Complex expressions to select and update
• Keeps yaml formatting and comments when updating (though there are issues with whitespace)
• Decode/Encode base64 data
• Load content from other files
• Convert to/from json/ndjson
• Convert to/from xml
• Convert to/from hcl (terraform)
• Convert to/from toml
• Convert to/from properties
• Convert to/from csv/tsv
• General shell completion scripts (bash/zsh/fish/powershell)
• Reduce to merge multiple files or sum an array or other fancy things.
• Github Action to use in your automated pipeline (thanks @devorbitus)

[Usage](https://mikefarah.gitbook.io/yq/) Copy Chapter

Check out the documentation for more detailed and advanced usage.

/* Detailed source-code truncated for AI context efficiency. */

Troubleshooting Copy Chapter

Common Issues Copy Section

PowerShell quoting issues:

# Use single quotes for expressions
yq '.a.b[0].c' file.yaml

# Or escape double quotes
yq ".a.b[0].c = \"value\"" file.yaml

Getting Help Copy Section

• Check existing issues: GitHub Issues
• Ask questions: GitHub Discussions
• Documentation: Complete documentation
• Examples: Recipes and examples

Known Issues / Missing Features Copy Chapter

• yq attempts to preserve comment positions and whitespace as much as possible, but it does not handle all scenarios (see https://github.com/go-yaml/yaml/tree/v3 for details)
• Powershell has its own...opinions on quoting yq
• "yes", "no" were dropped as boolean values in the yaml 1.2 standard - which is the standard yq assumes.

See tips and tricks for more common problems and solutions.

File: pkg/yqlib/doc/operators/headers/add.md Copy Chapter

Add

Add behaves differently according to the type of the LHS:

• arrays: concatenate
• number scalars: arithmetic addition
• string scalars: concatenate
• maps: shallow merge (use the multiply operator (*) to deeply merge)

Use += as a relative append assign for things like increment. Note that .a += .x is equivalent to running .a = .a + .x.

File: pkg/yqlib/doc/operators/headers/alternative-default-value.md Copy Chapter

Alternative (Default value)

This operator is used to provide alternative (or default) values when a particular expression is either null or false.

File: pkg/yqlib/doc/operators/headers/anchor-and-alias-operators.md Copy Chapter

Anchor and Alias Operators

Use the alias and anchor operators to read and write yaml aliases and anchors. The explode operator normalises a yaml file (dereference (or expands) aliases and remove anchor names).

yq supports merge keys (like <<: *blah) from YAML 1.1. These are no longer part of the YAML 1.2 standard, but remain common in practice. Plain <<: keys are recognised as merge keys and round-trip as <<: without an explicit !!merge tag. When the source uses an explicit !!merge tag, that is preserved on output. Internally, when yq synthesises a << map key (for example during merge operations), it tags the key as !!merge rather than !!str.

NOTE --yaml-fix-merge-anchor-to-spec flag Copy Chapter

yq doesn't merge anchors <<: to spec, in some circumstances it incorrectly overrides existing keys when the spec documents not to do that.

To minimise disruption while still fixing the issue, a flag has been added to toggle this behaviour. This will first default to false; and log warnings to users. Then it will default to true (and still allow users to specify false if needed).

This flag also enables advanced merging, like inline maps, as well as fixes to ensure when exploding a particular path, neighbours are not affect ed.

Long story short, you should be setting this flag to true.

See examples of the flag differences below, where LEGACY is with the flag off; and FIXED is with the flag on.

File: pkg/yqlib/doc/operators/headers/array-to-map.md Copy Chapter

Array to Map

Use this operator to convert an array to..a map. The indices are used as map keys, null values in the array are skipped over.

Behind the scenes, this is implemented using reduce:

(.[] | select(. != null) ) as $i ireduce({}; .[$i | key] = $i)

File: pkg/yqlib/doc/operators/headers/assign-update.md Copy Chapter

Assign (Update)

This operator is used to update node values. It can be used in either the:

plain form: `=` Copy Section

Which will set the LHS node values equal to the RHS node values. The RHS expression is run against the matching nodes in the pipeline.

relative form: `|=` Copy Section

This will do a similar thing to the plain form, but the RHS expression is run with each LHS node as context. This is useful for updating values based on old values, e.g. increment.

Flags Copy Section

• c clobber custom tags

File: pkg/yqlib/doc/operators/headers/boolean-operators.md Copy Chapter

Boolean Operators

The or and and operators take two parameters and return a boolean result.

not flips a boolean from true to false, or vice versa.

any will return true if there are any true values in an array sequence, and all will return true if all elements in an array are true.

any_c(condition) and all_c(condition) are like any and all but they take a condition expression that is used against each element to determine if it's true. Note: in jq you can simply pass a condition to any or all and it simply works - yq isn't that clever..yet

These are most commonly used with the select operator to filter particular nodes.

Related Operators Copy Chapter

• equals / not equals (==, !=) operators here
• comparison (>=, < etc) operators here
• select operator here

File: pkg/yqlib/doc/operators/headers/collect-into-array.md Copy Chapter

Collect into Array

This creates an array using the expression between the square brackets.

File: pkg/yqlib/doc/operators/headers/column.md Copy Chapter

Column

Returns the column of the matching node. Starts from 1, 0 indicates there was no column data.

Column is the number of characters that precede that node on the line it starts.

File: pkg/yqlib/doc/operators/headers/comment-operators.md Copy Chapter

Comment Operators

Use these comment operators to set or retrieve comments. Note that line comments on maps/arrays are actually set on the key node as opposed to the value (map/array). See below for examples.

Like the = and |= assign operators, the same syntax applies when updating comments:

plain form: `=` Copy Section

This will set the LHS nodes' comments equal to the expression on the RHS. The RHS is run against the matching nodes in the pipeline

relative form: `|=` Copy Section

This is similar to the plain form, but it evaluates the RHS with each matching LHS node as context. This is useful if you want to set the comments as a relative expression of the node, for instance its value or path.