← Full reference

jq

Parsing and transforming JSON — selecting fields, select, map, strings, dates, output to CSV/TSV

jq reads JSON, passes it through a filter and prints the result. A filter is a small program: . is the whole document, .field is a field's value, | passes the result on, as in the shell. A filter can produce zero, one or many values — each is printed separately.

Syntax

jq [options] 'filter' [file…]
jq [options] -f program.jq [file…]

Without a file it reads stdin. Always put the filter in single quotes, otherwise the shell will mangle $, | and quotes inside it.

Output options

OptionWhat it does
-rstrings without quotes and escaping — for further processing in the shell
-jlike -r, but without a newline after each value
-ccompact: each result on one line
-Ssort object keys
--tab / --indent Nindent with a tab / N spaces
-anon-ASCII characters as \uXXXX
-C / -Mforce color on / off
-eexit code based on the result: 1 if the last value is null or false; 4 if there's no result

Input options and variables

OptionWhat it does
-ndon't read input; data is created in the filter or read via input/inputs
-scollect all input documents into one array
-Rread lines as text, not JSON (with -s — the whole input as one string)
-f filetake the filter from a file
--arg name valuepass a string as $name
--argjson name JSONpass a number, array or object as $name
--slurpfile name fileJSON from a file — as an array in $name
--rawfile name filea file's contents as a string in $name
--args / --jsonargsremaining arguments — as strings / JSON values in $ARGS.positional

Environment variables are available as $ENV.NAME or env.NAME.

Paths and selection

FilterWhat it does
.the whole input
.a.b, .a["b"], ."a-b"a field; quotes are for names with a hyphen, space or dot
.[0], .[-1], .[2:4]element by index, the last one, a slice
.[]all array elements (or object values), one by one
.a?, .[]?the same, but no error if the type doesn't match
..recursively all values at any depth
f, gboth results, one after the other
f | gthe result of f as input to g
[ f ]collect all results of f into an array
{a: f, b}build an object; {b} = {b: .b}; {(.k): .v} — a computed key

Operators and constructs

ConstructWhat it does
+ - * / %arithmetic; + also concatenates strings, arrays and objects
== != < <= > >=comparisons
and, or, notlogic: select(.a and (.b | not))
a // bb if a is null, false or nothing
if … then … elif … else … endcondition
try f catch gcatch an error; f? — silently skip an error
. as $x | …save a value into a variable
reduce .[] as $x (0; . + $x)fold: accumulate a result over the elements
def f: …;your own function
.a = v, .a |= f, .a += vassign, update via a filter, add
del(.a)delete a field or elements
"\(.name): \(.age)"interpolate values into a string

Built-in functions

FunctionsWhat they do
length, keys, keys_unsorted, has("k"), typelength (of a string, array, object), keys, key presence, type
select(cond), empty, error("msg")filtering; "nothing"; an error
map(f), map_values(f)apply to each array element / object value
add, any(cond), all(cond), min, max, min_by(f), max_by(f)sum/concatenation, at least one / all, minimum, maximum
sort, sort_by(f), group_by(f), unique, unique_by(f), reversesorting, grouping, unique values
first, last, first(f), limit(n; f), range(n)first/last values, generating numbers
flatten, index(x), contains(x), inside(x)flatten, find a position, check containment
to_entries, from_entries, with_entries(f)object ↔ array of {key, value}; rename or filter keys
paths, path(f), getpath(p), setpath(p; v)working with paths inside a document
tostring, tonumber, tojson, fromjsontype conversion, JSON inside a string
split(s), join(s), ascii_downcase, ascii_upcasestrings
startswith, endswith, ltrimstr, rtrimstrprefixes and suffixes
test(re), match(re), capture(re), sub(re; s), gsub(re; s)regular expressions (the "i" flag as the second argument — case-insensitive)
now, todate, fromdate, strftime(fmt)time: Unix time ↔ ISO 8601
input, inputsthe next input document / all remaining ones (together with -n)
@csv, @tsv, @sh, @base64, @base64d, @uri, @html, @jsonformat a value as CSV, TSV, shell arguments, Base64…

Examples

cat > users.json <<'EOF'
{"users":[
  {"name":"anna","age":31,"roles":["admin","dev"],"active":true},
  {"name":"bob","age":25,"roles":["dev"],"active":false}
]}
EOF

# pretty-print and check that the JSON is valid at the same time
jq . users.json

# names one per line, without quotes
jq -r '.users[].name' users.json

# only active users over 30
jq -r '.users[] | select(.active and .age > 30) | .name' users.json

# who has the admin role
jq -r '.users[] | select(.roles | index("admin")) | .name' users.json

# a new object per user — one line per record
jq -c '.users[] | {name, roles: (.roles | length)}' users.json

# number of records and average age
jq '.users | length' users.json
jq '[.users[].age] | add / length' users.json

# how many users in each group
jq -c '.users | group_by(.active) | map({active: .[0].active, count: length})' users.json

# to TSV for sort, awk, cut
jq -r '.users[] | [.name, .age] | @tsv' users.json

# safely substitute a value from a shell variable
jq --arg n "$USER" '.owner = $n' users.json

# merge several JSON files into an array
jq -s '.' a.json b.json

# lines of text → a JSON array
printf 'one\ntwo\n' | jq -R . | jq -s -c .

# Unix time to a date
echo '{"ts":1700000000}' | jq -r '.ts | todate'

# "edit a file": jq has no -i, write to a temp file and swap it in
jq '.users[1].active = true' users.json > users.tmp && mv users.tmp users.json

Pitfalls

  • There's no -i. jq '…' f.json > f.json empties the file before jq reads it. Write to a temporary file and mv it.
  • Without -r strings stay quoted: "anna". For a shell variable or a loop you usually need -r.
  • A nonexistent field is null, not an error. A typo in a name silently gives null. Add -e to get a non-zero exit code.
  • // also fires on false. .active // true turns a real false into true. For boolean fields check explicitly: if .active == null then true else .active end.
  • A field with a hyphen: jq reads .a-b as ".a minus b". Write ."a-b" or .["a-b"].
  • | binds weaker than a comma. .a | length, .b means .a | (length, .b), and .b is looked up inside .a. Use parentheses: (.a | length), .b.
  • Don't splice shell values into the filter. jq ".name == \"$x\"" breaks on quotes in $x. Pass data via --arg / --argjson.
  • --arg always gives a string. With --arg n 5, the comparison .age > $n compares a number with a string. For numbers use --argjson.
  • .users[] produces several separate values, not an array. To get an array again, wrap it in [ … ] or use map.
  • A parse error (parse error: Invalid numeric literal) means the input wasn't JSON: an HTML error page, an empty response, extra text. Check the input without jq.

See also

yq · curl · xmllint · sort · awk