jqコマンドの使い方完全ガイド｜インストール・抽出・curl連携

近年のLinuxサーバー管理やクラウド運用（AWS CLI、GitHub API、Kubernetes、Dockerコンテナログ）において、実務で扱うデータ形式は JSONがデファクトスタンダード となっています。しかし、シェルスクリプトでJSONを扱う際、従来の grep や sed 、 awk だけでパースしようとして正規表現の罠にハマったり、エスケープ地獄で苦戦した経験はありませんか？

こうした現場の悩みを一撃で解決するのが jq コマンド です。 jq は、コマンドライン上で複雑なJSONデータを高速かつ自由自在に整形・抽出・加工・フィルタリングできる専用のCLIツールです。

本記事では、Linux環境における jq コマンドの各OS別インストール手順から、実務で最重要となる 「主要オプション早見表」「特定キー抽出」「配列展開」「selectフィルター」「curlと連携したWeb API自動化」「CSV/TSV変換」 まで、現場ですぐにコピペして使える具体例を交えて体系的に解説します。

---

jqコマンドとは？LinuxでJSONを自在に扱う必須ツール

JSONの整形（Pretty Print）・値抽出・加工を行うCLI標準ツール

jq は、コマンドライン上でJSONデータを軽量かつ柔軟に処理するための専用プロセッサです。C言語で書かれており、外部依存関係なしで単一バイナリとして高速に動作します。

Web APIのレスポンスやクラウドサービスのCLI出力は、人間にとって読みにくい1行の圧縮形式（Minified JSON）で返されることが日常茶飯事です。 jq を使うことで、瞬時に見やすいインデント付きの形式（Pretty Print）に整形したり、ネストされた階層から目的のキーだけを抜き出すことが可能になります。

基本構文：ファイル直接指定と標準入力パイプ渡し

jq の基本構文は非常にシンプルです。第1引数に「フィルタ（加工ルール）」を指定し、第2引数に対象ファイルを渡します。また、他のコマンドからパイプで標準入力を渡して処理することもできます。

# 基本構文（引数にファイルを直接渡す推奨スタイル）
jq 'フィルタ' sample.json

# 基本構文（標準入力からパイプで渡すスタイル）
cat sample.json | jq 'フィルタ'

実務スクリプトでは、無駄な cat の呼び出し（UUOC: Useless Use of cat）を避け、ファイルを直接引数として渡すか、 curl などのAPIコマンドから直接パイプで繋ぐ記法を推奨します。

---

各OS・環境へのjqインストール手順

jq は主要なLinuxディストリビューションやmacOS、Windows環境のパッケージマネージャーからワンライナーで簡単にインストールできます。

Ubuntu / Debian環境でのインストール（apt）

UbuntuやDebian系の環境では、標準の apt パッケージマネージャーを使用してインストールします。

# パッケージインデックスを更新してjqをインストール
sudo apt update && sudo apt install -y jq

RHEL / CentOS / AlmaLinux環境でのインストール（dnf / yum）

RHEL系やCentOS、AlmaLinux、Rocky Linuxでは、 dnf （または yum ）を使用します。EPELリポジトリが有効化されていれば即座に導入できます。

# AlmaLinux / Rocky Linux / RHEL 8以降（dnf）
sudo dnf install -y jq

# CentOS 7などのレガシー環境（yum）
sudo yum install -y epel-release && sudo yum install -y jq

macOS環境でのインストール（Homebrew）

macOSでは、 Homebrew を利用して簡単にインストールできます。

# Homebrewでjqをインストール
brew install jq

Windows環境（WSL2 / Git Bash / winget）でのインストールと確認

Windows環境で開発やサーバー操作を行う場合、利用するシェル環境に応じて以下の方法で導入します。

• WSL2（Ubuntu等）: 上記のUbuntu手順（sudo apt install -y jq）を実行します。
• winget（Windows Package Manager）: PowerShellやコマンドプロンプトから導入する場合。
• Git Bash: インストーラーまたはChocolatey / Scoop経由で導入可能です。

