Need help with yq?
Click the “chat” button below for chat support from the developer who created it, or find similar developers for support.

About the developer

mikefarah
3.6K Stars 225 Forks MIT License 865 Commits 46 Opened issues

Description

yq is a portable command-line YAML processor

Services available

!
?

Need anything else?

Contributors list

yq

Build Docker Pulls Github Releases (by Release) Go Report

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.

V4 released!

V4 is now officially released, it's quite different from V3 (sorry for the migration), however it is much more similar to

jq
, using a similar expression syntax and therefore support much more complex functionality!

If you've been using v3 and want/need to upgrade, checkout the upgrade guide.

Support for v3 will cease August 2021, until then, critical bug and security fixes will still get applied if required.

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=yqlinuxamd64

MacOS / Linux via Homebrew:

Using Homebrew

brew install yq

or, for the (deprecated) v3 version:

brew install [email protected]

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  [flags] [expression ]FILE...

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 "[email protected]"
}

Go Get:

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

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

webi yq

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

Windows:

Chocolatey Chocolatey

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

Usage

Check out the documentation for more detailed and advanced usage.

Usage:
  yq [flags]
  yq [command]

Available Commands: eval Apply expression to each document in each yaml file given 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 -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. -v, --verbose verbose mode -V, --version Print version information and quit

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

Simple Example:

yq e '.a.b | length' f1.yml f2.yml 

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)

We use cookies. If you continue to browse the site, you agree to the use of cookies. For more information on our use of cookies please see our Privacy Policy.