2026年10月18日 / 最終更新日 : 2026年10月18日 ふじながただし コラム

Python urllibの使い方｜GET・POST・JSON・エラー処理とurllib3・requestsとの違い

Pythonのurllibは、インストール不要でHTTP通信とURLの処理ができる標準ライブラリです。import urllib.request のようにサブモジュールまで書いて使い、GETは urlopen()、POSTやヘッダーの指定は Request、クエリ文字列の組み立ては urllib.parse.urlencode() で行います。

この記事は、urllibでよく使う処理を1ページで一通り試せるようにまとめた入門です。コードはすべてPython 3.12.15で実行し、実際の出力を載せています（2026年10月18日実行）。個々の関数の細かい使い方は、各見出しから専用の記事へ進めます。

urllibとは｜4つのサブモジュール

urllibは4つのモジュールをまとめたパッケージです（Python公式ドキュメント urllib）。

モジュール 役割 よく使うもの
urllib.request URLを開いて読む（HTTP通信） urlopen()、Request
urllib.parse URLの分解・組み立て urlencode()、urlparse()、quote()
urllib.error urllib.requestが出す例外 HTTPError、URLError
urllib.robotparser robots.txtの解析 RobotFileParser

import urllib だけでは動かない

パッケージ本体だけを読み込んでも、サブモジュールは使えるようになりません。

import urllib
try:
    urllib.request.urlopen
except AttributeError as e:
    print("AttributeError:", e)

実行結果：

AttributeError: module 'urllib' has no attribute 'request'

import urllib.request や from urllib.parse import urlencode のように、使うサブモジュールを明示してください。

urllib・urllib2・urllib3・requestsの違い

名前が似たものが多く、検索でも混ざりやすいので最初に整理します。

名前 種類 インストール 今の扱い
urllib Python 3の標準ライブラリ 不要 この記事の対象
urllib2 Python 2の標準ライブラリ — Python 3には無い。機能はurllib.requestとurllib.errorへ移った
urllib3 外部ライブラリ（PyPI） pip install urllib3 最新版は2.8.0（PyPI、2026年10月18日確認）
requests 外部ライブラリ（PyPI） pip install requests 内部でurllib3を使う高水準のHTTPクライアント

urllib3そのものの使い方はurllib3の解説記事、requestsはPython requestsとは？使い方を初心者向けに解説を参照してください。Python公式ドキュメントのurllib.requestのページにも「より高水準のHTTPクライアントインターフェースとして Requestsパッケージ がお奨め」と書かれています。それでもurllibを使うのは、ライブラリを追加できないサーバーや、配布するスクリプトの依存を増やしたくない場合です。

GETでページを取得する｜urlopen()

import urllib.request

with urllib.request.urlopen("https://example.com/", timeout=10) as res:
    print(res.status, res.headers.get_content_charset())
    html = res.read().decode("utf-8")

print(html.splitlines()[0][:40])
print(len(html) > 0)

実行結果：

200 utf-8
<!doctype html><html lang=en><head><meta
True

ポイントは3つです。

  • with で開くと、読み終わったあと接続が閉じられる
  • read() の戻り値は bytes。文字列にするには decode() が要る。文字コードは res.headers.get_content_charset() で確認できる
  • timeout を付ける。付けないと、相手が応答しないときにいつまでも待ち続ける

urlopen()の引数や戻り値の詳細はPython urlopen()とは？標準ライブラリでHTTP通信する方法で解説しています。タイムアウトで起きる例外はPython TimeoutErrorの原因と対処法も参考になります。

POSTでJSONを送る｜Request

Request に data を渡すとPOSTになり、headers でContent-TypeやUser-Agentを指定できます。送信先には、送った内容をそのまま返すテスト用サービスhttpbin.orgを使いました。

import json
import urllib.request

payload = json.dumps({"name": "techgym", "lang": "python"}).encode("utf-8")
req = urllib.request.Request(
    "https://httpbin.org/post",
    data=payload,                      # data を渡すと POST になる
    headers={"Content-Type": "application/json", "User-Agent": "my-script/1.0"},
)
print(req.get_method())

with urllib.request.urlopen(req, timeout=10) as res:
    body = json.load(res)              # レスポンスのJSONを辞書に

print(body["json"])
print(body["headers"]["User-Agent"])

実行結果：

POST
{'lang': 'python', 'name': 'techgym'}
my-script/1.0

data は bytes で渡す必要があるため、json.dumps() の結果を encode("utf-8") しています。レスポンスは json.load(res) でそのまま辞書になります。メソッドを明示したいときは Request(url, data=..., method="PUT") のように書けます。ヘッダーの付け方はPython urllib.request.Requestとは？ヘッダやPOSTを送る方法でさらに詳しく扱っています。

URLを組み立てる・分解する｜urllib.parse

from urllib.parse import urlencode, urlparse, parse_qs, quote

query = urlencode({"q": "Python 入門", "page": 2})
url = "https://example.com/search?" + query
print(url)

u = urlparse(url)
print(u.scheme, u.netloc, u.path)
print(parse_qs(u.query))
print(quote("テック ジム/a"))

実行結果：

https://example.com/search?q=Python+%E5%85%A5%E9%96%80&page=2
https example.com /search
{'q': ['Python 入門'], 'page': ['2']}
%E3%83%86%E3%83%83%E3%82%AF%20%E3%82%B8%E3%83%A0/a
  • urlencode()：辞書からクエリ文字列を作る。日本語や空白も変換される
  • urlparse()：URLをスキーム、ホスト、パスなどに分ける
  • parse_qs()：クエリ文字列を辞書に戻す（値はリスト）
  • quote()：パスの一部などをパーセントエンコードする。/ は初期設定では変換されない

