Tech

jq入門｜JSONをコマンドラインで整形・抽出する基本

jq入門｜JSONをコマンドラインで整形・抽出する基本

APIのレスポンスやログをターミナルで見たとき、JSONが1行にべったり潰れていて読めない。そんな場面に何度も出くわしてきました。

ブラウザの開発者ツールに貼り直すのも面倒です。

そこで私が手放せなくなったのが jq という小さなコマンドでした。

目次

jqとは

jqは、JSONをコマンドラインで整形・抽出・変換するためのツールです。

sedやawkのJSON版だと思うと近いでしょう。

パイプで受け取ったJSONを、フィルタという短い式で好きな形に切り出せます。

2026年6月時点の最新は 1.8.2 で、配布元は以前の個人リポジトリからjqlang組織へ移っています。

インストール

OSごとに1行で入ります。

# Windows (winget)
winget install jqlang.jq

# macOS (Homebrew)
brew install jq

# Ubuntu / Debian
sudo apt install jq

入ったかどうかは jq --version で確認できます。

まず覚える3つの操作

最初に握っておくと一気に世界が変わるのが、整形・キー抽出・配列展開の3つです。

. はJSON全体を受け取って、見やすくインデントして返します。

echo '{"name":"kamome","langs":["py","js"]}' | jq '.'

.key で特定のキーだけを取り出せます。

echo '{"name":"kamome","age":36}' | jq '.name'

配列は .[] で1要素ずつにバラせます。

echo '[{"id":1},{"id":2}]' | jq '.[].id'

実戦：APIレスポンスを絞り込む

私がいちばん使うのは、curlで叩いたAPIの結果をjqに流す形です。

curl -s https://api.example.com/users | jq '.[] | {name, id}'

{name, id} のように書くと、必要なキーだけの新しいオブジェクトを組み立て直せます。

条件で絞るなら select が便利でした。

curl -s https://api.example.com/users | jq '.[] | select(.age > 30) | .name'

文字列をそのまま欲しいときは -r（raw出力）を付けます。

これを付けないとダブルクオート付きで返るので、シェル変数に入れる前のひと手間として覚えておくと楽です。

最後に

jqはインストールが一瞬で、覚える式も . と .[] と select から始められます。

ローカルでJSONを返すAPIを触る話は、過去にこんな記事も書きました。レスポンス確認の手数をさらに減らしたい方はあわせてどうぞ。

ローカルAPIに繋がらない2つの壁―VOICEVOXで検証
ローカルAPIに繋がらない2つの壁―VOICEVOXで検証
公開HTTPSページからローカルのVOICEVOX APIに繋がらない――原因はAPI設定ではなく、ブラウザのオリジン制約とツール戻り値の制限という別レイヤでした。切り分けと現実解を実作業から整理します。
あわせて読みたい

以上です。