curlコマンドの使い方|GET・POST・JSON送信・ヘッダーとステータスコードの確認
API の動作確認、サーバーが動いているかのチェック、手順書に書かれた「このコマンドでファイルを取ってきて」――エンジニアの仕事では、curl(カール)というコマンドに出会う機会がとても多くあります。一方で、-i と -I の違い、-d と --json の使い分け、PowerShell で入力すると見慣れないエラーになる、など、つまずきやすい点もあります。
この記事では、curl の基本(GET・POST)、ヘッダーとステータスコードの確かめ方、JSON の送り方、よく使うオプションを、実際に実行した結果つきで解説します。練習には、自分の PC で起動したサーバー(127.0.0.1)と、説明用に公開されている example.com だけを使います。他人のサービスに練習で POST などを送るのはやめましょう。
実行結果は Windows 11 の PowerShell 5.1 と Git Bash で確かめたものです(2026 年 10 月)。
curl とは
curl は、URL を指定してデータを送ったり受け取ったりするコマンドです。ブラウザーがしている「ページをください(リクエスト)」「はい、どうぞ(レスポンス)」のやり取りを、コマンドで 1 回ずつ行えます。画面に表示しない情報(ヘッダーやステータスコード)を見られるので、Web や API のトラブル調査によく使われます。Linux・macOS・Windows のどれでも使えます。
Windows 10/11 には curl.exe が標準で入っている
Microsoft は 2017 年 12 月に、Windows 10 の build 17063 以降に curl を標準で入れると発表しました。この PC(Windows 11)では C:\Windows\System32\curl.exe にあり、バージョンは次のコマンドで確認できます。
curl.exe --version
curl 8.21.0 (Windows) libcurl/8.21.0 Schannel zlib/1.3.2 WinIDN WinLDAP
Release-Date: 2026-06-24
(以下省略)
Windows の curl は Microsoft が自分でビルドして Windows Update で配っているもので、curl の公式サイトの説明によると、curl プロジェクトの最新版より遅れて更新されるのがふつうです。バージョンは PC によって違うので、後で出てくる --json(curl 7.82.0 で追加)が使えるかどうかは、この 1 行目の数字で確かめてください。なお、Git for Windows にも別の curl が入っていて、この PC の Git Bash で curl --version を実行すると 8.12.1 と表示されました。どちらでも、この記事のコマンドは同じように動きました。
PowerShell 5.1 では「curl.exe」と書く
Windows PowerShell 5.1 では、curl は Invoke-WebRequest というコマンドの別名(エイリアス)です。本物の curl ではないので、curl のオプションが通じません。
Get-Alias curl
CommandType Name Version Source
----------- ---- ------- ------
Alias curl -> Invoke-WebRequest
この状態で curl -I http://127.0.0.1:8080/ と入力すると、次のようなエラーになりました。
Invoke-WebRequest : コマンドを処理できません。次の 1 つ以上の必須パラメーターが指定されていません: Uri。
エラーに Invoke-WebRequest と出ていたら、curl ではないものが動いた合図です。PowerShell では拡張子まで付けて curl.exe と入力すれば、本物の curl が動きます。コマンドプロンプト(cmd)と Git Bash では curl だけで本物が動きます。この記事では PowerShell 用のコマンドを curl.exe で書いています。PowerShell のエイリアスについては「PowerShellの基本コマンド一覧」でも解説しています。
練習用のサーバーを自分の PC で動かす
Python が入っていれば、練習用のサーバーをすぐに起動できます。作業用のフォルダーに index.html(中身は <h1>Hello curl</h1>)と、docs フォルダーの中に index.html を作り、そのフォルダーで次のコマンドを実行します。
py -m http.server 8080 --bind 127.0.0.1
--bind 127.0.0.1 を付けると、自分の PC からしかアクセスできません(同じネットワークのほかの PC に中身を見せないための指定です)。止めるときは Ctrl+C を押します。このサーバーは GET でファイルを返すだけなので、POST を試すために、受け取った内容をそのまま返す小さなサーバーも用意します。次の内容を echo_server.py という名前で保存してください。
from http.server import BaseHTTPRequestHandler, HTTPServer
class Handler(BaseHTTPRequestHandler):
def do_POST(self):
length = int(self.headers.get("Content-Length", 0))
body = self.rfile.read(length).decode("utf-8", errors="replace")
text = (
f"method: {self.command}\n"
f"Content-Type: {self.headers.get('Content-Type')}\n"
f"body: {body}\n"
)
data = text.encode("utf-8")
self.send_response(201)
self.send_header("Content-Type", "text/plain; charset=utf-8")
self.send_header("Content-Length", str(len(data)))
self.end_headers()
self.wfile.write(data)
do_PUT = do_POST
HTTPServer(("127.0.0.1", 8000), Handler).serve_forever()
別の PowerShell の画面を開いて、次のコマンドで起動します。これで、8080 番がファイルを返すサーバー、8000 番が POST の中身を返すサーバーになります。
py echo_server.py
基本:URL を指定してページを取得する(GET)
オプションを付けずに URL だけを指定すると、GET(取得)のリクエストを送り、返ってきた本文(ボディ)を画面に表示します。
curl.exe http://127.0.0.1:8080/
<h1>Hello curl</h1>
ブラウザーなら見出しとして表示されるところが、HTML のまま表示されます。curl.exe https://example.com/ とすると、example.com の HTML が表示されます。example.com は説明用に用意されているドメインですが、ページには「テストや監視に頼らないでください」と書かれているので、何度も繰り返しアクセスするような練習は自分の PC のサーバーで行いましょう。
ヘッダーとステータスコードを見る
サーバーの返事は、ステータス行(200 OK など)、ヘッダー(返事についての情報)、ボディ(本文)の 3 つでできています。curl はふだんボディだけを表示するので、それ以外を見たいときにオプションを使います。
-i:ヘッダーも一緒に表示する
curl.exe -i http://127.0.0.1:8080/
HTTP/1.0 200 OK
Server: SimpleHTTP/0.6 Python/3.12.6
Date: Sat, 17 Oct 2026 23:41:54 GMT
Content-type: text/html
Content-Length: 20
Last-Modified: Sat, 17 Oct 2026 23:41:43 GMT
<h1>Hello curl</h1>
1 行目の 200 がステータスコード(結果を表す 3 桁の番号)、空行までがヘッダー、空行の後がボディです。Content-type はデータの種類、Content-Length はボディのバイト数です。
-I:ヘッダーだけを取得する
大文字の -I は、HEAD という「ヘッダーだけください」というリクエストを送ります。ボディを受け取らないので、ページがあるかどうか、どんなサーバーかを手早く確かめるのに便利です。
curl.exe -I https://example.com/
HTTP/1.1 200 OK
Date: Sat, 17 Oct 2026 23:42:53 GMT
Content-Type: text/html; charset=utf-8
Connection: keep-alive
Server: cloudflare
allow: GET, HEAD
(以下省略)
小文字の -i は「本文に加えてヘッダーも」、大文字の -I は「ヘッダーだけ」と覚えましょう。ただし、サーバーによっては HEAD に GET と違う返事をすることがあるので、結果が怪しいときは -i でも確かめます。

