Skip to content
Use this GitHub Action with your project

Add this Action to an existing workflow or create a new one.

View on Marketplace
Go to file


Build Docker Pulls Github Releases (by Release) Go Report

a lightweight and portable command-line YAML processor

The aim of the project is to be the jq or sed of yaml files.


Download the latest binary


Using Homebrew

brew install yq

Ubuntu and other Linux distros supporting snap packages:

snap install yq

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 r - a.path

And to write to a root file you can either use sponge:

sudo cat /etc/myfile | yq w - a.path value | sudo sponge /etc/myfile

or write to a temporary file:

sudo cat /etc/myfile | yq w - a.path value | sudo tee /etc/myfile.tmp
sudo mv /etc/myfile.tmp /etc/myfile
rm /etc/myfile.tmp


Use wget to download the pre-compiled binaries:

wget{VERSION}/{BINARY} -O /usr/bin/yq &&\
    chmod +x /usr/bin/yq

For instance, VERSION=3.4.0 and BINARY=yq_linux_amd64

Run with Docker

Oneshot use:

docker run --rm -v "${PWD}":/workdir mikefarah/yq yq [flags] <command> FILE...

Run commands interactively:

docker run --rm -it -v "${PWD}":/workdir mikefarah/yq sh

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 "$@"

Go Get:

GO111MODULE=on go get

Community Supported Installation methods

As these are supported by the community ❤️ - however, they may be out of date with the officially supported releases.


choco install yq

Supported by @chillum (


Using MacPorts

sudo port selfupdate
sudo port install yq

Supported by @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

On Ubuntu 16.04 or higher from Debian package:

sudo apt-key adv --keyserver --recv-keys CC86BB64
sudo add-apt-repository ppa:rmescandon/yq
sudo apt update
sudo apt install yq -y

Supported by @rmescandon (



Check out the documentation for more detailed and advanced usage.

  yq [flags]
  yq [command]

Available Commands:
  compare          yq x [--prettyPrint/-P] dataA.yaml dataB.yaml 'b.e(name==fr*).value'
  delete           yq d [--inplace/-i] [--doc/-d index] sample.yaml 'b.e(name==fred)'
  help             Help about any command
  merge            yq m [--inplace/-i] [--doc/-d index] [--overwrite/-x] [--append/-a] sample.yaml sample2.yaml
  new              yq n [--script/-s script_file] a.b.c newValue
  prefix           yq p [--inplace/-i] [--doc/-d index] sample.yaml a.b.c
  read             yq r [--printMode/-p pv] sample.yaml 'b.e(name==fr*).value'
  shell-completion Generates shell completion scripts
  validate         yq v sample.yaml
  write            yq w [--inplace/-i] [--script/-s script_file] [--doc/-d index] sample.yaml 'b.e(name==fr*).value' newValue

  -C, --colors        print with colors
  -h, --help          help for yq
  -I, --indent int    sets indent level for output (default 2)
  -P, --prettyPrint   pretty print
  -j, --tojson        output as json. By default it prints a json document in one line, use the prettyPrint flag to print a formatted doc.
  -v, --verbose       verbose mode
  -V, --version       Print version information and quit

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

Upgrade from V2

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

V4 is in development!

If you're keen - check out the alpha release here, or in docker mikefarah/yq:4.0.0-alpha1 and the docs (also in alpha) here.

V4 is quite different from V3 (sorry for the migration), however it will be much more similar to jq, use a similar expression syntax and therefore support much more complex functionality!

For now - new features will be held off from V3 in anticipation of the V4 build. Critical fixes / issues will still be released.

Known Issues / Missing Features

You can’t perform that action at this time.