yq/README.md

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

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 (https://github.com/mikefarah/yq/pull/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.