jq Command
Intermediate Text Processing man(1)Command-line JSON processor
👁 1 views
📅 Updated: Mar 16, 2026
SYNTAX
jq [OPTIONS] FILTER [FILE...]
What Does jq Do?
The jq command is a lightweight and flexible command-line JSON processor. It is like sed, awk, and grep for JSON data — allowing you to slice, filter, map, and transform structured data with ease.
jq is essential for modern system administration and DevOps work, where JSON is the standard format for API responses, configuration files, container metadata, and cloud service outputs. Whether you are parsing Kubernetes manifests, processing API responses from curl, or extracting values from Terraform state files, jq makes working with JSON on the command line practical and powerful.
jq uses its own domain-specific language for writing filters and transformations. Despite its compact syntax, jq is surprisingly powerful — supporting conditionals, regular expressions, string interpolation, user-defined functions, and even recursive descent. It reads JSON from stdin or files, applies your filter expression, and outputs the result as formatted JSON (or raw text with -r).
jq is essential for modern system administration and DevOps work, where JSON is the standard format for API responses, configuration files, container metadata, and cloud service outputs. Whether you are parsing Kubernetes manifests, processing API responses from curl, or extracting values from Terraform state files, jq makes working with JSON on the command line practical and powerful.
jq uses its own domain-specific language for writing filters and transformations. Despite its compact syntax, jq is surprisingly powerful — supporting conditionals, regular expressions, string interpolation, user-defined functions, and even recursive descent. It reads JSON from stdin or files, applies your filter expression, and outputs the result as formatted JSON (or raw text with -r).
Options & Flags
| Option | Description | Example |
|---|---|---|
| . | Identity filter - output the entire input unchanged | echo '{"a":1}' | jq . |
| .key | Extract a specific key from an object | echo '{"name":"app"}' | jq .name |
| -r | Raw output - strip quotes from strings | echo '{"name":"app"}' | jq -r .name |
| -c | Compact output - no pretty printing | cat data.json | jq -c . |
| -e | Exit with error if output is null or false | jq -e .missing data.json |
| -s | Slurp - read all inputs into an array | cat *.json | jq -s . |
| -S | Sort keys in objects alphabetically | jq -S . config.json |
| --arg name val | Pass a string variable into the jq program | jq --arg v "hello" '{msg: $v}' <<< '{}' |
| -n | Null input - do not read any input | jq -n '{a: 1, b: 2}' |
| --rawfile name file | Read file contents into a variable as string | jq --rawfile tpl template.txt -n '{template: $tpl}' |
Practical Examples
#1 Extract a field from JSON
Extracts the name field and outputs raw text without quotes.
$ echo '{"name":"nginx","version":"1.25"}' | jq -r .name
Output:
nginx
#2 Get nested values
Access nested objects using dot notation.
$ echo '{"server":{"host":"10.0.0.1","port":8080}}' | jq '.server.port'
Output:
8080
#3 Filter array elements
Iterate array elements, filter by condition, and extract field.
$ echo '[{"name":"a","active":true},{"name":"b","active":false}]' | jq '.[] | select(.active==true) | .name'
Output:
"a"
#4 Transform JSON structure
Create a new JSON object with computed values.
$ echo '{"first":"John","last":"Doe"}' | jq '{fullname: (.first + " " + .last)}'
Output:
{"fullname": "John Doe"}
#5 Parse curl API response
Fetch JSON from an API and extract specific fields into a new object.
$ curl -s https://api.github.com/repos/jqlang/jq | jq '{name: .name, stars: .stargazers_count, language: .language}'#6 Count array elements
Returns the number of elements in an array or keys in an object.
$ echo '[1,2,3,4,5]' | jq length
Output:
5
#7 Map and transform arrays
Transform each array element into a new structure.
$ echo '[{"name":"a","cpu":50},{"name":"b","cpu":80}]' | jq '[.[] | {service: .name, load: (.cpu | tostring + "%")}]'#8 Merge two JSON files
Deep merge two JSON objects. Second file values override first.
$ jq -s '.[0] * .[1]' defaults.json overrides.jsonTips & Best Practices
Always use -r for scripting: When assigning jq output to shell variables, use -r to get raw strings without quotes: VERSION=$(jq -r .version package.json)
Null handling: jq returns "null" (string) for missing keys. Use the // operator for defaults: jq '.missing // "default"' to avoid null in your scripts.
jq as a JSON validator: Use jq . file.json to validate and pretty-print JSON. If the file has syntax errors, jq will report the exact error location.
Combine with other tools: jq works great in pipelines: kubectl get pods -o json | jq '.items[] | {name: .metadata.name, status: .status.phase}'
Install jq: Install with: apt install jq (Debian/Ubuntu), dnf install jq (Fedora/RHEL), brew install jq (macOS). Available on virtually every platform.
Frequently Asked Questions
How do I pretty-print JSON on the command line?
Pipe JSON through jq with the identity filter: cat file.json | jq . — This formats the JSON with proper indentation and syntax highlighting.
How do I extract a value from a JSON array?
Use array indexing: jq '.[0]' for the first element, jq '.[-1]' for the last, or jq '.[] | .name' to iterate all elements and extract a field.
What is the difference between jq . and jq -r .?
jq . outputs JSON with quotes around strings. jq -r . outputs raw strings without quotes — essential when using output in shell scripts or passing to other commands.
How do I modify a JSON file with jq?
jq does not edit files in place. Use a temp file: jq '.version = "2.0"' config.json > tmp.json && mv tmp.json config.json. Or use sponge from moreutils.
Can jq handle multiple JSON objects (JSONL/ndjson)?
Yes. jq processes newline-delimited JSON naturally. Each line is treated as a separate input. Use -s (slurp) to combine them into a single array if needed.
Related Commands
More Text Processing Commands
Master Linux with Professional eBooks
Curated IT eBooks covering Linux, DevOps, Cloud, and more
Browse Books →