開発を進めていると、「デジャヴュ」のような瞬間に遭遇することがあります。確かに知っているはずの関数なのに、`import`パスを見ると自分が知っていたものとは違う、というような場合です。Django開発者にとって、`urlencode`はまさにそのような存在でしょう。

Djangoを少しでも扱ったことがある方なら、`urlencode`がdjango.utils.httpにあることをご存存じでしょうが、初めて触れる開発者は、Python標準ライブラリとして有名なurllib.parse.urlencodeを使おうとすることが多いはずです（私もそうでした）。

Python標準ライブラリにも、Djangoユーティリティにも存在するこの関数、果たしてどちらを選んでも問題ないのでしょうか？結論から言うと、**「いいえ」**です。この2つの関数の、微妙でありながら決定的な違いをまとめました。

![a dev is being confused about choosing a method](/media/whitedec/blog_img/9215d69669ef4f36b9be389a5594ba1f.webp)

---

# 同じ名前なのに結果が違う？Django開発でurlencodeを使用する際によくある間違い

Pythonの`urllib.parse.urlencode`とDjangoの`django.utils.http.urlencode`は、名前と目的が同じように見えますが、DjangoバージョンはWeb開発の特殊な状況に対応するために、さらに進化を遂げた形です。

## 1. 主な違いをひと目で確認 {#sec-e4fba724ad11}

2つの関数の主な違いを以下の表にまとめました。

|**区分**|**urllib.parse.urlencode**|**django.utils.http.urlencode**|
|---|---|---|
|**所属**|Python標準ライブラリ|Django内蔵ユーティリティ|
|**実装方式**|標準ライブラリ独自実装|内部で`urllib`バージョンを拡張呼び出し|
|**基本動作**|辞書をクエリ文字列に変換|**`QueryDict`およびマルチバリュー処理に最適化**|
|**リスト処理**|`doseq=True`オプションが必須|**別途オプションなしでリストを安全に処理**|

---

## 2. なぜDjangoバージョンを別途使うのか？（最も重要な理由） {#sec-4eb807c69f0}

Djangoが標準ライブラリをそのまま使わず、あえて独自の`urlencode`を作成したのには明確な理由があります。それは、**Web環境における安定性**と**利便性**のためです。

### その1、リスト（Multi-value）処理の「安全装置」 {#sec-0927ec9ca7b1}

Webプロトコルでは、1つのキーに複数の値が格納されることがよくあります（例: `?tag=python&tag=django`）。Python標準の`urllib`バージョンは、リストをエンコードする際に`doseq=True`オプションを手動で指定する必要があります。これを忘れると、リストオブジェクト自体が文字列に変換され、`tag=['python', 'django']`のような意図しない結果が生成されてしまいます。

一方、Djangoバージョンは「Webではリストを展開して送信するのが基本」という前提で設計されており、別途オプションなしでリストデータを完璧にエンコードします。

### その2、QueryDictとの完璧な互換性 {#sec-fc334b880462}

Djangoの`request.GET`は、通常の辞書ではなく`QueryDict`オブジェクトです。`QueryDict`は、同じキーに複数の値を持つことができる特殊なオブジェクトですが、Djangoの`urlencode`はこのオブジェクトの特性を正確に理解し、内部メソッドを活用してデータを漏れなく変換します。

---

## 3. QueryDictを活用した実践的なエンコード事例 {#sec-d12e4e553206}

実際のプロジェクトでDjangoの`urlencode`が真価を発揮する2つのシナリオを見ていきましょう。

### 事例1: 検索フィルターを維持したままページネーションを実装する {#sec-6144c74d2640}

ユーザーが選択した複数の検索条件を維持しつつ、ページ移動のみを行いたい場合、`request.GET`を丸ごとエンコードするのが最もスマートな方法です。


```Python
from django.utils.http import urlencode

# ユーザーが ?category=tech&category=life&q=django を検索した状況
def get_next_page_url(request):
    params = request.GET.copy()  # QueryDict をコピー
    params['page'] = 2           # ページ番号のみ更新
    
    # DjangoのurlencodeはQueryDictのマルチバリュー（category 2つ）を自動的に処理
    return f"/search/?{urlencode(params)}"

# 結果: /search/?category=tech&category=life&q=django&page=2
```

### 事例2: チェックボックスの複数選択データを送信する {#sec-5e6185fe793c}

複数のチェックボックスデータを辞書形式でエンコードし、他のAPIやページに渡す必要がある場合に役立ちます。


```Python
from django.utils.http import urlencode

data = {
    'user_id': 123,
    'selected_tags': ['python', 'backend', 'tips']
}

# 標準urllibとは異なり、doseq=True を使用する必要なし
query_string = urlencode(data)
print(query_string)

# 結果: user_id=123&selected_tags=python&selected_tags=backend&selected_tags=tips
```

---

## 4. まとめ: どちらを選択すべきか？ {#sec-eb673ad941be}
選択の基準は明確です。

1. **Djangoプロジェクト内部**で`request.GET`を扱ったり、Web URLを生成する場合？
    
    - 迷うことなく**`django.utils.http.urlencode`**を使用してください。
        
2. **Djangoとは無関係な独立したPythonスクリプト**を作成する場合？
    
    - **`urllib.parse.urlencode`**を使用しますが、リストデータがある場合は`doseq=True`を忘れないでください。
        

結局のところ、Djangoのバージョンは標準の機能をすべて含みつつ、開発者のミスを減らしてくれる「親切なラッパー（Wrapper）」と言えます。この小さな違いがデバッグ時間を短縮してくれるという事実を、忘れないでください！


**連関記事**

- [DjangoのHTTP万能ツール - 'django.utils.http'](/ja/whitedec/2025/11/12/django-utils-http/)