# Windowsのwingetを使用する場合（PowerShell等で実行）
winget install jqlang.jq

# インストール後のバージョン確認（全環境共通）
jq --version
# 出力例: jq-1.7.1

正常にバージョン番号が出力されれば、インストールは完了です。

---

必ず覚えるべきjqコマンドの主要オプション早見表

jq コマンドをシェルスクリプトで実用する際、オプションの使い分けがスクリプトの安全性と可読性を大きく左右します。特に押さえておくべき主要オプションを一覧表にまとめました。

主要オプション一覧比較表（-r, -c, -s, -S, -e）

オプション	正式名称	機能概要	主な利用シーン・実務のポイント
-r	--raw-output	文字列を囲むダブルクォートを取り除き、プレーンテキストとして出力	シェル変数代入時の最重要オプション。パスや引数の破壊を防ぐ。
-c	--compact-output	整形（Pretty-print）を行わず、1行に圧縮して出力	ログ集約や while read ループ処理で行分割バグを防ぐ必須オプション。
-s	--slurp	複数のJSONストリームやファイルを単一の巨大な配列として読み込む	改行区切りのJSONログや複数ファイルを一度に集計・合体する際に利用。
-S	--sort-keys	出力JSONのオブジェクトキーをアルファベット順にソート	設定ファイルやAPIレスポンスの diff（差分比較）を容易にする。
-e	--exit-status	フィルタ結果が false または null の場合に終了ステータス1を返す	Bashの if 条件分岐やCI/CDパイプラインのエラー検知に最適。

シェル変数代入で最重要な「-r（raw-output）」の仕組みと事故防止

実務で最も初心者がハマりやすいのが、 -r オプションの付け忘れです。

通常、 jq はJSONの仕様に準拠して文字列をダブルクォートで囲んで出力します。これをそのままシェル変数に代入してしまうと、クォート自体が文字列の一部として変数に含まれてしまいます。

# サンプルJSON
echo '{"endpoint": "api.example.com", "port": 443}' > server.json

# 【NG例】 -r を付けない場合
ENDPOINT=$(jq '.endpoint' server.json)
echo "接続先: ${ENDPOINT}"
# 変数の値は "api.example.com" （クォートが含まれている）
# これを curl https://${ENDPOINT} などに渡すとURL解析エラーになる！

# 【推奨】 -r オプションを付与した場合
ENDPOINT=$(jq -r '.endpoint' server.json)
PORT=$(jq -r '.port' server.json)
echo "接続先: ${ENDPOINT}:${PORT}"
# 変数の値は api.example.com （プレーンテキスト）

シェル変数に代入して後続のコマンド（ curl や ssh 、ファイルパスなど）に渡す場合は、 「必ず -r を付与する」 を鉄則として覚えましょう。

1行圧縮「-c（compact-output）」とソート「-S（sort-keys）」

-c オプションは、JSONオブジェクトを改行なしの1行形式に圧縮します。後述する while IFS= read -r line ループに渡す際、1オブジェクトが複数行にまたがっていると行単位の読み込みが壊れてしまいますが、 -c を適用することで安全な行処理が可能になります。

また、 -S オプションはキーを辞書順に並べ替えて出力します。2つのJSON設定ファイルの内容が同一かどうかを検証したい場合、キーの並び順が異なると diff コマンドで不一致と判定されますが、 jq -S '.' file1.json > f1.json && jq -S '.' file2.json > f2.json && diff f1.json f2.json と実行することで正確な差分比較が実現できます。

---

実践！よく使うjqフィルター・パーステクニック

ここからは、実務で頻出する具体的なフィルター記法を、入力JSONと実行結果をセットにして解説します。まずは以下のサンプルJSON（ users.json ）を想定します。