-w “%{http_code}”:ステータスコードの数字だけを表示する
スクリプトでの監視などで「数字だけ欲しい」ときは、-w(書き出す内容の指定)を使います。ボディは -o NUL で捨て(Git Bash や Linux では -o /dev/null)、-s で途中経過の表示を消します。
curl.exe -s -o NUL -w "%{http_code}\n" http://127.0.0.1:8080/nothing
404
存在しないページなので 404 になりました。\n は改行で、curl が自分で改行に置き換えます。%{time_total}(かかった秒数)、%{size_download}(受け取ったバイト数)も並べられ、-w "%{http_code} %{time_total}s\n" で example.com を取得すると「200 0.055118s」と表示されました。返ってきた番号の意味は、HTTPステータスコード検索で原因と対処法まで調べられます。
-v:やり取りをすべて表示する
うまくいかない原因を調べるときは -v(詳しく表示)です。curl が送った内容まで見られます。
curl.exe -v -o NUL http://127.0.0.1:8080/
* Trying 127.0.0.1:8080...
* Established connection to 127.0.0.1 (127.0.0.1 port 8080) from 127.0.0.1 port 63630
(途中省略)
> GET / HTTP/1.1
> Host: 127.0.0.1:8080
> User-Agent: curl/8.21.0
> Accept: */*
>
* Request completely sent off
* HTTP 1.0, assume close after body
< HTTP/1.0 200 OK
< Server: SimpleHTTP/0.6 Python/3.12.6
(以下省略)
curl の公式マニュアルのとおり、行の先頭の > は curl が送ったヘッダー、< は受け取ったヘッダー、* は curl からの補足情報です。接続の段階で止まっているのか、返事でエラーが返っているのかが一目で分かります。
-L:リダイレクト(転送)をたどる
練習用サーバーで、末尾の「/」を付けずに /docs を取得すると、本文が空のまま終わります。-i を付けると理由が分かります。
curl.exe -i http://127.0.0.1:8080/docs
HTTP/1.0 301 Moved Permanently
Server: SimpleHTTP/0.6 Python/3.12.6
Date: Sat, 17 Oct 2026 23:41:54 GMT
Location: /docs/
Content-Length: 0
301 は「Location に書いた場所へ移動した」という返事です。curl はふだん転送先へ自動で行かないので、-L を付けます。
curl.exe -L http://127.0.0.1:8080/docs
<p>docs page</p>
-w "%{http_code} %{url_effective}\n" と組み合わせると、-L なしでは「301」、ありでは「200 http://127.0.0.1:8080/docs/」と表示され、最終的にどの URL にたどり着いたかも分かりました。なお公式マニュアルによると、-L で POST を送って 301・302・303 が返ると、次のリクエストは GET に変わります。

ファイルに保存する(-o・-O・-s)
-o ファイル名 は名前を決めて保存、-O(大文字)は URL の最後の部分をそのままファイル名にして保存します。
curl.exe -o page.html http://127.0.0.1:8080/
curl.exe -O http://127.0.0.1:8080/sample.csv
今いるフォルダーに page.html と sample.csv ができました。ファイルに保存するときは、受け取った量や速度の表(プログレスメーター)が表示されます。表示を消したいときは -s(静かに)を付けますが、-s だけだとエラーのメッセージまで消えます。エラーだけは表示したいときは -sS にします。止まっているサーバー(127.0.0.1:9999)で試すと、-s では何も表示されず、-sS では「curl: (7) Failed to connect to 127.0.0.1:9999 after 2038 ms: Could not connect to server」と表示されました。
-O は同じ名前のファイルがあると上書きします。大事なファイルがあるフォルダーで実行しないよう注意してください。
GET と POST の違い
HTTP のリクエストには「何をしたいか」を表すメソッドがあります。よく使うのは GET と POST です。
| GET | POST | |
|---|---|---|
| 目的 | データを取得する | データを送って処理してもらう(登録・送信など) |
| 送るデータの場所 | URL の後ろ(?q=… の部分。クエリ) | リクエストのボディ |
| curl の書き方 | URL だけ(何も付けない) | -d・--json を付けると自動で POST |
| 繰り返し送ったとき | ふつうはサーバーの状態を変えない | 送るたびに登録などが起きることがある |
POST は「送るたびに何かが起きる」ことがあるので、練習で他人のサービスに送ってはいけない理由もここにあります。GET で検索語などを送るときは、URL に日本語や空白をそのまま入れず、URL エンコード(%E5%A4%AA のような形への変換)をします。-G --data-urlencode "q=太郎 山田" を付けると、curl がエンコードして URL の後ろに付け、GET /?q=%E5%A4%AA%E9%83%8E+%E5%B1%B1%E7%94%B0 というリクエストを送りました。エンコードの結果は URLエンコード・デコードツールでも確かめられます。
-d:POST でデータを送る
-d(--data)でデータを指定すると、curl は POST でボディに入れて送ります。-X POST を書かなくても POST になります。
curl.exe -d "name=taro&age=20" http://127.0.0.1:8000/
method: POST
Content-Type: application/x-www-form-urlencoded
body: name=taro&age=20
Content-Type が application/x-www-form-urlencoded になっています。これは Web のフォームから送るときと同じ形式で、-d を使うと curl が自動でこの値を付けます。値に日本語や記号が入るときは、-d の代わりに --data-urlencode "name=太郎 山田" とすると、name=%E5%A4%AA%E9%83%8E+%E5%B1%B1%E7%94%B0 のようにエンコードして送られました。
JSON を送る(–json と -H)
API に JSON を送るときは、ボディが JSON であることを Content-Type ヘッダーで伝える必要があります。curl 7.82.0 以降なら --json が一番簡単です。公式マニュアルによると、--json は Content-Type: application/json と Accept: application/json の 2 つのヘッダーを自動で付けます。
シェルごとの引用符の書き方
JSON には「”」が入るので、使うシェルによって書き方が変わります。Git Bash や Linux では、全体を「’」で囲みます。
curl --json '{"name":"taro","age":20}' http://127.0.0.1:8000/
ところが PowerShell 5.1 で同じように書くと、curl.exe に渡る途中で「”」が消えてしまいます。実際に送られたボディは次のとおりで、もう JSON ではありません。
method: POST
Content-Type: application/json
body: {name:taro,age:20}
PowerShell 5.1 では、「”」の前に「\」を付けます。
curl.exe --json '{\"name\":\"taro\",\"age\":20}' http://127.0.0.1:8000/
method: POST
Content-Type: application/json
body: {"name":"taro","age":20}
コマンドプロンプトでは「’」が囲みとして働かず、'{"name":"taro"}' と書くと「’」ごと、しかも「”」が消えて送られました。"{\"name\":\"taro\"}" のように「”」で囲み、中の「”」に「\」を付けます。
JSON をファイルから送る(おすすめ)
引用符で悩まない一番確実な方法は、JSON をファイルに書いて「@ファイル名」で指定することです。data.json に次の内容を UTF-8 で保存します。
{
"name": "花子",
"age": 25
}
curl.exe --json "@data.json" http://127.0.0.1:8000/
method: POST
Content-Type: application/json
body: {
"name": "花子",
"age": 25
}
PowerShell では「@」で始まる語に特別な意味(スプラッティング)があり、囲まずに @data.json と書くとエラーになったので、"@data.json" と「”」で囲んでいます。送る前に JSON の書き間違い(カンマの付け忘れなど)がないかは、JSON整形ツールで確かめられます。Python で JSON を作る方法は「PythonでJSONを扱う方法」を見てください。
–json が使えない古い curl では -H と –data-binary
7.82.0 より前の curl では、ヘッダーを -H で自分で付けます。ファイルから送るときは -d ではなく --data-binary を使ってください。
curl.exe -H "Content-Type: application/json" --data-binary "@data.json" http://127.0.0.1:8000/
公式マニュアルに書かれているとおり、-d @ファイル名 はファイルの改行を取り除いて送ります。実際に -d で送ると、ボディは { "name": "花子", "age": 25} と 1 行になりました。JSON なら意味は変わりませんが、改行に意味があるデータ(CSV など)は壊れてしまいます。--data-binary なら改行もそのまま送られました。
-H でヘッダーを付ける・-X でメソッドを変える
-H "名前: 値" でヘッダーを付けられます。何個でも並べられ、curl が最初から付けるヘッダーと同じ名前なら置き換わります。
curl.exe -v -o NUL -H "X-Request-Id: test-001" -H "Accept: text/plain" http://127.0.0.1:8080/
> GET / HTTP/1.1
> Host: 127.0.0.1:8080
> User-Agent: curl/8.21.0
> X-Request-Id: test-001
> Accept: text/plain
Accept がふだんの */* から text/plain に置き換わりました。API のトークン(Authorization: Bearer ...)も -H で付けますが、コマンドの履歴に残るので、人に見せる画面や共有する手順書には本物の値を書かないでください。
-X はメソッドの名前を指定します。PUT や DELETE を送るときに使います。
curl.exe -X PUT --json '{\"id\":1}' http://127.0.0.1:8000/
method: PUT
Content-Type: application/json
body: {"id":1}
公式マニュアルには「ふつうはこのオプションは必要ない」とあります。-d や --json を付ければ自動で POST になるので、-X POST は書かなくてかまいません。また、-X は送る言葉を書き換えるだけで curl の動き方は変えないため、ヘッダーだけ欲しいときは -X HEAD ではなく -I を使います。-X と -L を一緒に使うと、転送先にも同じメソッドが送られるので注意が必要です。
よく使うオプションの早見表
| オプション | 長い名前 | 意味 |
|---|---|---|
| -i | –include | ヘッダーも表示する |
| -I | –head | ヘッダーだけ取得する(HEAD) |
| -L | –location | リダイレクトをたどる |
| -o ファイル | –output | 名前を決めて保存する |
| -O | –remote-name | URL の名前で保存する |
| -s | –silent | 進み具合とメッセージを表示しない |
| -S | –show-error | -s と一緒に使い、エラーだけ表示する |
| -v | –verbose | やり取りを詳しく表示する |
| -w 書式 | –write-out | 終了後に情報を表示する(%{http_code} など) |
| -H “名前: 値” | –header | ヘッダーを付ける |
| -d データ | –data | POST でデータを送る |
| なし | –json データ | JSON を POST で送る(7.82.0 以降) |
| -X メソッド | –request | メソッドを指定する |
| -f | –fail | 400 以上のときにボディを表示せず失敗にする |
よくある間違い・トラブル
404 や 500 でも「成功」扱いになる
curl は、サーバーから返事が来れば、それが 404 でも正常終了します。PowerShell で 404 のページを取得した直後の $LASTEXITCODE(終了コード)は 0 でした。スクリプトで失敗を見分けたいときは -f を付けます。-f を付けると、同じ 404 で終了コードが 22 になりました。公式マニュアルには、この方法は完全ではない(認証が必要なときなどに一部の返事がすり抜ける)とも書かれているので、確実に見たいときは -w "%{http_code}" で数字を確かめます。
「Failed to connect」と表示される
「curl: (7) Failed to connect」は、相手のサーバーにつながらなかったという意味です(ステータスコードではなく、curl の終了コード 7)。ポート番号の間違い、サーバーの起動忘れ、プロキシやファイアウォールなどが原因です。まず -v で、どこまで進んだかを見ます。
証明書のエラーで -k を付けてしまう
HTTPS で証明書のエラーが出たとき、ネットで -k(--insecure)を付ける方法が紹介されていることがあります。これは証明書の確認をやめるオプションで、通信相手が本物かどうかを確かめずに送受信することになります。社内のテスト環境など、理由が分かっている場合以外は使わず、エラーの原因(日付・プロキシ・証明書の期限など)を調べましょう。
よくある質問
PowerShell の Invoke-WebRequest を使ってはいけないのですか?
使ってかまいません。Invoke-WebRequest http://127.0.0.1:8080/ -UseBasicParsing を実行すると、結果がオブジェクトとして返り、.StatusCode で 200 を取り出せました。PowerShell の中で結果を加工するなら便利です。ただ、ネット上の手順書やエラー報告は curl で書かれていることが多いので、両方を知っておくと困りません。
ブラウザーでは表示されるのに、curl だと違う結果になります
ブラウザーは、リダイレクトを自動でたどり、Cookie や多くのヘッダーを付けて送っています。まず -L を付け、それでも違うときは -v で送ったヘッダーを確かめ、ブラウザーの開発者ツール(F12 の「ネットワーク」タブ)と見比べます。
関連する記事・ツール
- HTTPステータスコード検索:404・500 などの意味と原因・対処法を確認
- URLエンコード・デコードツール:日本語の URL やクエリを変換・分解
- JSON整形ツール:送る JSON・返ってきた JSON を整形して構文チェック
- PowerShellの基本コマンド一覧|コマンドプロンプト・Linuxとの対応表と実行例
- PythonでJSONを扱う方法|json.loads・dumpsの使い方とエラー対処
- REST APIとは?HTTPメソッド・ステータスコードの意味とcurlでの試し方
- HTTPとHTTPSの違いとは?暗号化・証明書の仕組みとcurlでの確認方法
- PythonでHTTPリクエストを送る方法|urllibとrequestsの使い方と例外処理