yqyq is a portable command-line YAML processor
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 (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
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/communityto/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
jqbut 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
-
yqattempts 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.