# テスト用データの作成
cat << 'EOF' > users.json
{
  "system": "auth-service",
  "version": 2,
  "users": [
    {
      "id": 1,
      "name": "Alice",
      "profile": {
        "email": "alice@example.com",
        "age": 28
      },
      "roles": ["admin", "developer"],
      "status": "active"
    },
    {
      "id": 2,
      "name": "Bob",
      "profile": {
        "email": "bob@example.com",
        "age": 19
      },
      "roles": ["guest"],
      "status": "pending"
    },
    {
      "id": 3,
      "name": "Charlie",
      "profile": {
        "email": "charlie@example.com",
        "age": 34
      },
      "roles": ["developer"],
      "status": "active"
    }
  ]
}
EOF

1. 特定キーの値を取得（.key）と階層ネストアクセス

トップレベルのキーを取得するには .キー名 を指定します。階層が深い場合はドットで繋いでアクセスします。

# トップレベルの特定キーを取得
jq -r '.system' users.json
# 出力結果: auth-service

# ネストされた階層へのアクセス（1人目のメールアドレス）
jq -r '.users[0].profile.email' users.json
# 出力結果: alice@example.com

2. 配列の展開（.[]）とインデックス指定（.[0]）

配列の全要素を展開してストリーム（改行区切り）にするには .[] を使用します。特定の要素を取り出す場合はインデックス番号 .[0] を指定します。末尾の要素は .[-1] で取得できます。

# 全ユーザーの name を一覧で取得
jq -r '.users[].name' users.json
# 出力結果:
# Alice
# Bob
# Charlie

# 先頭ユーザー（インデックス0）の名前を取得
jq -r '.users[0].name' users.json
# 出力結果: Alice

# 末尾ユーザー（インデックス-1）の名前を取得
jq -r '.users[-1].name' users.json
# 出力結果: Charlie

3. 条件指定で絞り込む（select関数）

select(条件式) は、指定した条件が真（true）になるオブジェクトのみを抽出するフィルタです。SQLの WHERE 句のように直感的に利用できます。

# status が "active" のユーザーのみ抽出
jq -c '.users[] | select(.status == "active")' users.json
# 出力結果:
# {"id":1,"name":"Alice","profile":{"email":"alice@example.com","age":28},"roles":["admin","developer"],"status":"active"}
# {"id":3,"name":"Charlie","profile":{"email":"charlie@example.com","age":34},"roles":["developer"],"status":"active"}

# 複数条件：年齢が20歳以上（age >= 20）かつステータスが active の名前を取得
jq -r '.users[] | select(.profile.age >= 20 and .status == "active") | .name' users.json
# 出力結果:
# Alice
# Charlie

4. 部分一致で検索する（contains関数 / test関数）

文字列の一部が含まれているかどうかを検索したい場合は contains() や正規表現を扱える test() を使用します。

# roles 配列に "admin" が含まれているユーザーを抽出（contains）
jq -r '.users[] | select(.roles | contains(["admin"])) | .name' users.json
# 出力結果: Alice

# メールアドレスが "@example.com" で終わるか正規表現で検証（test）
jq -r '.users[] | select(.profile.email | test("@example\\.com$")) | .name' users.json
# 出力結果:
# Alice
# Bob
# Charlie

5. 複数フィールドを抽出して新しいJSONを再構築

元のJSONから不要な項目を削ぎ落とし、必要なフィールドだけで構成された新しいJSONオブジェクトや配列を構築できます。

# 必要なキーだけを抜き出した新しいオブジェクトを生成
jq '.users[] | {user_name: .name, user_email: .profile.email}' users.json
# 出力結果:
# {
#   "user_name": "Alice",
#   "user_email": "alice@example.com"
# }
# ...

# 配列全体を再ラップして新しいJSON配列を作成
jq '[.users[] | {id: .id, name: .name}]' users.json
# 出力結果:
# [
#   {"id": 1, "name": "Alice"},
#   {"id": 2, "name": "Bob"},
#   {"id": 3, "name": "Charlie"}
# ]

