# Homebrew
brew install jq

# MacPorts
sudo port install jq
Copy

# scoop
scoop install jq

# winget
winget install jqlang.jq

# Chocolatey
choco install jq
Copy

# Debian / Ubuntu
sudo apt-get install jq

# CentOS / RHEL / Fedora
sudo dnf install jq
# 或
sudo yum install jq

# Arch
sudo pacman -S jq
Copy

echo '{"a":1}' | docker run --rm -i ghcr.io/jqlang/jq:latest '.a'
Copy

git clone https://github.com/jqlang/jq.git
cd jq
autoreconf -fi
./configure --with-oniguruma=builtin
make -j8
sudo make install
Copy

jq --version
# jq-1.7.1
Copy

jq [options] '<filter>' [file...]
Copy

# 美化输出
echo '{"name":"Tom","age":20}' | jq '.'

# 输出：
# {
#   "name": "Tom",
#   "age": 20
# }
Copy

echo '{"a":1}' | jq '.'
Copy

echo '{"user":{"name":"Tom","age":20}}' | jq '.user.name'
# "Tom"

# 深层字段链式访问
jq '.user.address.city'

# 字段名含特殊字符，用 ."xxx"
echo '{"a-b":1}' | jq '."a-b"'
Copy

echo '{"a":1}' | jq '.b?'
# null（不报错）
Copy

echo '[10,20,30]' | jq '.[1]'
# 20

# 负索引从尾部取
jq '.[-1]'   # 最后一个元素
Copy

echo '[10,20,30,40,50]' | jq '.[1:4]'
# [20,30,40]

# 省略首尾
jq '.[2:]'   # 第3个到最后
jq '.[:2]'   # 前2个
Copy

echo '[1,2,3]' | jq '.[]'
# 1
# 2
# 3

# 对象迭代
echo '{"a":1,"b":2}' | jq '.[]'
# 1
# 2
Copy

echo '{"users":[{"name":"Tom"},{"name":"Jerry"}]}' | jq '.users | .[] | .name'
# "Tom"
# "Jerry"
Copy

echo '{"a":1,"b":2}' | jq '.a, .b'
# 1
# 2

echo '{"a":1,"b":2}' | jq '[.a, .b]'
# [1, 2]
Copy

echo '{"a":1,"b":2}' | jq '(.a + .b)'
# 3
Copy

echo '{"a":1,"b":2}' | jq 'keys'
# ["a","b"]

echo '{"a":1,"b":2}' | jq 'to_entries'
# [{"key":"a","value":1},{"key":"b","value":2}]

echo '{"name":"Tom","age":20}' | jq 'to_entries | map(.value)'
# [20,"Tom"]
Copy

# 取偶数
echo '[1,2,3,4,5]' | jq 'map(select(. % 2 == 0))'
# [2,4]

# 按字段排序并取最大
echo '[{"n":3},{"n":1},{"n":2}]' | jq 'max_by(.n)'
# {"n":3}

# 分组统计
echo '[{"t":"a","v":1},{"t":"a","v":2},{"t":"b","v":3}]' \
  | jq 'group_by(.t) | map({t:.[0].t, sum:(map(.v)|add)})'
# [{"t":"a","sum":3},{"t":"b","sum":3}]

# range 生成
jq -n 'range(5)'
# 0 1 2 3 4

jq -n '[range(0;10;2)]'
# [0,2,4,6,8]
Copy

# CSV 输出
echo '[{"name":"Tom","age":20},{"name":"Jerry","age":18}]' | jq -r '.[] | [.name,.age] | @csv'
# "Tom",20
# "Jerry",18

# 正则替换
echo '"hello 2026"' | jq -r 'gsub("[0-9]+"; "YEAR")'
# hello YEAR

# base64
echo '"hello"' | jq -r '@base64'
# aGVsbG8=
Copy

echo '{"a":3,"b":4}' | jq '.a as $a | .b as $b | $a * $a + $b * $b'
# 25

# 解构对象
echo '{"user":{"name":"Tom","age":20}}' \
  | jq '.user as {$name, $age} | {$name, $age, adult: ($age >= 18)}'
# {"name":"Tom","age":20,"adult":true}

# 解构数组
echo '[1,2,3]' | jq '. as [$a, $b, $c] | $a + $b + $c'
# 6
Copy

# 定义一个求平方的函数
echo '[1,2,3]' | jq 'def sq: . * .; map(sq)'
# [1,4,9]

# 带参数的函数
jq -n 'def add3($a;$b;$c): $a+$b+$c; add3(1;2;3)'
# 6

# 递归：求阶乘
jq -n 'def fact: if . <= 1 then 1 else . * (.-1 | fact) end; 5 | fact'
# 120
Copy

echo '5' | jq 'if . > 10 then "big" elif . > 3 then "mid" else "small" end'
# "mid"

# 简化的三元替代（注意 jq 没有三元运算符，但可以用 // 提供默认值）
echo 'null' | jq '. // "default"'
# "default"
Copy

# 求和
echo '[1,2,3,4,5]' | jq 'reduce .[] as $x (0; . + $x)'
# 15

# 拼接字符串
echo '["a","b","c"]' | jq 'reduce .[] as $x (""; . + $x)'
# "abc"

# 统计频次
echo '["a","b","a","c","a","b"]' \
  | jq 'reduce .[] as $k ({}; .[$k] = ((.[$k] // 0) + 1))'
# {"a":3,"b":2,"c":1}
Copy

