Terminal GuideTerminal Guide
yq icon

yq

Dev Tools•
macOSLinuxWindows
•Go

YAML/JSON/XML/CSV/TOML processor with jq-like syntax.

Official Website

Features

YAML Processingjq-like SyntaxMultiple FormatsIn-place Editing

Installation

Homebrew
brew install yq
Chocolatey
choco install yq

Why use yq?

yq is a tool for processing YAML files from the command line. With jq-like syntax for manipulating YAML, it's ideal for editing Kubernetes and CI/CD configurations.

Multi-Format Support

Convert between multiple formats including YAML, JSON, XML, TOML, and CSV.

jq-Compatible Syntax

Nearly zero learning curve for jq users. Use the same query syntax to manipulate YAML.

In-Place Editing

Edit files directly. Update while preserving comments and formatting.

Single Binary

Install without dependencies. Easy to use in CI/CD environments.

Installation

Installation
# macOS (Homebrew)
brew install yq

# Ubuntu/Debian (snap)
sudo snap install yq

# Download binary directly
wget https://github.com/mikefarah/yq/releases/latest/download/yq_linux_amd64 -O /usr/local/bin/yq
chmod +x /usr/local/bin/yq

# Install via Go
go install github.com/mikefarah/yq/v4@latest

# Docker
docker run --rm -v "${PWD}":/workdir mikefarah/yq

Note: There are multiple implementations of yq. This guide uses mikefarah/yq (Go-based). It's different from the Python-based kislyuk/yq.

Basic Usage

Reading YAML

Reading
# Display entire YAML file
yq '.' config.yaml

# Get specific field
yq '.metadata.name' deployment.yaml

# Nested fields
yq '.spec.containers[0].image' pod.yaml

# Get array elements
yq '.items[].name' list.yaml

Sample YAML

config.yaml
# config.yaml
apiVersion: v1
kind: ConfigMap
metadata:
  name: my-config
  namespace: default
data:
  database_url: postgres://localhost:5432/mydb
  log_level: info

Extracting Values

Value Extraction
# Get as string (without quotes)
yq -r '.metadata.name' config.yaml
# Output: my-config

# Get multiple fields
yq '.metadata | {name, namespace}' config.yaml

# Get all keys
yq '.data | keys' config.yaml

Common Patterns

Manipulating Kubernetes Configurations

Kubernetes
# Get Deployment image
yq '.spec.template.spec.containers[0].image' deployment.yaml

# Get name and image of all containers
yq '.spec.template.spec.containers[] | {name, image}' deployment.yaml

# Check resource limits
yq '.spec.template.spec.containers[].resources' deployment.yaml

# Get labels
yq '.metadata.labels' deployment.yaml

Editing YAML

Editing
# Update field value
yq '.metadata.name = "new-name"' config.yaml

# Add new field
yq '.metadata.labels.app = "myapp"' config.yaml

# Update nested value
yq '.spec.replicas = 3' deployment.yaml

# Add element to array
yq '.spec.containers += [{"name": "sidecar", "image": "nginx"}]' pod.yaml

# Delete field
yq 'del(.metadata.annotations)' deployment.yaml

In-Place Editing

In-Place Editing
# Update file directly (-i option)
yq -i '.metadata.name = "updated-name"' config.yaml

# Create backup while editing
yq -i '.version = "2.0"' config.yaml && cp config.yaml config.yaml.bak

# Batch update multiple files
for f in *.yaml; do
  yq -i '.metadata.namespace = "production"' "$f"
done

Advanced Usage

Format Conversion

Format Conversion
# Convert YAML to JSON
yq -o=json '.' config.yaml

# Convert JSON to YAML
yq -P '.' config.json

# Convert YAML to XML
yq -o=xml '.' config.yaml

# Multiple YAML documents to array
yq ea '[.]' file1.yaml file2.yaml

Multi-Document Processing

Multi-Document
# Process all documents (multiple YAML separated by ---)
yq ea '.' multi-doc.yaml

# Select specific document
yq 'select(documentIndex == 1)' multi-doc.yaml

# Filter documents by condition
yq 'select(.kind == "Deployment")' resources.yaml

# Apply operation to all documents
yq ea '.metadata.namespace = "staging"' *.yaml

Merging and Combining

Merging
# Merge two YAML files
yq ea '. as $item ireduce ({}; . * $item)' base.yaml override.yaml

# Combine arrays
yq ea '.items = ([.items] | flatten)' file1.yaml file2.yaml

# Embed environment variables
export IMAGE_TAG="v1.2.3"
yq '.spec.containers[0].image = env(IMAGE_TAG)' deployment.yaml

# Reference values from another file
yq '.data.config = load("settings.json")' configmap.yaml

Conditional Operations

Conditional Operations
# Update elements matching condition
yq '(.spec.containers[] | select(.name == "app")).image = "newimage:v2"' deployment.yaml

# Exclude null values
yq '.. | select(. != null)' config.yaml

# Extract only specific types
yq '.. | select(type == "!!str")' config.yaml

# Display with path
yq '.. | select(. == "production") | path' config.yaml

Common Options

OptionDescriptionExample
-iIn-place editingyq -i '.v = 1' f.yaml
-o=jsonOutput in JSON formatyq -o=json '.' f.yaml
-PPretty print (YAML format)yq -P '.' f.json
-rRaw string outputyq -r '.name' f.yaml
eaEvaluate all documentsyq ea '.' *.yaml
-CForce color outputyq -C '.' f.yaml

Practical Examples

Updating CI/CD Configuration

CI/CD
# Update GitHub Actions version
yq -i '(.jobs.build.steps[] | select(.uses | test("actions/checkout"))).uses = "actions/checkout@v4"' .github/workflows/ci.yaml

# Add environment variable
yq -i '.env.NEW_VAR = "value"' .github/workflows/ci.yaml

# Update Docker Compose image tag
yq -i '.services.app.image = "myapp:$TAG"' docker-compose.yaml

Working with Helm values

Helm
# Update image tag in values.yaml
yq -i '.image.tag = "v2.0.0"' values.yaml

# Set replica count for environment
yq -i '.replicaCount = 3' values-production.yaml

# Merge multiple values files
yq ea '. as $item ireduce ({}; . * $item)' values.yaml values-override.yaml

Tips

  • •Use yq -P to convert JSON to YAML. Useful for saving API responses in YAML format
  • •Use env() function to embed environment variables in YAML. Great for dynamic values in CI/CD
  • •Comments are preserved by default. Use -N option to remove comments
  • •Combine select() with test() to filter elements with regex
  • •For complex queries, use --from-file to load from a file for easier management
Written by Dai AokiPublished: 2026-01-20

Related Articles

jq - JSON Processor

Lightweight and flexible command-line JSON processor

tools10 min read

HTTPie - HTTP Client

User-friendly command-line HTTP client

tools8 min read

Explore More

Browse Dev Tools

See all tools in this category

All CLI Tools

Explore all tool categories