6. 要素数・配列長のカウント（length関数）

length フィルタを使用すると、配列の要素数、オブジェクトのキー数、文字列の文字数をカウントできます。

# ユーザー配列の全件数を取得
jq '.users | length' users.json
# 出力結果: 3

# 1人目のユーザーが持つロールの数をカウント
jq '.users[0].roles | length' users.json
# 出力結果: 2

---

curlとjqを組み合わせたWeb APIレスポンス処理の実践例

jq コマンドが真価を発揮するのは、 curl コマンドと連携してWeb APIから取得したデータを自動処理する場面 です。

なお、 curl コマンドを用いたHTTPリクエスト（GET/POST/ヘッダー送信等）の基礎知識については、当サイトの解説記事 【Linux】curlコマンドの使い方完全ガイド｜GET/POST・JSON送信・オプション早見表 を合わせて参照してください。

REST APIからcurlで取得したJSONをjqでパースしてシェル変数に代入

GitHub REST APIから特定リポジトリの最新リリースタグ名を取得し、シェル変数に格納する実践スクリプトです。

#!/usr/bin/env bash
set -euo pipefail

REPO="jqlang/jq"
API_URL="https://api.github.com/repos/${REPO}/releases/latest"

# curlでJSONを取得し、jq -r で特定キー（tag_name）を抽出して変数に格納
LATEST_TAG=$(curl -sL "${API_URL}" | jq -r '.tag_name')

echo "リポジトリ [${REPO}] の最新リリース: ${LATEST_TAG}"
# 出力例: リポジトリ [jqlang/jq] の最新リリース: jq-1.7.1

HTTPステータスコードとJSONエラーの安全なハンドリング

本番運用のスクリプトでは、APIがエラー（404や500等）を返した場合にHTMLやエラーJSONが降ってくる可能性があります。これを考慮せずに jq を直接実行すると、構文エラーや空変数による二次障害を引き起こします。

curl -w でHTTPステータスコードを末尾に付加して取得し、レスポンスコードを検証した上で jq を実行するのが実務の鉄則です。

#!/usr/bin/env bash
set -euo pipefail

ENDPOINT_URL="https://httpbin.org/status/200"

# レスポンス本文とHTTPステータスコードを改行区切りで同時に取得
RESPONSE=$(curl -s -w "\n%{http_code}" "${ENDPOINT_URL}")

# 末尾行からHTTPステータスコードを取得
HTTP_STATUS=$(echo "${RESPONSE}" | tail -n 1)
# 最終行を除去して純粋なJSON本文を取得
BODY=$(echo "${RESPONSE}" | sed '$d')

# HTTPステータスが200番台か判定
if [ "${HTTP_STATUS}" -ne 200 ]; then
    echo "[エラー] HTTPリクエストに失敗しました（ステータス: ${HTTP_STATUS}）" >&2
    echo "レスポンス内容: ${BODY}" >&2
    exit 1
fi

# jq -e によるJSON妥当性検証
if ! echo "${BODY}" | jq -e . >/dev/null 2>&1; then
    echo "[エラー] レスポンスが正常なJSON形式ではありません。" >&2
    exit 1
fi

echo "[成功] 正常なJSONレスポンスを受信・検証完了"

エラー時の標準エラー出力への切り分けや >&2 の仕組みについては、 【Bash】標準エラー出力のリダイレクト完全ガイド で詳しく解説しています。

シェル変数をjqへ安全に渡す「–arg」「–argjson」の必須性

初心者が最もやってしまいがちな重大なアンチパターンが、 ダブルクォートでjqフィルタを囲み、シェル変数をインライン展開（文字列埋め込み）させる書き方 です。

# 【危険なアンチパターン】インライン展開
TARGET_NAME="Alice"
# ダブルクォート展開で変数内に記号やスペースが含まれると構文破壊やインジェクションが発生！
jq ".users[] | select(.name == \"${TARGET_NAME}\")" users.json  # 厳禁！

