Terminal GuideTerminal Guide
jq icon

jq

Dev Tools•
macOSLinuxWindows
•C

Lightweight command-line JSON processor.

Official Website

Features

JSON ParsingFilteringTransformationFormatting

Installation

Homebrew
brew install jq
APT (Debian/Ubuntu)
apt install jq
Pacman (Arch)
pacman -S jq
Chocolatey
choco install jq

Why use jq?

jq is the standard tool for processing JSON data from the command line. It streamlines developer workflows by enabling API response parsing, log extraction, and configuration file editing.

Powerful Filtering

Extract only the needed data from complex JSON. Easily access nested structures.

Data Transformation

Transform JSON structure, generate new objects, and manipulate arrays with flexible transformations.

High-Speed Processing

Implemented in C for rapid processing of large JSON datasets. Supports stream processing.

Pipeline Integration

Works seamlessly with other commands like curl and cat. Excellent shell script compatibility.

Installation

Installation
# macOS (Homebrew)
brew install jq

# Ubuntu/Debian
sudo apt install jq

# Arch Linux
sudo pacman -S jq

# Windows (Chocolatey)
choco install jq

# Windows (Scoop)
scoop install jq

Basic Usage

JSON Formatting (Pretty Print)

Formatting
# Format and display compressed JSON
echo '{"name":"John","age":30}' | jq '.'

# Read and format from file
jq '.' data.json

# Format API response
curl -s https://api.example.com/users | jq '.'

Extracting Values

Value Extraction
# Get specific field
echo '{"name":"John","age":30}' | jq '.name'
# Output: "John"

# Get without quotes
echo '{"name":"John","age":30}' | jq -r '.name'
# Output: John

# Nested fields
echo '{"user":{"name":"John","address":{"city":"Tokyo"}}}' | jq '.user.address.city'
# Output: "Tokyo"

Array Operations

Array Operations
# All array elements
echo '[1,2,3,4,5]' | jq '.[]'

# Specific index
echo '["a","b","c"]' | jq '.[1]'
# Output: "b"

# Slicing
echo '[1,2,3,4,5]' | jq '.[2:4]'
# Output: [3,4]

# Array length
echo '[1,2,3,4,5]' | jq 'length'
# Output: 5

Common Patterns

Parsing API Responses

API Parsing
# Get user info from GitHub API
curl -s https://api.github.com/users/octocat | jq '{
  name: .name,
  company: .company,
  location: .location,
  repos: .public_repos
}'

# Extract specific fields from multiple users
curl -s https://api.github.com/users | jq '.[] | {login, id, type}'

# Get only repository names
curl -s https://api.github.com/users/octocat/repos | jq -r '.[].name'

Filtering

Filtering
# Extract elements matching conditions
echo '[{"name":"Alice","age":25},{"name":"Bob","age":35}]' | jq '.[] | select(.age > 30)'

# Elements with specific value
echo '[{"status":"active"},{"status":"inactive"}]' | jq '.[] | select(.status == "active")'

# Multiple conditions
echo '[{"name":"Alice","age":25,"active":true}]' | jq '.[] | select(.age > 20 and .active == true)'

Data Transformation

Transformation
# Create new structure
echo '{"firstName":"John","lastName":"Doe"}' | jq '{fullName: (.firstName + " " + .lastName)}'

# Array to object
echo '[{"key":"a","value":1},{"key":"b","value":2}]' | jq 'from_entries'
# Output: {"a":1,"b":2}

# Transform with map
echo '[1,2,3]' | jq 'map(. * 2)'
# Output: [2,4,6]

# Group by
echo '[{"type":"a","val":1},{"type":"b","val":2},{"type":"a","val":3}]' | jq 'group_by(.type)'

Advanced Usage

Variables and Functions

Variables
# Use variables
echo '{"items":[1,2,3]}' | jq --arg prefix "item_" '.items | map($prefix + tostring)'

# Use values from external file
echo '{"users":["alice","bob"]}' | jq --slurpfile ids ids.json '.users as $u | $ids[0]'

# Use environment variables
export MY_VAR="hello"
echo '{}' | jq --arg v "$MY_VAR" '{greeting: $v}'

Processing Multiple Files

Multiple Files
# Combine multiple JSON files into array
jq -s '.' file1.json file2.json file3.json

# Merge multiple files
jq -s 'add' file1.json file2.json

# Process JSONL (newline-delimited JSON)
cat events.jsonl | jq -c 'select(.type == "error")'

Editing JSON

Editing
# Add field
echo '{"name":"John"}' | jq '. + {age: 30}'

# Update field
echo '{"name":"John","age":25}' | jq '.age = 30'

# Delete field
echo '{"name":"John","age":30,"temp":true}' | jq 'del(.temp)'

# Conditional update
echo '{"count":5}' | jq 'if .count > 3 then .status = "high" else .status = "low" end'

Common Options

OptionDescriptionExample
-rRaw string output (without quotes)jq -r '.name'
-cCompact output (single line)jq -c '.'
-sSlurp - combine input into arrayjq -s '.' *.json
-eExit code 1 for false/nulljq -e '.exists'
--argDefine string variablejq --arg n "John" '.name = $n'
--argjsonDefine JSON variablejq --argjson n 42 '.count = $n'

Tips

  • •jq '.' alone can format JSON. It's faster than python -m json.tool
  • •Format functions like @csv, @tsv, @base64 can convert data formats
  • •Use keys to get object keys and values to get values
  • •Use type to check value type (string, number, array, object, null, boolean)
  • •Try jq queries in browser at jqplay.org
Written by Dai AokiPublished: 2026-01-20

Related Articles

yq - YAML/JSON/XML Processor

YAML, JSON, and XML processor with jq-like syntax

tools8 min read

HTTPie - HTTP Client

User-friendly command-line HTTP client

tools8 min read

curl Command Guide

Transfer data from URLs

linux8 min read

Explore More

Browse Dev Tools

See all tools in this category

All CLI Tools

Explore all tool categories