LinuxのjqコマンドでJSONを処理する入門｜DockerやAPIの結果をターミナルで見やすく整形する方法

宮崎智広 この記事の監修：宮崎智広（Linux実務・教育歴20年以上・受講者3,100名超）
ＨＯＭＥ ＞ Linux技術 リナックスマスター.JP（Linuxマスター.JP） ＞ 【Linux入門】初心者のための基礎知識・講座 ＞ LinuxのjqコマンドでJSONを処理する入門｜DockerやAPIの結果をターミナルで見やすく整形する方法
「DockerコマンドやAPIのレスポンスを出したら、{から始まる読みにくい文字の塊が表示された。これは何？どうやって読めばいいの？」

Linuxを使い始めると、必ずといっていいほどJSON形式のデータに遭遇します。
Dockerの状態確認、WebサービスのAPI、クラウドの設定情報など、現代のLinux環境ではJSONがいたるところで登場します。

この記事では、JSONデータをLinuxのターミナルで手軽に扱えるようにするコマンド「jq」の使い方を解説します。
インストールから基本操作、Dockerとの組み合わせまで、ITが初めての方でも理解できるよう一つひとつ説明します。

実行環境: Ubuntu 24.04 LTS（WSL2・VPS）および Rocky Linux 9（VPS）で動作確認済み

この記事のポイント

・jqはJSON出力を整形・抽出できるLinuxの標準的なコマンドツール
・apt install jq または dnf install jq で1分でインストールできる
・. フィルタで整形、.キー名 で値抽出、.[] で配列展開が基本操作
・Dockerやクラウド設定の確認など、現場で毎日使うレベルで役立つ


「このままじゃマズい」と感じていませんか？
参考書を開く気力もない、同年代に取り残される不安——
でも安心してください。プロのエンジニアはコマンドを暗記していません。
「現場で使える型」を効率よく使いこなしているだけです。
姓・名・メールの3つだけ／30秒／解除は3秒 ／ 詳細はこちら

JSONとは何か？ jqが必要になる理由

JSON（ジェイソン）とは「JavaScript Object Notation」の略で、コンピュータ同士がデータをやり取りするときによく使われる形式です。
難しい名前ですが、内容は「名前と値のセット」を{}や[]でまとめたシンプルなデータ形式です。

たとえば、Dockerでコンテナの状態を確認するときや、天気予報サービスのAPIを呼び出したときに、次のようなJSONが返ってきます。

# DockerコマンドのJSON出力（例）
{"Id":"a3b7c9d1e5f2","Name":"/web","State":{"Status":"running","Running":true},"NetworkSettings":{"IPAddress":"172.17.0.2","Ports":{"80/tcp":[{"HostIp":"0.0.0.0","HostPort":"80"}]}}}
すべてが1行にまとまっていて、どこに何の情報があるのか一目では分かりません。
これを読みやすく整形し、必要な部分だけ取り出してくれるのが jq コマンドです。

jq を使うと、同じデータが次のように表示されます。

# jqで整形した場合の表示（実行結果）
{
  "Id": "a3b7c9d1e5f2",
  "Name": "/web",
  "State": {
    "Status": "running",
    "Running": true
  },
  "NetworkSettings": {
    "IPAddress": "172.17.0.2",
    "Ports": {
      "80/tcp": [
        {
          "HostIp": "0.0.0.0",
          "HostPort": "80"
        }
      ]
    }
  }
}
構造が一目でわかり、欲しい情報をすぐ見つけられます。

jqが役立つ主な場面
・Dockerコンテナの詳細情報（docker inspectの出力）を確認する
・GitHub・AWSのCLIコマンドがJSON形式で返す結果を読む
・ChatGPTやClaude APIなどのAI APIレスポンスを整形する
・設定ファイル（package.json、docker-compose.ymlなど）の内容を素早く確認する

jqのインストール方法

jq はほとんどのLinuxディストリビューションの標準パッケージリポジトリに含まれており、1コマンドでインストールできます。

1. Ubuntu / Debian（WSL2を含む）

WSL2のUbuntuや、さくらVPS・ConoHaなどでUbuntuを使っている場合は apt でインストールします。

# パッケージリストを更新してjqをインストール
sudo apt update
sudo apt install -y jq
インストール中に確認画面が出る場合は Y と入力してEnterを押してください。

2. Rocky Linux / RHEL / AlmaLinux

RHEL系のサーバーでは dnf を使います。

# dnfでjqをインストール
sudo dnf install -y jq

3. インストールの確認

インストールが完了したら、バージョンを確認して動作を確かめます。

# jqのバージョン確認
jq --version
実行結果: 

jq-1.7.1
バージョン番号が表示されれば、正常にインストールされています。

jqの基本操作（最初に覚える5つのパターン）

jq のコマンド形式は次の通りです。

# 基本形式（1）パイプで渡す
コマンド | jq 'フィルタ'

# 基本形式（2）ファイルを読む
jq 'フィルタ' ファイル名.json
「フィルタ」というのは「JSONのどの部分を取り出すか」を指定する書き方です。
順番に覚えていきましょう。

1. .（ドット）で全体を見やすく表示する

.（ドット1つ）は「全体を整形して表示する」という意味のフィルタです。
1行にまとまっているJSONを、インデント付きで見やすく整形してくれます。

まず練習用のJSONデータを用意します。

# 練習用のJSONをechoで作る
echo '{"name":"taro","age":30,"city":"Tokyo"}' | jq '.'
実行結果: 

{
  "name": "taro",
  "age": 30,
  "city": "Tokyo"
}
キーと値が整然と並んで表示されました。これが jq '.' の基本です。

2. キー名で特定の値を取り出す

.キー名 の形で、特定のキーの値だけを取り出せます。

# "name" の値だけ取り出す
echo '{"name":"taro","age":30,"city":"Tokyo"}' | jq '.name'

# "city" の値だけ取り出す
echo '{"name":"taro","age":30,"city":"Tokyo"}' | jq '.city'
実行結果: 

"taro"
"Tokyo"
ネストされたキーの取り出し方（階層が深い場合）
JSONがネスト（入れ子）になっている場合は、.親キー.子キー のようにドットでつなぎます。

# address の中の city を取り出す
echo '{"name":"taro","address":{"city":"Tokyo","zip":"100-0001"}}' | jq '.address.city'
実行結果: 

"Tokyo"

3. .[] で配列を展開する

[...] で囲まれた「配列」形式のJSONは、.[] で各要素を展開できます。

# 配列を展開して1件ずつ表示する
echo '[{"name":"taro"},{"name":"hanako"},{"name":"jiro"}]' | jq '.[]'
実行結果: 

{
  "name": "taro"
}
{
  "name": "hanako"
}
{
  "name": "jiro"
}
配列の特定の番号だけ取り出す場合は .[0]（0番目、つまり最初の要素）のように指定します。

# 最初（0番目）の要素だけ取り出す
echo '[{"name":"taro"},{"name":"hanako"},{"name":"jiro"}]' | jq '.[0]'

# 2番目の要素を取り出す
echo '[{"name":"taro"},{"name":"hanako"},{"name":"jiro"}]' | jq '.[1]'
実行結果: 

{
  "name": "taro"
}
{
  "name": "hanako"
}

4. | でフィルタを連結する

Linuxのパイプ（|）と同様に、jqのフィルタもパイプでつなげられます。
「配列を展開して、その中のキーを取り出す」という操作を1行で書けます。

# 配列を展開して、各要素の "name" だけを取り出す
echo '[{"name":"taro","age":30},{"name":"hanako","age":25}]' | jq '.[] | .name'
実行結果: 

"taro"
"hanako"

5. ファイルに保存されたJSONを処理する

ファイルとして保存されているJSONは、ファイル名を直接渡せます。

# data.json というファイルを整形して表示
jq '.' data.json

# data.json の "name" キーだけ取り出す
jq '.name' data.json
cat data.json | jq '.' と書いても同じ結果になりますが、jq '.' data.json の方がシンプルです。

実践的な使い方 ─ Dockerと組み合わせる

ここからは、実際のLinux環境でよく使う場面を紹介します。
Dockerをインストール済みの環境（WSL2 with Docker、VPSなど）でお試しください。

1. docker inspect の結果を整形して確認する

docker inspect コンテナ名 はコンテナの詳細情報をJSONで返しますが、そのままでは読みにくい大量のデータです。
jq '.' を組み合わせると、スクロールしながら読める形式に整形できます。

# nginxコンテナの詳細情報を整形して表示
docker inspect web | jq '.'
実行結果（抜粋）: 

[
  {
    "Id": "a3b7c9d1e5f29a83b2c4d6e7f8a9b0c1d2e3f4a5",
    "Created": "2026-09-10T08:23:14.523891Z",
    "Path": "nginx",
    "Args": [
      "-g",
      "daemon off;"
    ],
    "State": {
      "Status": "running",
      "Running": true,
      "Pid": 1234
    },
    ...
  }
]

2. コンテナのIPアドレスだけを取り出す

詳細情報の中から、特定の値（IPアドレスなど）だけを素早く抜き出す使い方です。

# コンテナのIPアドレスを取り出す
docker inspect web | jq '.[0].NetworkSettings.IPAddress'
実行結果: 

"172.17.0.2"
.[0]（配列の最初の要素）の中の .NetworkSettings.IPAddress を指定しています。
この方法で、大量の情報の中から必要な値だけを1行で取り出せます。

3. 起動中のコンテナ名を一覧表示する


# docker psのJSON出力からコンテナ名だけを抽出
docker ps --format '{{json .}}' | jq -r '.Names'
実行結果: 

web
db
redis
-r オプションは「raw output」の意味で、結果の前後の引用符（"）を外してプレーンテキストで表示します。
スクリプトの中で値を変数に代入したい場合は -r を付けるのが一般的です。

フィルタの組み合わせと応用

基本操作に慣れてきたら、より実用的なフィルタを覚えましょう。

1. select()で条件に合う要素だけ抽出する

配列の中から「特定の条件に合う要素だけ」を取り出すには select() を使います。

# statusが"running"のコンテナだけを取り出す
docker inspect  | jq '.[] | select(.State.Status == "running") | .Name'
実行結果: 

"/web"
"/db"

2. keys で JSONのキー一覧を確認する

「このJSONにはどんなキーがあるか」を確認したいときは keys を使います。
初めて見るJSONを調べるときに重宝します。

# JSONのキー一覧を表示する
echo '{"name":"taro","age":30,"city":"Tokyo"}' | jq 'keys'
実行結果: 

[
  "age",
  "city",
  "name"
]
アルファベット順に並んだキーの一覧が表示されます。

3. length で要素数を数える

length は配列の要素数や文字列の長さを返します。

# 配列の要素数を数える
echo '["a","b","c","d"]' | jq 'length'

# 起動中コンテナの数を数える
docker ps --format '{{json .}}' | jq -s 'length'
実行結果: 

4
3
-s（スラーブ）オプションは、複数行のJSONをまとめて1つの配列として受け取るオプションです。

トラブルシュート・よくあるエラーと対処法

「parse error: Invalid numeric literal」が出る

入力データがJSONとして正しくない形式のとき、このエラーが出ます。

# エラーが出る例（JSONではないテキストを渡している）
echo "hello world" | jq '.'

# エラーメッセージ
parse error (Invalid numeric literal at EOF at line 1, column 12): hello world
対処法
・入力データが本当にJSON形式かどうかを確認する
・コマンドの出力がJSONかどうかをまず echo で確認してから jq に渡す
・JSON形式の出力オプション（例: docker inspect、--format json）を付け忘れていないか確認する

null が返ってくる（キーが見つからない）

指定したキーが存在しないと null が返ります。

# "email" というキーが存在しない場合
echo '{"name":"taro","age":30}' | jq '.email'
実行結果: 

null
対処法
・keys でキー一覧を確認して、正しいキー名を調べる
・大文字・小文字の違い（Name と name）や、スペルミスに注意する
・配列を展開していない場合は .[] を先に付けてから .キー名 を指定する

「No such file or directory」が出る

ファイル名を直接指定したのに、ファイルが存在しない場合のエラーです。

# 存在しないファイルを指定した場合
jq '.' config.json

# エラーメッセージ
jq: error: Could not open file config.json: No such file or directory
対処法
・ls でファイルが存在するか確認する
・現在のディレクトリ（pwd で確認）にファイルがあるか確認する
・ファイルパスのスペルミスがないか確認する

本記事のまとめ

この記事では、Linuxのjqコマンドの基本的な使い方を解説しました。
やりたいこと jqの書き方
JSONを見やすく整形する コマンド | jq '.'
特定のキーの値を取り出す コマンド | jq '.キー名'
ネストされたキーを取り出す コマンド | jq '.親.子'
配列を展開する コマンド | jq '.[]'
配列の特定要素を取り出す コマンド | jq '.[0]'
配列の各要素からキーを抽出 コマンド | jq '.[] | .キー名'
条件に合う要素だけ取り出す コマンド | jq '.[] | select(.キー == "値")'
引用符なしで出力する コマンド | jq -r '.キー名'
JSONのキー一覧を表示する コマンド | jq 'keys'
要素数を数える コマンド | jq 'length'
ファイルのJSONを処理する jq 'フィルタ' ファイル名.json
jqを覚えると、Dockerの管理、クラウドCLIの出力確認、AIのAPI連携など、現代のLinux活用シーンで何度も使う場面が出てきます。
まずは docker inspect コンテナ名 | jq '.' を試して、整形されたJSONを眺めてみてください。
「あの情報だけ取り出せないか」と思ったときに、この記事のフィルタ一覧を参考にしてみてください。

次に読む記事（Linux入門シリーズ）
・Linuxのコマンドライン入門｜ターミナルの開き方から基本操作まで
・Linuxのパイプとリダイレクト入門｜コマンドをつなげて処理を効率化する方法
・Linuxのテキスト処理入門｜cat・less・grep・headでファイルの中身を読む方法
・LinuxでDockerをはじめる入門｜コンテナとVMの違いを理解してUbuntuで最初のコンテナを動かす方法
・LinuxでOllamaを使ってAIと会話する入門｜WSL2やVPSに無料でLLMをインストールする方法

実務で使うLinuxスキル 7テーマ
・tmuxコマンドでターミナルを分割・管理する方法（シェルスクリプト）
・ssh-keygenコマンドでSSH公開鍵認証を設定する方法（セキュリティ）
・Apacheのタイムアウト設定を変更・確認する方法（サーバー構築）
・straceコマンドでプロセスのシステムコールを追跡する方法（トラブルシューティング）
・ncコマンドでネットワーク接続をテストする方法（ネットワーク）
・rsyncコマンドでファイルを同期・転送する方法（ファイルシステム・ストレージ）
・Linuxでポート番号の状態を確認するコマンド（現場コラム）
現場で通用する安全なLinuxサーバー構築の「型」を体系的に身につけたい方へ、
無料の「Linuxサーバー構築入門マニュアル（図解60ページ）」をプレゼントしています。
コマンドを「なんとなく打つ」段階から卒業したい方は、ぜひ受け取ってみてください。
無料マニュアルを受け取る ＞＞

関連記事

無料メルマガで学習を続ける

Linuxの実践スキルをメールで毎週お届け。
登録は30秒、解除もいつでも可。

登録無料・いつでも解除できます

暗記不要・1時間後にはサーバーが動く

3,100名以上が実践した「型」を無料で公開中

プロのエンジニアはコマンドを暗記していません。
「現場で使える型」を効率よく使いこなしているだけです。
その「型」を図解60Pにまとめた入門マニュアルを、完全無料でプレゼントしています。

姓・名・メールの3つだけ／30秒／解除は3秒 ／ 詳細はこちら

Linux無料マニュアル（図解60P） 名前とメールで30秒登録
宮崎 智広

この記事を書いた人

宮崎 智広（みやざき ともひろ）

株式会社イーネットマーキュリー代表。現役のLinuxサーバー管理者として20年以上の実務経験を持ち、これまでに累計3,100名以上のエンジニアを指導してきたLinux教育のプロフェッショナル。「現場で本当に使える技術」を体系的に伝えることをモットーに、実践型のLinuxセミナーの開催や無料マニュアルの配布を通じてLinux人材の育成に取り組んでいる。

趣味は、キャンプにカメラ、トラウト釣り。好きな食べ物は、ラーメンにお酒。休肝日が作れない、酒量を減らせないのが悩み。最近、ドラマ「フライトエンジェル」を観て涙腺が崩壊しました。