# 【推奨】--arg オプションを使用する
jq --arg target "${TARGET_NAME}" '.users[] | select(.name == $target)' users.json

# 数値やブール値をJSON型として渡す場合は --argjson を使用する
MIN_AGE=20
jq --argjson min "${MIN_AGE}" '.users[] | select(.profile.age >= $min)' users.json

--arg を使うと、変数の値が自動的にエスケープされた安全な文字列変数（ $target ）として jq 内に渡されます。空白やクォートが含まれていても構文が壊れる心配が一切ありません。

---

JSONをCSV/TSVに変換してシェルスクリプトでループ処理

JSONデータをExcelやスプレッドシート、あるいは従来のテキスト処理ツール（ awk や cut ）で集計・加工するために、 CSVやTSVへ変換するテクニック は実務で非常に重宝されます。

@csv / @tsv フィルタによるフラット化とエクスポート

jq には組み込みのフォーマッタ @csv と @tsv が用意されています。配列内の各フィールドをフラットなカンマ区切り・タブ区切りテキストに変換してくれます。

# ヘッダーなしのCSV出力（ダブルクォートエスケープは自動処理）
jq -r '.users[] | [.id, .name, .profile.email, .status] | @csv' users.json
# 出力結果:
# 1,"Alice","alice@example.com","active"
# 2,"Bob","bob@example.com","pending"
# 3,"Charlie","charlie@example.com","active"

# ヘッダー行を先頭に付与してCSVファイルに書き出す
jq -r '["ID", "Name", "Email", "Status"], (.users[] | [.id, .name, .profile.email, .status]) | @csv' users.json > users_report.csv

while IFS= read -r line による安全な行処理パターン

オブジェクト配列の各要素に対して、シェルスクリプトで順番にバッチ処理（バックアップや別APIへの再送など）を実行したい場合、 -c オプションと while IFS= read -r item の組み合わせ が最も堅牢な鉄板パターンです。

#!/usr/bin/env bash
set -euo pipefail

# 処理用の関数を定義
process_user() {
    local user_id="$1"
    local user_name="$2"
    local user_email="$3"
    echo "通知メール送信中: ID=${user_id}, 氏名=${user_name} (${user_email})"
    # ここに実際のメール送信や外部コマンドを記述
}

# users.json から1行1オブジェクト形式（-c）で出力し、whileループへ渡す
jq -c '.users[]' users.json | while IFS= read -r item; do
    # 各行のJSONから個別フィールドを抽出
    USER_ID=$(echo "${item}" | jq -r '.id')
    USER_NAME=$(echo "${item}" | jq -r '.name')
    USER_EMAIL=$(echo "${item}" | jq -r '.profile.email')

    # 関数を呼び出して処理
    process_user "${USER_ID}" "${USER_NAME}" "${USER_EMAIL}"
done

改行を含まない1行JSONとしてストリームを受け取るため、JSON文字列の中にスペースや特殊文字が含まれていても、行分割事故が起こりません。関数設計や引数の安全な受け渡しについては、 【Bash】関数の作り方・呼び出し方完全ガイド を参考にしてください。

---

つまずきやすいポイントとエラー対処

実務現場で jq を使用している際、直面しやすいエラーやつまずきポイントと、その解決策をまとめました。

ハイフンや特殊記号を含むキー名の指定（."key-name"）

キー名にハイフン（ - ）やアットマーク（ @ ）などの特殊文字が含まれている場合、 .app-settings のように書くと、 jq は「 .app から settings を引き算する」と解釈して構文エラー（または予期せぬ演算）を起こします。

# ハイフンを含むJSON
echo '{"app-config": {"max-connections": 100}}' > config.json

# 【エラー】ハイフンが減算と誤認される
jq '.app-config.max-connections' config.json
# jq: error: Cannot subtract string from object...

# 【解決策1】キー名をダブルクォートで囲む
jq -r '."app-config"."max-connections"' config.json
# 出力結果: 100

