How to Use jq to Parse and Transform JSON Streams in Linux Terminal

Modern Linux DevOps pipelines, microservice architectures, and cloud APIs communicate almost exclusively using structured JSON payloads. While text-processing utilities like grep, awk, and sed excel at unstructured line-based logs, attempting to parse nested JSON keys, multi-dimensional arrays, and escaped Unicode using regular expressions results in brittle scripts. jq is a lightweight, flexible command-line JSON processor designed specifically for Unix pipelines. It slices, filters, maps, and transforms structured JSON data with declarative expressions.

Installing jq Across Linux Distributions

The jq binary is available in all standard package repositories:

# Ubuntu / Debian
sudo apt update && sudo apt install -y jq

# RHEL / CentOS / Rocky Linux / Fedora
sudo dnf install -y jq

# Arch Linux
sudo pacman -S jq

# Alpine Linux
apk add jq

Basic Filtering and Pretty-Printing

The simplest filter in jq is the identity operator ., which formats compact, unreadable JSON streams into colorized, cleanly indented text:

# Pretty-print JSON from an API endpoint
curl -s https://api.github.com/repos/stedolan/jq | jq '.'

# Extract a specific top-level property
curl -s https://api.github.com/repos/stedolan/jq | jq '.stargazers_count'

Navigating Nested Objects and Arrays

Access nested keys by chaining dot notation (.parent.child) and unnest array items using bracket notation ([]):

# Access nested property within an object
cat payload.json | jq '.user.address.city'

# Iterate over an array of objects and output each element
cat data.json | jq '.items[]'

# Extract only the "name" field from every object in an array
cat data.json | jq '.items[].name'

# Slice the first three elements of an array
cat data.json | jq '.items[0:3]'

Filtering and Conditional Select Expressions

To extract specific records matching boolean criteria without writing external shell scripts, use the select() function:

# Filter users where age is greater than or equal to 30
cat users.json | jq '.[] | select(.age >= 30)'

# Filter products by category and active status
cat catalog.json | jq '.products[] | select(.category == "hardware" and .in_stock == true)'

Transforming and Constructing New JSON Structures

jq allows constructing entirely new custom JSON objects and tabular outputs directly from input streams:

# Map incoming objects to a streamlined custom schema
cat users.json | jq '[.[] | {fullName: .name, userEmail: .email, active: .is_active}]'

# Transform JSON records into raw comma-separated values (CSV)
cat inventory.json | jq -r '.[] | [.id, .sku, .price] | @csv'

The -r (raw output) flag strips quotation marks from formatted strings, enabling seamless piping into bash variables, text files, and downstream Linux command pipelines.