yq - yq

Search…

v4.x

Upgrading from V3

Commands

Usage

Working with Properties

Working with JSON

Front Matter

GitHub Action

Tips, Tricks, Troubleshooting

Github Page

yq is a lightweight and portable command-line YAML processor

 
 
 
 
​
yq is 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.
v3 users:
Version 4 of yq is a major upgrade that now fully supports complex expressions for powerful filtering, slicing and dicing yaml documents. This new version uses syntax very similar to jq and works very similarly, so if you've used jq before this should be a low learning curve - however it is quite different from previous versions of yq. Take a look at the upgrade guide for help.
Support for v3 will cease August 2021, until then, critical bug and security fixes will still get applied if required.
How it works
yq works by runningyaml nodes against a filter expression. The filter expression is made of of operators that pipe into each other. yaml nodes are piped through operators, operators may either return a different set of nodes (e.g. children) or modify the nodes (e.g. update values). See the operator documentation for more details and examples.
1
yq eval 'select(.a == "frog") | .b.c = "dragon"' file.yaml
Copied!
Install
​Download the latest binary​
wget
Use wget to download the pre-compiled binaries:
Compressed via tar.gz
1
wget https://github.com/mikefarah/yq/releases/download/${VERSION}/${BINARY}.tar.gz -O - |\
2
  tar xz && mv ${BINARY} /usr/bin/yq
Copied!
Plain binary
1
wget https://github.com/mikefarah/yq/releases/download/${VERSION}/${BINARY} -O /usr/bin/yq &&\
2
    chmod +x /usr/bin/yq
Copied!
For instance, VERSION=v4.2.0 and BINARY=yq_linux_amd64
Homebrew
​Homebrew is a package manger for MacOS and Linux.
1
brew install yq
Copied!
for the (deprecated) v3 version
1
brew install [email protected]
Copied!
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.
Snap
Snap can be used on all major Linux distributions.
1
snap install yq
Copied!
or, for the (deprecated) v3 version:
1
snap install yq --channel=v3/stable
Copied!
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:
1
sudo cat /etc/myfile | yq e '.a.path' -
Copied!
And to write to a root file you can either use sponge:
1
sudo cat /etc/myfile | yq e '.a.path = "value"' - | sudo sponge /etc/myfile
Copied!
or write to a temporary file:
1
sudo cat /etc/myfile | yq e '.a.path = "value"' | sudo tee /etc/myfile.tmp
2
sudo mv /etc/myfile.tmp /etc/myfile
3
rm /etc/myfile.tmp
Copied!
Docker
Oneshot use:
1
docker run --rm -v "${PWD}":/workdir mikefarah/yq <command> [flags] [expression ]FILE...
Copied!
Run commands interactively:
1
docker run --rm -it -v "${PWD}":/workdir --entrypoint sh mikefarah/yq
Copied!
It can be useful to have a bash function to avoid typing the whole docker command:
1
yq() {
2
  docker run --rm -i -v "${PWD}":/workdir mikefarah/yq "[email protected]"
3
}
Copied!
Go Get
1
GO111MODULE=on go get github.com/mikefarah/yq
Copied!
Community Supported Installation methods
As these are supported by the community :heart: - however, they may be out of date with the officially supported releases.
Webi
1
webi yq
Copied!
See webi  for more infor.
Supported by @adithyasunil26 (https://github.com/webinstall/webi-installers/tree/master/yq)
Chocolatey for Windows:
1
choco install yq
Copied!
Supported by @chillum (https://chocolatey.org/packages/yq)
MacPorts:
1
sudo port selfupdate
2
sudo port install yq
Copied!
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:
1
sudo apt-key adv --keyserver keyserver.ubuntu.com --recv-keys CC86BB64
2
sudo add-apt-repository ppa:rmescandon/yq
3
sudo apt update
4
sudo apt install yq -y
Copied!
Supported by @rmescandon (https://launchpad.net/~rmescandon/+archive/ubuntu/yq)
Parsing engine and YAML spec support
Under the hood, yq uses go-yaml v3 as the yaml parser, which supports yaml spec 1.2. In particular, note that in 1.2 the values 'yes'/'no' are no longer interpreted as booleans, but as strings.