# 【解決策2】ブラケット記法を使用する
jq -r '.["app-config"]["max-connections"]' config.json
# 出力結果: 100

「Cannot index array with string」エラーの原因と解決

現場で最も頻出するエラーが jq: error: Cannot index array with string "name" です。

これは、 ルート要素が配列（[...]）であるデータに対して、直接オブジェクトのキー（.name）を指定したこと が原因です。

# 配列データ
echo '[{"name": "Alice"}, {"name": "Bob"}]' > list.json

# 【エラー】配列に対して直接キーを指定
jq '.name' list.json
# jq: error: Cannot index array with string "name"

# 【解決策1】配列を展開（.[]）してからキーを指定
jq -r '.[].name' list.json
# 出力結果:
# Alice
# Bob

# 【解決策2】特定インデックスを指定
jq -r '.[0].name' list.json
# 出力結果: Alice

データ構造が不明なときは、まず jq 'type' file.json を実行してルートが "array" なのか "object" なのかを確認しましょう。

null値のハンドリングと empty 関数・// 演算子

対象キーが存在しない場合、 jq はエラーにならず null を返します。しかし、シェルスクリプトで null が返ると後続の判定処理で困る場合があります。

このようなケースでは、 // （オルタナティブ演算子） によるデフォルト値の設定や、 empty 関数 による除外が有効です。

# ニックネームが未定義のデータ
echo '{"name": "Charlie"}' > user.json

# 通常は null が出力される
jq -r '.nickname' user.json
# 出力: null

# // 演算子でフォールバック（デフォルト値）を指定
jq -r '.nickname // "名無し"' user.json
# 出力: 名無し

# キーが存在しない場合に何も出力したくない場合は empty を使う
echo '[{"id": 1, "val": 10}, {"id": 2}]' > data.json
jq -r '.[] | .val // empty' data.json
# 出力結果: 10 （valが存在しない2つ目の要素はスキップされる）

---

まとめ｜jqコマンド チートシート

Linux環境でのJSON処理に欠かせない jq コマンドの要点をまとめます。

実務で即戦力となる3大原則の整理

1. シェル変数への代入は -r が鉄則：ダブルクォートを排除したプレーンテキストを出力し、URLやファイルパスの破壊を防ぐ。
2. 配列のループ処理は -c と while read：改行なしの1行JSONに圧縮して渡すことで、内部改行による行分割事故を根絶する。
3. シェル変数の受け渡しは --arg / --argjson：フィルタ文字列へのインライン展開を避け、インジェクションと構文エラーを防止する。

頻出ワンライナー チートシート

やりたいこと	コマンド例
JSONインデント整形	jq '.' data.json
クォートなしで値抽出	jq -r '.key' data.json
ネスト階層のアクセス	jq -r '.user.profile.email' data.json
配列の一括展開	jq -r '.items[].id' data.json
条件付きフィルタ	jq -c '.[] \| select(.status == "active")' data.json
CSV変換	jq -r '.[] \| [.id, .name] \| @csv' data.json
配列件数のカウント	jq '.items \| length' data.json
curlでAPIレスポンス取得	curl -sL https://api.example.com \| jq -r '.data'

---

関連記事（内部リンク）

• 【Linux】curlコマンドの使い方完全ガイド｜GET/POST・JSON送信・オプション早見表：Web API連携やHTTPリクエスト送信の基本を網羅
• 【Bash】関数の作り方・呼び出し方完全ガイド｜引数の渡し方・戻り値・local変数を徹底解説：jqでパースしたデータを関数で安全に処理する設計
• 【Bash】標準エラー出力のリダイレクト完全ガイド｜2>&1・個別保存・/dev/null破棄の仕組み：API連携やバッチスクリプトでの堅牢なエラーハンドリング
• 【Linux】xargsコマンドの使い方早見表：jqで抽出したIDやURLの一括並列処理（-P）テクニック