echo '[1,2,3,4]' | jq 'foreach .[] as $x (0; . + $x; {sum: ., item: $x})'
# {"sum":1,"item":1}
# {"sum":3,"item":2}
# {"sum":6,"item":3}
# {"sum":10,"item":4}
Copy

# 路径
echo '{"a":{"b":1}}' | jq 'paths'
# []
# ["a"]
# ["a","b"]

# 修改字段（产生新对象）
echo '{"a":1,"b":2}' | jq '.a = 10'
# {"a":10,"b":2}

# 批量更新
echo '{"a":1,"b":2}' | jq '.a += 10 | .b += 100'
# {"a":11,"b":102}

# 用路径更新
echo '{"a":{"b":1}}' | jq '.a.b = 99'
# {"a":{"b":99}}

# 递归更新所有 number 加 1
echo '{"a":1,"b":{"c":2}}' | jq 'walk(if type == "number" then . + 1 else . end)'
# {"a":2,"b":{"c":3}}
Copy

# 找出 JSON 中所有的字符串
echo '{"a":"x","b":{"c":"y","d":1}}' | jq '.. | strings'
# "x"
# "y"

# 找出所有名为 id 的字段值
echo '{"id":1,"items":[{"id":2}]}' | jq '.. | .id? // empty'
# 1
# 2
Copy

# 多个文件
jq -s '.' file1.json file2.json   # 合并成数组
jq -s 'add' file1.json file2.json # 合并成对象

# -R 读取原始文本，按行处理
echo -e "a\nb\nc" | jq -R '.'
# "a"
# "b"
# "c"

# -R -s 读取全部文本
echo '{"x":1}' | jq -Rs '.'
# "{\"x\":1}\n"

# 从 stdin 读多行 JSONL
cat events.jsonl | jq -c '.'
Copy

NAME="Tom"
echo '{"name":"Tom","age":20}' | jq --arg n "$NAME" 'select(.name == $n)'
# {"name":"Tom","age":20}
Copy

AGE=20
echo '[{"name":"Tom","age":20},{"name":"Jerry","age":18}]' \
  | jq --argjson a "$AGE" 'map(select(.age >= $a))'
# [{"name":"Tom","age":20}]
Copy

echo '[{"id":1}]' > a.json
echo '[{"id":2}]' > b.json
jq -n --slurpfile a a.json --slurpfile b b.json '{a:$a, b:$b}'
Copy

echo "hello" > text.txt
jq -n --rawfile t text.txt '{content:$t}'
Copy

jq -n '{name:"Tom", time: now | todate}'
# {"name":"Tom","time":"2026-06-29T01:22:00Z"}
Copy

# 美化
curl -s https://api.github.com/repos/jqlang/jq | jq '.'

# 取字段
curl -s https://api.github.com/repos/jqlang/jq | jq '.stargazers_count'

# 压缩成一行
curl -s https://api.github.com/repos/jqlang/jq | jq -c '{name, stars: .stargazers_count}'
Copy

# 取出所有 error 级别日志的 message
cat app.log | jq -r 'select(.level == "error") | .message'

# 按时间排序后输出前 5 条
cat app.log | jq -s 'sort_by(.ts) | .[:5]'

# 统计每种 level 的数量
cat app.log | jq -s 'group_by(.level) | map({level:.[0].level, count:length})'
Copy

echo '[{"name":"Tom","age":20,"city":"NY"},{"name":"Jerry","age":18,"city":"LA"}]' \
  | jq -r '.[] | [.name, .age, .city] | @csv'
# "Tom",20,"NY"
# "Jerry",18,"LA"
Copy

echo '[{"id":1,"name":"a"},{"id":2,"name":"b"}]' \
  | jq -r '.[] | [.id, .name] | @tsv'
# 1	a
# 2	b
Copy

# 把目录下所有 json 合并成数组
jq -s '.' *.json > all.json

# 按 id 合并（去重）
jq -s 'map(.) | unique_by(.id)' *.json
Copy

# 把 age 加 1 后写回文件
jq '.age += 1' data.json > tmp && mv tmp data.json

# 批量修改嵌套字段
jq '.users[].active = true' data.json
Copy

# 查看响应头里的分页信息
curl -sI https://api.github.com/repos/jqlang/jq | grep -i link

# 把接口返回的列表里每条记录的 url 提取出来
curl -s https://api.github.com/users/torvalds/repos \
  | jq -r '.[].html_url'
Copy

# 从一个接口取数据，处理后写入文件
curl -s https://api.github.com/repos/jqlang/jq/contributors \
  | jq -r '.[] | "\(.login)\t\(.contributions)"' \
  > contributors.tsv
Copy

echo '{"name":"Tom"}' | jq '.name'
# "Tom"   ← 带引号，shell 里赋值会出问题

echo '{"name":"Tom"}' | jq -r '.name'
# Tom     ← 裸字符串
Copy

# .[] 把数组拆成流（多个输出）
echo '[1,2,3]' | jq '.[]'

# [] 把流收集成数组
echo '[1,2,3]' | jq '[.[]]'

# -s 把多个输入对象合并成数组
echo -e '{"a":1}\n{"a":2}' | jq -s '.'
# [{"a":1},{"a":2}]
Copy

# 错误：先 map 再 select，会得到数组而不是元素
echo '[{"n":1},{"n":2}]' | jq 'map(select(.n > 1))'
# [{"n":2}]

# 想要元素流：
echo '[{"n":1},{"n":2}]' | jq '.[] | select(.n > 1)'
# {"n":2}
Copy

# 缺字段默认值
echo '{"a":1}' | jq '.b // 0'
# 0

# 可选访问避免报错
echo '{"a":1}' | jq '.b.c?'
# null
Copy