f文字列でクエリを連結すると、値に & や = が入ったときに別のパラメータとして解釈されてしまいます。クエリは urlencode() で作るのが安全です。詳しくはPython urlencode()とは？とurllib.parse.quoteとunquoteの使い方をご覧ください。

エラー処理｜HTTPErrorとURLError

urllibは、404や500などのエラー応答を受け取ると例外を投げます（requestsは raise_for_status() を呼ばない限り例外にしません）。

import urllib.error
import urllib.request

for url in ["https://httpbin.org/status/404", "https://no-such-host.invalid/"]:
    try:
        urllib.request.urlopen(url, timeout=10)
    except urllib.error.HTTPError as e:      # サーバーは返事をした（404・500など）
        print("HTTPError", e.code, e.reason)
    except urllib.error.URLError as e:       # そもそも届かなかった
        print("URLError", type(e.reason).__name__)

print(issubclass(urllib.error.HTTPError, urllib.error.URLError))

実行結果：

HTTPError 404 NOT FOUND
URLError gaierror
True
例外 起きる場面 中身
HTTPError サーバーは応答したが、ステータスがエラー（404・500など） e.code、e.reason
URLError そもそも届かない（名前解決の失敗、接続拒否など） e.reason（上の例ではsocket.gaierror）

HTTPError は URLError のサブクラスなので（最後の行の True）、except は HTTPError を先に書きます。逆にすると404も URLError の節で捕まってしまいます。

Python 2のコードを書き換える

古い記事のコードを動かして ModuleNotFoundError: No module named 'urllib2' が出たら、Python 2向けのコードです。次のように置き換えます。

Python 2 Python 3
urllib2.urlopen() urllib.request.urlopen()
urllib2.Request() urllib.request.Request()
urllib2.HTTPError urllib.error.HTTPError
urllib.urlencode() urllib.parse.urlencode()
urllib.quote() urllib.parse.quote()
urlparse.urlparse() urllib.parse.urlparse()

使い分けの早見表

やりたいこと 使うもの
ページやAPIをGETする urllib.request.urlopen(url, timeout=10)
JSONをPOSTする、ヘッダーを付ける urllib.request.Request(url, data=..., headers=...)
レスポンスのJSONを読む json.load(res)
クエリ文字列を作る urllib.parse.urlencode()
URLを分解する urllib.parse.urlparse()、parse_qs()
エラーで分岐する urllib.error.HTTPError → URLError の順で捕まえる

手元で動かしながら覚えたい方は、テックジムの無料Python講座（ゼロからはじめるPython入門講座）も利用できます。東京本校で毎週土曜13:00〜14:00に開いていて、これまでに全国で2万人以上が参加しています。講座のあとは19時まで自習室を使い、講師に質問できます。

よくある質問

Q. urllibはpip installが必要ですか？

いいえ。urllibはPythonに最初から入っている標準ライブラリなので、インストールは不要です。pip install urllib3 で入るのは別物のurllib3です。

Q. urllibとurllib3の違いは何ですか？

urllibは標準ライブラリ、urllib3はPyPIで配布されている外部ライブラリです。名前は似ていますが別のプロジェクトで、urllib3はコネクションプーリングなどを持ち、requestsの内部でも使われています。

Q. import urllib だけで使えないのはなぜですか？

urllibはパッケージで、import urllib だけではサブモジュールのrequestやparseが読み込まれないためです。import urllib.request のようにサブモジュールまで書きます。

Q. urllib2はPython 3で使えますか？

使えません。Python 2のurllib2の機能は、Python 3ではurllib.requestとurllib.errorに移りました。

Q. requestsとどちらを使うべきですか？

追加インストールできるならrequestsのほうが短く書けます。Python公式ドキュメントも高水準のHTTPクライアントとしてRequestsを勧めています。インストールできない環境や依存を増やしたくないスクリプトではurllibを使います。

まとめ

urllibは標準ライブラリだけでHTTP通信とURL処理を済ませたいときの道具です。import urllib.request とサブモジュールまで書き、GETは urlopen()、POSTは Request、クエリは urlencode()、エラーは HTTPError を先に捕まえる。この4点と timeout の指定を押さえれば、たいていのスクリプトは書けます。

あわせて読みたい

対面・無料｜東京・永田町で毎週土曜日13時

1回の参加で、プログラミングの構造がわかる

ゼロからはじめるPython入門講座

8年間・累計600回開催／これまで全国で2万人以上が参加

「やはり対面で聞けるのはとても気づきがあり、価値があると思います」

参加者の声

  • 本当に初心者からの講座です。プログラミングに触ったことがなくて大丈夫です
  • 対面だから、その場で聞けます。つまずいた所を持ち帰らずに解決できます
  • 講座は1時間。そのあとも残って学習を続けられ、講師にも質問できます
  • 独学で挫折した方も。糸口が見つかって、講座のあと会員になる方が多くいます

無料で参加する｜開催日程を見る

参加費は無料です

プログラミング学習に関するお役立ちコンテンツ

カテゴリー
コラム
コラム
Claude Managed Agentsとは？料金・使い方・Messages APIとの違い

前の記事

Claude Managed Agentsとは？料金・使い方・Messages APIとの違いNew!!
2026年10月18日
コラム
VSCodeでPythonをデバッグする方法｜ブレークポイント・ステップ実行・launch.jsonの引数とpdb

次の記事

VSCodeでPythonをデバッグする方法｜ブレークポイント・ステップ実行・launch.jsonの引数とpdbNew!!
2026年10月18日