How to Install yq on Ubuntu: A Portable YAML, JSON and XML Processor

yq is a lightweight, portable command-line processor for YAML, JSON, XML, and other structured formats. Written in Go by Mike Farah, it lets you query and transform documents with a compact, jq-inspired expression language — think of it as jq for the YAML files that fill modern DevOps work.

There is a naming trap worth flagging up front. Two different tools call themselves yq: a Python script that wraps jq, and Mike Farah’s standalone Go binary. This guide covers the Go version — the one packaged in the repository below — whose expressions read like yq '.a.b' file.yaml and which ships as a single dependency-free executable. Confirming you have the right one is part of the verification step.

Ubuntu’s official archive either omits a recent yq or carries a version that trails upstream by a wide margin. The unofficial deb.griffo.io repository provides an up-to-date .deb, so you install yq with apt and keep it current through your standard system upgrades.

What Makes yq Special?

📄 Handles many formats — YAML, JSON, XML, TOML, CSV/TSV, and properties files
🔧 jq-style syntax — a concise path language for reading and rewriting documents
✏️ In-place edits — -i rewrites a file directly without disturbing its layout
💬 Keeps comments — YAML comments survive most in-place transformations
🧩 Deep merging — combine multiple documents or files with one expression
📦 Static Go binary — no interpreter, runtime, or shared libraries required
🔁 Format conversion — flip YAML to JSON and back with output flags
🗂️ Multi-document support — process YAML streams with several --- documents

Why Use the deb.griffo.io Repository?

On Ubuntu, the deb.griffo.io repository is the simplest way to keep a current yq:

Easy installation and updates through APT, Ubuntu’s native package tooling
Automatic dependency management handled by the packaging
Tracks upstream releases instead of the outdated versions elsewhere
No manual binary downloads or source builds to stay recent
Works across supported Ubuntu releases from Jammy through the latest LTS and beyond

Prerequisites

Make sure you have the following:

An Ubuntu system (Jammy 22.04 LTS, Noble 24.04 LTS, or newer)
A user with sudo privileges
curl installed (sudo apt install curl if needed)

Step 1: Add the deb.griffo.io Repository

Add the key and repository:

# Create the keyrings directory
sudo install -d -m 0755 /etc/apt/keyrings

# Download and install the repository GPG key
curl -fsSL https://deb.griffo.io/EA0F721D231FDD3A0A17B9AC7808B4DD62C41256.asc | sudo gpg --dearmor --yes -o /etc/apt/keyrings/deb.griffo.io.gpg

# Add the repository (auto-detects your distro codename)
echo "deb [signed-by=/etc/apt/keyrings/deb.griffo.io.gpg] https://deb.griffo.io/apt $(lsb_release -sc 2>/dev/null) main" | sudo tee /etc/apt/sources.list.d/deb.griffo.io.list > /dev/null

# Update the package list
sudo apt update

Here is what happens:

install -d creates /etc/apt/keyrings with the right permissions for the signing key
curl … gpg --dearmor downloads and stores the key in APT’s binary keyring format
echo … tee adds the source line, with lsb_release -sc supplying your Ubuntu codename
apt update refreshes metadata so yq becomes available to install

Step 2: Update the Package List

If you did not run the final command above, do so now:

sudo apt update

Step 3: Install yq

Install yq with APT:

sudo apt install yq

APT installs the Go yq binary and places it on your PATH.

Step 4: Verify the Installation

Check the version and confirm you have the Go build:

yq --version

Expected output:

yq (https://github.com/mikefarah/yq/) version v4.44.3

The mikefarah/yq URL in that string is your guarantee that this is the Go implementation, not the Python jq wrapper.

Getting Started with yq

For the examples, start with a sample document:

cat > deployment.yaml <<'EOF'
metadata:
  name: api
  labels:
    app: api
    env: staging
spec:
  replicas: 2
  ports:
    - 8080
    - 9090
EOF

Converting Formats First

A common reason people reach for yq on Ubuntu is format conversion in CI. The -o (output) and -p (input) flags handle it:

# YAML to JSON
yq -o=json '.' deployment.yaml

# JSON to YAML
yq -p=json -o=yaml '.' payload.json

# Read XML as YAML
yq -p=xml '.' settings.xml

# Compact JSON to readable YAML from a pipe
cat payload.json | yq -p=json -o=yaml

Reading Values

Query a document with a path expression:

# A single value
yq '.metadata.name' deployment.yaml
# -> api

# A nested value
yq '.spec.replicas' deployment.yaml
# -> 2

# The first port in the sequence
yq '.spec.ports[0]' deployment.yaml
# -> 8080

# Every label value
yq '.metadata.labels[]' deployment.yaml

Editing In Place

The -i flag rewrites the file while keeping comments and layout intact:

# Scale up the replica count
yq -i '.spec.replicas = 5' deployment.yaml

# Add a label
yq -i '.metadata.labels.team = "platform"' deployment.yaml

# Append a port
yq -i '.spec.ports += [3000]' deployment.yaml

# Remove a key
yq -i 'del(.metadata.labels.env)' deployment.yaml

Selecting and Constructing

yq supports jq-like selection and object construction:

# Select only if a condition holds
yq '.spec | select(.replicas > 1)' deployment.yaml

# Build a summary object
yq '{"name": .metadata.name, "replicas": .spec.replicas}' deployment.yaml

Merging Files

Layer an override file over a base with a recursive merge:

yq '. *= load("prod.yaml")' deployment.yaml

# Reduce a stream of documents into a single merged result
yq eval-all '. as $item ireduce ({}; . * $item)' base.yaml overrides.yaml

The * operator merges deeply, which is ideal for building environment-specific manifests from a shared base.

Keeping yq Updated

Being a managed package, yq updates with your normal maintenance:

sudo apt update && sudo apt upgrade

Each upgrade pulls the latest packaged release automatically.

Other Tools from deb.griffo.io

The repository packages many other useful tools for Ubuntu:

DuckDB — an in-process SQL engine for querying data files
Nushell — a shell designed around structured data
fzf — a fuzzy finder that pairs nicely with yq output
just — a command runner for saving common yq recipes

Troubleshooting

Package Not Found

If APT cannot find the yq package:

Re-run sudo apt update to refresh the index
Confirm your Ubuntu release is supported (Jammy, Noble, or newer)
Check the source list: cat /etc/apt/sources.list.d/deb.griffo.io.list

GPG or Key Errors

If APT reports a signature or key problem, re-import the key:

sudo install -d -m 0755 /etc/apt/keyrings
curl -fsSL https://deb.griffo.io/EA0F721D231FDD3A0A17B9AC7808B4DD62C41256.asc | sudo gpg --dearmor --yes -o /etc/apt/keyrings/deb.griffo.io.gpg
sudo apt update

The Python yq Is Shadowing the Go Binary

If your expressions raise unexpected syntax errors, a pip-installed Python yq (a jq wrapper) may be first on your PATH. Check which binary wins:

yq --version
which -a yq

The version string should mention github.com/mikefarah/yq. If it does not, uninstall the Python one (pip uninstall yq) or reorder your PATH so the APT binary at /usr/bin/yq is found first.

Uninstalling

To remove yq:

sudo apt remove yq

To remove the repository too:

sudo rm /etc/apt/sources.list.d/deb.griffo.io.list
sudo rm /etc/apt/keyrings/deb.griffo.io.gpg
sudo apt update

Conclusion

yq gives Ubuntu users a fast, portable way to slice, transform, and convert the structured configuration files that modern infrastructure runs on. As a single static Go binary with jq-style ergonomics, it fits naturally into shell pipelines and CI jobs alike. The deb.griffo.io repository delivers a current build with apt install yq and keeps it updated through your regular upgrades.

Install it, create the sample manifest above, and experiment with a few queries and in-place edits. Once the path syntax clicks, editing YAML by hand starts to feel like a chore you no longer need to do.

Resources

Disclaimer: The deb.griffo.io repository is an unofficial community project and is not affiliated with the official Debian or Ubuntu projects, or with the upstream yq project.