jq 1.8.2

Every modern command-line tool emits JSON, and grep on structured data works until the formatting changes. jq is a small language built for the job.

The parts you will actually use

curl -s https://api.example.com/data | jq          # pretty-print and colourise
jq -r '.name' file.json                            # raw string, no quotes
jq -r '.[] | select(.state == "running") | .name'  # filter then extract
jq -r '.[] | [.name, .state] | @tsv'               # tab separated for column
jq --arg svc nginx '.[] | select(.name == $svc)'   # pass a shell value safely

-r is the flag you want whenever the output feeds another command, because otherwise the JSON quotes become part of the value.

--arg rather than interpolating into the filter string. Building a filter with shell interpolation has the same class of problem as building SQL that way.

Practical examples

# Container name, status, image, as a table
docker inspect $(docker ps -q) \
  | jq -r '.[] | [.Name, .State.Status, .Config.Image] | @tsv' \
  | column -t

# Failed systemd units
systemctl list-units --failed --output=json | jq -r '.[].unit'

# Extract a value into a variable
VERSION=$(curl -s "$API/version" | jq -r '.version')

The @tsv formatter exists precisely so output can be handed to column.

Handling missing keys

jq -r '.name // "unknown"'    # fall back on null or false
jq -r '.a.b?'                 # suppress the error on a missing path

Without either, a missing key produces null and a type error further along the pipeline.

When it is the wrong tool

For genuinely complex transformation, a few lines of Python are easier to read and maintain. jq is excellent for extraction and filtering in a pipeline and becomes write-only fairly quickly as the logic grows.

The rule of thumb: if the filter no longer fits on one line, consider a script.

Our jq guide covers the language in more depth.

Installing

sudo apt install jq       # Debian and Ubuntu
sudo dnf install jq       # Fedora
sudo pacman -S jq         # Arch

It is a single static binary, so installing it on a server you administer takes seconds and is worth doing before you need it.

Verify Your Download

Release binaries on GitHub are published with SHA-256 checksums and signatures.