yq

a lightweight and portable command-line YAML processor. yq uses jq like syntax but works with yaml files as well as json. 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, all listed below.

Quick Usage Guide

Read a value:

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

Pipe from STDIN:

cat file.yaml | yq e '.a.b[0].c' -

Update a yaml file, inplace

yq e -i '.a.b[0].c = "cool"' file.yaml

Update using environment variables

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

Merge multiple files

yq ea '. as $item ireduce ({}; . * $item )' path/to/*.yml

Multiple updates to a yaml file

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

See the documentation for more.

Install

Download the latest binary

wget

Use wget to download the pre-compiled binaries:

Compressed via tar.gz

wget https://github.com/mikefarah/yq/releases/download/${VERSION}/${BINARY}.tar.gz -O - |\
  tar xz && mv ${BINARY} /usr/bin/yq

Plain binary

wget https://github.com/mikefarah/yq/releases/download/${VERSION}/${BINARY} -O /usr/bin/yq &&\
    chmod +x /usr/bin/yq

For instance, VERSION=v4.2.0 and BINARY=yq_linux_amd64

MacOS / Linux via Homebrew:

Using Homebrew

brew install yq

or, for the (deprecated) v3 version:

brew install yq@3

Note that for v3, as it is a versioned brew it will not add the yq command to your path automatically. Please follow the instructions given by brew upon installation.

Linux via snap:

snap install yq

or, for the (deprecated) v3 version:

snap install yq --channel=v3/stable

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 e '.a.path' -

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

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

or write to a temporary file:

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

Run with Docker

Oneshot use:

docker run --rm -v "${PWD}":/workdir mikefarah/yq <command> [flags] [expression ]FILE...

Pipe in via STDIN:

You'll need to pass the -i\--interactive flag to docker:

cat myfile.yml | docker run -i --rm mikefarah/yq e . -

Run commands interactively:

docker 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 "$@"
}

Running as root:

yq's docker image no longer runs under root (mikefarah#860). If you'd like to install more things in the docker 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

Or, in your docker file:

FROM mikefarah/yq

USER root
RUN apk add bash
USER yq

GitHub Action

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

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

Go Get:

GO111MODULE=on go get github.com/mikefarah/yq/v4

Community Supported Installation methods

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

Webi

webi yq

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

Windows:

choco install yq

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

Mac:

Using MacPorts

sudo port selfupdate
sudo port install yq

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

Alpine Linux

Enable edge/community repo by adding $MIRROR/alpine/edge/community to /etc/apk/repositories
Update database index with apk update
Install yq with apk add yq

Supported by Tuan Hoang https://pkgs.alpinelinux.org/package/edge/community/x86/yq

On Ubuntu 16.04 or higher from Debian package:

sudo apt-key adv --keyserver keyserver.ubuntu.com --recv-keys CC86BB64
sudo add-apt-repository ppa:rmescandon/yq
sudo apt update
sudo apt install yq -y

Supported by @rmescandon (https://launchpad.net/~rmescandon/+archive/ubuntu/yq)

Features

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 and JSON files
Fully supports multi document yaml files
Supports yaml front matter blocks (e.g. jekyll/assemble)
Colorized yaml output
Deeply traverse yaml
Sort yaml by keys
Manipulate yaml comments, styling, tags and anchors and aliases.
Update yaml inplace
Complex expressions to select and update
Keeps yaml formatting and comments when updating (though there are issues with whitespace)
Convert to/from json
Convert to properties
Pipe data in by using '-'
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

Check out the documentation for more detailed and advanced usage.

Usage:
  yq [flags]
  yq [command]

Available Commands:
  eval             Apply the expression to each document in each yaml file in sequence
  eval-all         Loads _all_ yaml documents of _all_ yaml files and runs expression once
  help             Help about any command
  shell-completion Generate completion script

Flags:
  -C, --colors                force print with colors
  -e, --exit-status           set exit status if there are no matches or null or false is returned
  -f, --front-matter string   (extract|process) first input as yaml front-matter. Extract will pull out the yaml content, process will run the expression against the yaml content, leaving the remaining data intact
  -h, --help                  help for yq
  -I, --indent int            sets indent level for output (default 2)
  -i, --inplace               update the yaml file inplace of first yaml file given.
  -M, --no-colors             force print with no colors
  -N, --no-doc                Don't print document separators (---)
  -n, --null-input            Don't read input, simply evaluate the expression given. Useful for creating yaml docs from scratch.
  -P, --prettyPrint           pretty print, shorthand for '... style = ""'
  -j, --tojson                output as json. Set indent to 0 to print json in one line.
      --unwrapScalar          unwrap scalar, print the value with no quotes, colors or comments (default true)
  -v, --verbose               verbose mode
  -V, --version               Print version information and quit

Use "yq [command] --help" for more information about a command.

Known Issues / Missing Features

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: https://mikefarah.gitbook.io/yq/usage/tips-and-tricks#quotes-in-windows-powershell

See tips and tricks for more common problems and solutions.

ebourg / yq

yq