jq コマンドは、JSON を入力として受け取りフィルタで抽出・整形・変換・集計を行う CLI ツールです。sed/awk/grep の JSON 版のように扱え、curl で取得した API レスポンスの整形や、ログ・設定ファイルの加工、シェルスクリプトでの自動処理に日常的に使われます。(JqLang)
この記事では、jq コマンドのインストール方法から基本構文、実務で使うオプション、初心者がつまずきやすいポイントまでを実行例つきで解説します。
jqコマンドとは
jq は JSON データをコマンドラインで自由に加工できる軽量ツールです。curl や API から取得した JSON をそのまま人間が読むのは大変ですが、jq を通すだけで整形表示され、さらに特定のキーだけを抜き出したり、条件で絞り込んだりできます。(JqLang)
- API レスポンスを整形して読みやすくする
- JSON から必要なフィールドだけを抽出する
- 複数の JSON ファイルを結合・集計する
- ログやテキストを JSON に組み立て直す
インストール方法
主要な OS ではパッケージマネージャーから 1 コマンドで導入できます。
| 環境 | インストールコマンド |
|---|---|
| Debian / Ubuntu | sudo apt install jq |
| RHEL / CentOS / Fedora | sudo dnf install jq |
| macOS（Homebrew） | brew install jq |
| Windows（winget） | winget install jqlang.jq |
インストール後は次のコマンドでバージョンを確認し、正しく導入できているか確かめます。
jq --version
# jq-1.7.1構文（Syntax）
# 基本形
jq [OPTIONS] 'FILTER' [FILE...]
# 代表例
curl ... | jq '.' # 整形表示（pretty print）
jq -r '.items[] | .name' data.json # 生文字列で出力
jq -f script.jq input.json # フィルタをファイルから読み込み
jq -n --arg k v '{(env.k):$v}' # 入力なしで JSON を構築
- フィルタ（
FILTER）は jq 言語で記述します。.は恒等（入力をそのまま出力）。(JqLang)
主なオプション一覧
| オプション | 説明 | 使用例 |
|---|---|---|
-r, --raw-output | 文字列を JSON 文字列でなく生の文字列で出力 | jq -r '.version' package.json (JqLang) |
-j, --join-output | -r の派生。改行を付けないで連結出力 | jq -j '.[]' (JqLang) |
-c, --compact-output | 1 行に圧縮して出力（機械処理向き） | jq -c '.items' (JqLang) |
-S, --sort-keys | オブジェクトの キーをソートして出力 | jq -S '.' (JqLang) |
-C / -M | 強制カラー / モノクロ出力 | `jq -C ‘.’ |
--tab / --indent N | インデントをタブ / スペース数 N に変更 | jq --indent 4 '.' (JqLang) |
-s, --slurp | 入力全体を 配列1件として読み込む | jq -s 'add' files*.json (JqLang) |
-R, --raw-input | 入力を JSON として 解釈せず生テキストで受け取る | jq -R 'split(\":\")' (JqLang) |
-n, --null-input | 入力を読まず null を 1 度だけ流す（JSON の生成に） | jq -n '{now:now}' (JqLang) |
--stream | 巨大 JSON を ストリーミングで処理（path,leaf のペア） | jq --stream '...reduce...' (JqLang) |
--seq | application/json-seq 形式で入出力 | jq --seq '.' (JqLang) |
-f, --from-file FILE | フィルタをファイルから読み込む | jq -f filter.jq data.json (JqLang) |
-L DIR | モジュール検索パスを追加（import 用） | jq -L lib -f main.jq (JqLang) |
--arg name val | 文字列変数を $name に注入 | jq --arg q "tokyo" '.city==$q' (JqLang) |
--argjson name json | JSON 値を変数として注入 | jq --argjson ids '[1,2]' 'map(select(.id IN($ids[])))' (JqLang) |
--argfile name file / --slurpfile name file | ファイル内容を変数へ（JSON/行スループ） | jq --slurpfile cfg cfg.json '. + $cfg[0]' (JqLang) |
-e, --exit-status | 最終結果で 終了コード を設定（監視/判定に便利） | jq -e 'length>0' (JqLang) |
実行例
最初の一歩：整形表示（pretty print）
説明: 引数なしの . フィルタは、JSON を色付き・インデント付きで見やすく整形するだけの、最も基本的な使い方です。
コマンド:
echo '{"name":"jq","version":"1.7.1"}' | jq '.'
{
"name": "jq",
"version": "1.7.1"
}
整形表示とキー抽出
説明: API レスポンスを整形し、配列要素の名前だけ取り出します。
コマンド:
curl -s https://api.github.com/repos/jqlang/jq/commits?per_page=3 \
| jq '.[] | {sha, author: .commit.author.name}'
jq -r '.[].commit.message' commits.json
(JqLang)
条件抽出と並び替え
説明: .items の中から active==true だけに絞り、名前でソート。
コマンド:
jq '.items | map(select(.active)) | sort_by(.name) | .[].name' data.json
（select/ sort_by は定番フィルタです） (JqLang)
生テキストから JSON を組み立てる（ログ処理）
説明: key:value 形式の行を -R で読み、オブジェクトへ変換。
コマンド:
cat kv.txt | jq -R 'split(":") | { (.[0]): .[1] }' | jq -s 'add'
(JqLang)
巨大 JSON をストリーミングで集計（メモリ節約）
説明: ルート配列が非常に大きい場合でも --stream で段階処理。
コマンド:
jq --stream 'foreach ( .[] as $p (0; if ($p|length==2 and ($p[0]|last)=="price") then . + $p[1] else . end ))' big.json
（--stream は path と値のペアを逐次出力します） (JqLang)
エラー例：入力が JSON でない
説明: 入力が JSON でないのに -R を付けないとパースエラーになります。
コマンド:
echo 'not json' | jq '.'
出力例（例）:
parse error: Invalid numeric literal at line 1, column 5
対処: テキストなら -R を使う、あるいは JSON に整形してから渡します。(JqLang)
よくある質問
jq -r と jq . の違いは？
jq '.' は結果を JSON 形式（文字列ならダブルクォート付き）で出力しますが、jq -r はダブルクォートを外した生の文字列で出力します。シェルスクリプトで値をそのまま変数に代入したい場合は -r を使うのが基本です。
jq がインストールされているか確認するには？
jq --version または which jq で確認できます。未インストールの場合は上記の「インストール方法」を参照してください。
配列の要素数を数えるには？
jq '.items | length' data.json
JSON 以外（YAML など）を扱いたい場合は？
jq は JSON 専用です。YAML を扱いたい場合は、後述の yq（内部で jq 互換のフィルタ構文を使える版もあります）を利用します。
関連コマンド
- curl : API レスポンスを取得して
jqに渡す相棒。 - grep : テキストの行単位検索。JSON を
jq -rで整形してからgrepに渡すことも多い。 - sed / awk : テキスト全般の置換・抽出・集計。
jqは JSON 特化版に相当。 yq: YAML 用のフィルタ（内部でjq互換表現を使える版もあり）。jo: シェルから JSON を構築するユーティリティ。jqplay: ブラウザで jq を試せるプレイグラウンド。(jqプレイグラウンド)
備考
- 引用とエスケープ: シェルのメタ文字と jq の構文が衝突しやすいので、Unix シェルでは 単一引用符
'...'を推奨（PowerShell/Windows では規則が異なる）。(JqLang) - 整形と配信: 人間向けは既定（カラー/整形）、機械向けは
-cと-r/-jを併用。(JqLang) - 大規模データ: 全体を配列化する
-sは簡単ですがメモリ消費が増えます。巨大データは--streamとreduce/foreachで段階処理を。(JqLang) - モジュール:
-Lで検索パスを追加しimportで関数を再利用できます。(JqLang) - 終了コード:
-eで 0/1/4 などに分岐でき、シェルの if/CI 判定に便利です。(JqLang)
参考
- 公式サイト（トップ）: https://jqlang.org/
- マニュアル（最新 / v1.8）: https://jqlang.org/manual/
- チュートリアル: https://jqlang.org/tutorial/
- GitHub（リポジトリ）: https://github.com/jqlang/jq
- jq Playground: https://play.jqlang.org/
- Arch Linux man ページ: https://man.archlinux.org/man/jq.1.en
コメント