a lightweight and portable command-line YAML, JSON and XML processor. yq
uses jq like syntax but works with yaml files as well as json, xml, 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.
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
Merge multiple files
# merge two files
yq -n 'load("file1.yaml") * load("file2.yaml")'
# merge using globs:
# note the use of `ea` to evaluate all the 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:
yq '(.[] | select(.name == "foo") | .address) = "12 cat st"'
Convert JSON to YAML
yq -Poy sample.json
See recipes for more examples and the documentation for more information.
Take a look at the discussions for common questions, and cool ideas
Use wget to download, gzipped pre-compiled binaries:
For instance, VERSION=v4.2.0 and BINARY=yq_linux_amd64
wget https://github.com/mikefarah/yq/releases/download/${VERSION}/${BINARY}.tar.gz -O - |\
tar xz && mv ${BINARY} /usr/bin/yq
wget https://github.com/mikefarah/yq/releases/download/${VERSION}/${BINARY} -O /usr/bin/yq &&\
chmod +x /usr/bin/yq
wget https://github.com/mikefarah/yq/releases/latest/download/yq_linux_amd64 -O /usr/bin/yq &&\
chmod +x /usr/bin/yq
Using Homebrew
brew install yq
snap install yq
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
docker run --rm -v "${PWD}":/workdir mikefarah/yq [command] [flags] [expression ]FILE...
Note that you can run yq
in docker without network access and other privileges if you desire,
namely --security-opt=no-new-privileges --cap-drop all --network none
.
podman run --rm -v "${PWD}":/workdir mikefarah/yq [command] [flags] [expression ]FILE...
You'll need to pass the -i\--interactive
flag to docker:
docker run -i --rm mikefarah/yq '.this.thing' < myfile.yml
podman run -i --rm mikefarah/yq '.this.thing' < myfile.yml
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 "$@"
}
yq
's container image no longer runs under root (#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
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
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
- 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 github.com/mikefarah/yq/v4@latest
As these are supported by the community ❤️ - 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.
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 profile install nixpkgs#yq-go
See here
webi yq
See webi Supported by @adithyasunil26 (https://github.com/webinstall/webi-installers/tree/master/yq)
pacman -S go-yq
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