How to Install and Use yq in Linux Terminal to Parse and Convert YAML and JSON

YAML has become the undisputed configuration standard for modern cloud-native architectures, container orchestration engines like Kubernetes and Docker Compose, GitHub Actions automation pipelines, and Ansible playbooks. However, unlike JSON—which has long enjoyed the ubiquitous command-line power of jq—parsing, slicing, and mutating complex YAML data structures from within Bash shell scripts has historically been error-prone and brittle.

The yq utility (specifically the popular Go implementation by Andrey Kislyuk/Mike Farah) solves this challenge directly. Functioning as a high-performance, portable command-line YAML, JSON, XML, CSV, and properties processor, yq brings jq-like expressive syntax to YAML documents, enabling developers and DevOps engineers to extract nested keys, update values in place, and seamlessly convert between YAML and JSON formats.

How to Install yq in Linux

Depending on your Linux distribution and environment permissions, yq can be installed using several official package managers or via direct precompiled binary download.

Method 1: Installing via Native Package Managers

On Ubuntu and Debian systems (or systems with Snap enabled):

sudo snap install yq

On Arch Linux and Manjaro:

sudo pacman -S yq

Method 2: Direct Binary Installation (All Distributions)

For headless production servers or continuous integration (CI) runners where Snap is unavailable, download the official standalone Go binary directly from GitHub:

sudo wget -qO /usr/local/bin/yq https://github.com/mikefarah/yq/releases/latest/download/yq_linux_amd64
sudo chmod +x /usr/local/bin/yq

Verify that yq is installed and accessible in your system path:

yq --version

Reading and Extracting Data from YAML Files

The foundational syntax of yq follows the structure yq '<expression>' <file.yaml>.

Suppose you have a configuration file named config.yaml containing the following content:

app:
  name: "Digitash-Service"
  port: 8080
  database:
    host: "10.0.0.5"
    enabled: true
servers:
  - name: "node-01"
    ip: "192.168.1.10"
  - name: "node-02"
    ip: "192.168.1.11"

1. Extracting a Nested Key

To retrieve a specific nested value, chain the keys using dot notation:

yq '.app.database.host' config.yaml

Output:

10.0.0.5

2. Extracting from Arrays

To access elements within a list, use bracket indexing (zero-based):

yq '.servers[0].ip' config.yaml

Output:

192.168.1.10

3. Extracting All Values in an Array

To extract a specific field across every item in an array:

yq '.servers[].name' config.yaml

Output:

node-01
node-02

Updating YAML Values In-Place

One of yq‘s most powerful capabilities is in-place editing (-i), which modifies the target YAML file directly while preserving comments, line breaks, and indentation formatting:

To change the port number from 8080 to 9000:

yq -i '.app.port = 9000' config.yaml

To toggle a boolean flag:

yq -i '.app.database.enabled = false' config.yaml

To append a new server entry to an existing array:

yq -i '.servers += {"name": "node-03", "ip": "192.168.1.12"}' config.yaml

Converting Between YAML and JSON

Modern microservices often communicate via JSON payloads while accepting YAML configuration files. yq allows instantaneous, bidirectional format conversion directly from the terminal:

1. Converting YAML to JSON

To convert an entire YAML file into formatted JSON output:

yq -o=json config.yaml

To produce compact, minified JSON suitable for HTTP POST requests or environment variables, pass the -I=0 flag:

yq -o=json -I=0 config.yaml

2. Converting JSON to YAML

You can pipe JSON data from a curl API call directly into yq to generate clean YAML configuration blocks:

curl -s https://api.example.com/v1/status | yq -p=json -o=yaml

Or convert a local JSON file directly into a new YAML file:

yq -p=json -o=yaml input.json > output.yaml

Filtering and Searching YAML Documents

You can use conditional filters inside yq expressions to locate specific objects matching defined criteria:

To find the IP address of the server named “node-02”:

yq '.servers[] | select(.name == "node-02") | .ip' config.yaml

Output:

192.168.1.11

Mastering these fundamental yq operations eliminates the need for brittle regex searches or custom Python scripts, streamlining CI/CD configuration pipelines and Kubernetes manifest management across Linux systems.