---
title: "PythonでRedisを使う方法：redis-py 8系の接続プール・pipeline・asyncioと既定値の変更点【2026年11月】"
url: "https://www.issoh.co.jp/tech/details/19931/"
published: 2026-11-17
updated: 2026-11-17
categories: ["データベース"]
publisher: "株式会社一創"
---

# PythonでRedisを使う方法：redis-py 8系の接続プール・pipeline・asyncioと既定値の変更点【2026年11月】

PythonからRedisを使うには、公式クライアントのredis-pyを入れ、プロセスで1つのクライアントを共有し、まとめて送れるコマンドはpipelineで1往復にします。注意したいのは2026年5月のredis-py 8.0で、タイムアウト・再試行・プロトコルの既定値が変わったことです。7系以前を前提にした記事のコードは、そのままでも動きますが、ブロッキングコマンドが途中で切れるなど挙動の差が出ます。この記事ではredis-py 8.1.0のソースとRedis公式ドキュメントをもとに、接続、既定値、接続プール、pipelineとトランザクション、asyncioでの使い方を、コピーして動かせるコードで示します。

## まとめ：redis-py 8系はクライアント共有とタイムアウト明示、往復の削減

インストールは`pip install "redis[hiredis]"`、接続は`redis.Redis(host=..., decode_responses=True)`か`redis.from_url()`で行います。クライアントはリクエストごとに作らず、モジュールで1つ作って使い回します。

8.0からは`socket_timeout`が5秒、再試行が10回、通信はRESP3が既定です。`BLPOP`のように長く待つコマンドを使うなら、そのクライアントだけタイムアウトを延ばします。

複数のコマンドはpipelineで送れば往復が1回で済みます。非同期のアプリでは`redis.asyncio`を使い、終了時に必ず`aclose()`を呼びます。業務データの正本はRDBに置き、Redisはキャッシュやセッションなど消えても作り直せるデータに使いましょう。

## redis-pyのインストールと接続、decode\_responsesとURL指定の書き方

Redis本体の仕組みとデータ型は[Redisとは：仕組みとデータ型・Redis 8.10系の新機能とライセンス、Dockerで動かす手順](https://www.issoh.co.jp/tech/details/18876/)で扱いました。ここからはPython側のコードに絞ります。

### hiredis導入の前提：Python 3.10以上と検証用のRedis

ここでは、pip install “redis\[hiredis\]”を実行する前の環境と、接続確認用のRedisを準備します。

2026年11月17日時点で[PyPIのredis](https://pypi.org/project/redis/)の最新は8.1.0（2026年7月30日公開）で、Python 3.10以上が必要です。3.9以前の環境では古い版が入るため、まず`python --version`で確かめます。

```
# 仮想環境を作ってから入れる
python -m venv .venv
source .venv/bin/activate        # Windows は .venv\Scripts\activate
pip install "redis[hiredis]>=8.1"

# 検証用の Redis をコンテナで起動する
docker run -d --name redis-dev -p 6379:6379 redis:8
```

`[hiredis]`はC実装の応答パーサを一緒に入れる指定です。[redis-pyのREADME](https://github.com/redis/redis-py)は、多くの場合コードの変更なしに速くなると書いています。永続化ボリュームやパスワードを付けた起動は[RedisをDockerで動かす手順：compose.yamlでの永続化・redis.conf・パスワード設定](https://www.issoh.co.jp/tech/details/19855/)を参照してください。

### decode\_responses=True指定でstrを受け取る接続確認

この接続コードでは、bytesではなくstrで応答を受け取る指定と、その確認方法を示します。

redis-pyは既定で応答を`bytes`で返します。[公式の接続ガイド](https://redis.io/docs/latest/develop/clients/redis-py/connect/)のとおり、文字列で受け取るなら`decode_responses=True`を付けます。

```
import redis

r = redis.Redis(host="localhost", port=6379, db=0, decode_responses=True)

print(r.ping())                      # True
r.set("greeting", "hello", ex=60)    # 60秒で消える
print(r.get("greeting"))             # 'hello'（指定しないと b'hello'）

r.hset("user:1001", mapping={"name": "Sato", "plan": "pro"})
print(r.hgetall("user:1001"))        # {'name': 'Sato', 'plan': 'pro'}
```

画像やpickleしたデータのようにバイナリを入れるキーがあるなら、そのキー用には`decode_responses`を付けないクライアントを別に作ります。1つのクライアントで両方を扱うと、UTF-8として読めない値で`UnicodeDecodeError`になります。

### from\_urlとrediss://でパスワードとTLSを接続文字列にまとめる書き方

環境変数1つで接続先を切り替えたいなら、URLで渡します。[接続URLの公式解説](https://redis.io/docs/latest/develop/clients/connection-urls/)によると、`redis://`は平文、`rediss://`はTLSで、末尾の数字がDB番号です。

```
import os
import redis

# 例: REDIS_URL=rediss://default:p%40ss%3Aw%2Brd@cache.example.internal:6379/0
r = redis.from_url(os.environ["REDIS_URL"], decode_responses=True)
```

落とし穴が2つあります。パスワードに`@`や`:`を含むなら、パーセントエンコードが必要です。もう1つは、クエリ文字列の値がキーワード引数として渡される点です。`?decode_responses=False`と書くと文字列の`"False"`が渡り、Pythonでは真と扱われます。真偽値の指定は、URLではなく引数で渡しましょう。

## redis-py 8.0で変わった既定値：タイムアウト5秒・再試行10回・RESP3

2026年5月28日公開の[redis-py 8.0.0のリリースノート](https://github.com/redis/redis-py/releases/tag/v8.0.0)は、接続と再試行の既定値の変更を破壊的変更として挙げています。

### 8.0で変わった接続の既定値を変更前と並べた比較表とソースの定義

| 項目                       | 8.0以降の既定値        | 影響が出る場面            |
| ------------------------ | ---------------- | ------------------ |
| `socket_timeout`         | 5秒               | 5秒を超えて応答を待つコマンド    |
| `socket_connect_timeout` | 5秒               | 遠い拠点や起動直後のサーバーへの接続 |
| `retry`                  | 10回・指数バックオフ＋ジッター | 障害時に失敗が返るまでの時間     |
| `max_connections`        | 100              | 同時に多数のスレッドから使う場合   |
| 通信プロトコル                  | RESP3            | RESP3に対応しない互換製品    |

値は[redis-py 8.1.0の\_defaults.py](https://github.com/redis/redis-py/blob/v8.1.0/redis/%5Fdefaults.py)で、`DEFAULT_SOCKET_TIMEOUT = 5`、`DEFAULT_RETRY_COUNT = 10`、待ち時間の初期値0.01秒・上限1秒と定義されています。RESP3になっても、応答のPythonの型は従来のRESP2と同じ形に保たれます。新規のプロジェクトなら、READMEが勧める`legacy_responses=False`で型をそろえておくと、後でプロトコルを切り替えても戻り値が変わりません。

### BLPOPなどのブロッキングコマンドがsocket\_timeoutの5秒で切れる例

リリースノートが注意しているのが、`BLPOP`や`BRPOP`です。コマンド側で30秒待つ指定をしても、クライアントのソケットが5秒で諦め、`TimeoutError`になる可能性があります。キューのワーカーを8系へ上げたら例外が出始めた、という事故はこの組み合わせで起きます。

```
import redis

# 通常の読み書き用（既定の5秒のまま）
r = redis.Redis(host="localhost", decode_responses=True)

# 長く待つワーカー用。待ち時間より長いソケットタイムアウトを持たせる
worker = redis.Redis(host="localhost", decode_responses=True, socket_timeout=40)

while True:
    item = worker.blpop("jobs", timeout=30)   # 30秒待って無ければ None
    if item is None:
        continue
    _, payload = item
    handle(payload)
```

ブロッキング用のクライアントを分ける理由は、全体のタイムアウトを延ばすと、通常のコマンドでサーバーが詰まったときの検知まで遅れるためです。

### 公式ガイドの「再試行3回・10秒」とソースの既定値が食い違う点

2026年11月17日時点の[公式のProduction usage](https://redis.io/docs/latest/develop/clients/redis-py/produsage/)には、6.0以降は失敗したコマンドを3回試す、タイムアウトは接続・コマンドとも10秒、という記述が残っています。8.1.0のソースとは一致しません。

実際に動くのはソースの値です。迷ったら、自分の環境で`r.connection_pool.connection_kwargs`を表示して確かめます。どちらにしても、既定値に頼らず、業務の要件から`socket_timeout`と`retry`を明示しておくのが安全です。再試行の対象は既定で`ConnectionError`と`TimeoutError`で、`retry_on_error`で追加できます。

## 接続プール設計：共有と上限100、BlockingConnectionPool

redis-pyの`Redis`は、内部に接続プールを持っています。コマンドごとにプールから接続を借りて返すので、クライアントを使い回せばTCP接続も使い回されます。

### リクエストごとにRedis()を作らずモジュールで1つを共有する構成

よくある失敗は、Webのリクエストを処理する関数の中で毎回`redis.Redis()`を作る書き方です。そのたびにプールが作られ、接続の確立とAUTHが毎回走ります。

```
# app/cache.py ― アプリ全体で import して使う
import os
import redis

client = redis.Redis.from_url(
    os.environ.get("REDIS_URL", "redis://localhost:6379/0"),
    decode_responses=True,
    socket_timeout=2,          # 要件に合わせて明示する
    health_check_interval=30,  # 30秒以上使っていない接続は PING で確かめてから使う
)
```

`health_check_interval`は、アイドルが長い接続をロードバランサーやファイアウォールに切られている環境で効きます。夜間にしか動かないバッチや、アクセスの少ない管理画面で、朝一番のコマンドだけが失敗する症状への対策になります。

### 上限100の接続エラーとBlockingConnectionPoolの20秒待機

[redis-py 8.1.0のconnection.py](https://github.com/redis/redis-py/blob/v8.1.0/redis/connection.py)では、通常の`ConnectionPool`は上限を指定しないと100本で、使い切ると待たずに`MaxConnectionsError("Too many connections")`を投げます。同じファイルの`BlockingConnectionPool`は既定が50本で、空きが出るまで最大20秒待ちます。

```
import redis

pool = redis.BlockingConnectionPool(
    host="localhost", port=6379, decode_responses=True,
    max_connections=20,   # Redis 側の maxclients と台数から逆算する
    timeout=2,            # 2秒待っても空かなければ ConnectionError
)
r = redis.Redis(connection_pool=pool)
```

スレッド数の多いアプリで、一時的な集中をエラーでなく待ちで吸収したいならBlockingConnectionPoolです。上限は、アプリのプロセス数×1プロセスの上限が、Redis側の`maxclients`を超えないように決めます。待ちの20秒は長すぎることが多いので、APIの応答時間の目標より短く設定し直してください。

### gunicornなどforkするサーバーで子プロセスのプールが作り直される仕組み

gunicornの`--preload`のように、親プロセスでモジュールを読み込んでからforkする構成では、親で作ったクライアントが子に引き継がれます。connection.pyの`_checkpid()`は、プールを操作するたびにプロセスIDを比べ、変わっていればforkされたとみなしてプールを初期化する仕組みです。子は親のソケットを使わず、自分の接続を張り直すため、上のモジュール共有の書き方はfork環境でもそのまま使えます。

注意すべきなのは本数の見積もりです。プールはプロセスごとに作られるため、ワーカー8プロセスなら上限も8倍になります。

## pipelineで往復を減らす実装とtransaction=Falseに切り替える判断

[公式のPipelines and transactions](https://redis.io/docs/latest/develop/clients/redis-py/transpipe/)のとおり、pipelineはコマンドを手元にためておき、`execute()`でまとめて送ります。結果は送った順のリストで返ります。

### 1,000件の書き込みを1往復ずつ送る場合とpipelineでまとめるコード

Redisの1コマンドの処理は速くても、Pythonから1件ずつ送ると、待ち時間の大半はネットワークの往復になります。往復1ミリ秒の環境で1,000件を送れば、計算上は往復だけで約1秒です。

```
import redis

r = redis.Redis(decode_responses=True)
rows = [{"sku": f"SKU-{i:04d}", "stock": i % 50} for i in range(1000)]

# 1件ずつ送る：1,000往復
for row in rows:
    r.hset(f"stock:{row['sku']}", mapping={"qty": row["stock"]})

# pipeline：500件ごとに1往復
with r.pipeline(transaction=False) as pipe:
    for i, row in enumerate(rows, 1):
        pipe.hset(f"stock:{row['sku']}", mapping={"qty": row["stock"]})
        if i % 500 == 0:
            pipe.execute()
    pipe.execute()          # 端数を送る
```

途中で区切って`execute()`しているのは、数十万件を1回に積むと、応答をすべて受け取るまでクライアントとサーバーの両方でメモリを使うためです。数百〜数千件ごとに区切るのが無難な目安になります。

### 既定のMULTI/EXECが不要な一括処理でtransaction=Falseにする場面

redis-pyの`pipeline()`は、既定でトランザクションとして実行します。送ったコマンドは`MULTI`と`EXEC`で囲まれ、他のクライアントのコマンドが途中に挟まりません。

上の在庫の取り込みのように、各コマンドが独立していて途中に他の処理が挟まっても困らないなら、`transaction=False`で十分です。Redis Clusterでは、1つのトランザクションのキーが同じハッシュスロットにないとエラーになるため、複数のキーにまたがる一括処理はなおさら`transaction=False`で送ります。Clusterでの接続は[Redis Clusterの構築手順：16384ハッシュスロットの仕組みとMOVED・ASK、redis-pyでの接続と再シャーディング](https://www.issoh.co.jp/tech/details/19853/)で扱いました。

### WATCHとtransaction()で在庫を楽観ロック付きで減らす更新コード

読んだ値をもとに書き戻す処理は、読んでから書くまでの間に他のクライアントが値を変えると壊れます。`WATCH`で監視し、変わっていたら`WatchError`でやり直すのがRedisの楽観ロックです。redis-pyには、この再試行を肩代わりする`transaction()`があります。

```
import redis

r = redis.Redis(decode_responses=True)
r.set("stock:SKU-0001", 3)

def reserve_one(pipe):
    qty = int(pipe.get("stock:SKU-0001") or 0)   # WATCH 後はすぐに実行される
    if qty <= 0:
        raise ValueError("在庫切れ")
    pipe.multi()                                  # ここから下がまとめて実行される
    pipe.set("stock:SKU-0001", qty - 1)

r.transaction(reserve_one, "stock:SKU-0001")      # 競合したら自動でやり直す
print(r.get("stock:SKU-0001"))                    # '2'
```

`multi()`の呼び出しは自動では入らないので、読み取りの後に自分で書きます。単純な増減だけなら`DECR`の1コマンドで済むので、`WATCH`は判定を挟む更新に限って使います。複数のプロセスで処理そのものを1つに絞りたい場合は、[RedisのSETNXロック実装：SET NX PXとLuaでの解放、Redlockとフェンシングトークンの判断](https://www.issoh.co.jp/tech/details/19929/)で扱った分散ロックの領分です。

## redis.asyncioで非同期に使う実装とFastAPIでのaclose漏れ対策

asyncioのアプリでは、同じパッケージの`redis.asyncio`を使います。コマンドはすべてコルーチンなので`await`を付けます。

### redis.asyncioの基本とawaitを付けたpipelineの書き方

[redis-pyのasyncioの例](https://redis.readthedocs.io/en/stable/examples/asyncio%5Fexamples.html)は、非同期版には後始末を自動で行う仕組みがないため、明示的に`aclose()`で閉じるよう書いています。

```
import asyncio
import redis.asyncio as redis

async def main():
    r = redis.from_url("redis://localhost:6379/0", decode_responses=True)  # from_url 自体は await しない
    try:
        await r.set("counter", 0)
        async with r.pipeline(transaction=True) as pipe:
            ok, value = await pipe.incr("counter").get("counter").execute()
        print(ok, value)              # 1 '1'
    finally:
        await r.aclose()

asyncio.run(main())
```

pipelineへのコマンドの追加には`await`を付けず、最後の`execute()`だけを待ちます。同期版のコードを書き換えるときに、全部の行へ`await`を付けてしまう間違いが多い箇所です。

### FastAPIのlifespanでクライアントを1つ作りaclose()で閉じる構成

Webフレームワークでは、起動時に1つ作り、終了時に閉じます。FastAPIなら、起動と終了の処理の記述先は`lifespan`です。FastAPI自体の起動手順は[FastAPIとは？最短の起動手順とasync/defの使い分け、0.162の変更点](https://www.issoh.co.jp/tech/details/3859/)にまとめています。

```
from contextlib import asynccontextmanager

from fastapi import FastAPI, Request
import redis.asyncio as redis

@asynccontextmanager
async def lifespan(app: FastAPI):
    app.state.redis = redis.from_url("redis://localhost:6379/0", decode_responses=True)
    yield
    await app.state.redis.aclose()     # 終了時にプールごと閉じる

app = FastAPI(lifespan=lifespan)

@app.get("/visits")
async def visits(request: Request):
    count = await request.app.state.redis.incr("visits")
    return {"visits": count}
```

エンドポイントの中で`redis.from_url()`を呼んで閉じ忘れると、リクエストのたびに接続が残り、Redis側の接続数が増え続けます。

### from\_poolとconnection\_pool引数でプールを閉じる責任が変わる違い

プールを自分で作る場合は、渡し方で後始末が変わります。`Redis.from_pool(pool)`で渡すとクライアントがプールを所有し、クライアントの`aclose()`でプールも閉じます。`Redis(connection_pool=pool)`で複数のクライアントに共有した場合は、各クライアントを閉じてもプールは残るので、最後に`await pool.aclose()`が必要です。かつての`auto_close_connection_pool`引数は8.1.0のソースで非推奨の警告が出るため、新しいコードでは使いません。

## PythonとRedisの組み合わせを採用する条件、RDBに任せる場面

判断の軸は、Redisのデータが消えたときに作り直せるかどうかです。

### キャッシュ・セッション・ジョブの受け渡しなど、redis-pyで書く用途

次の用途は、Redisの速さがそのまま効き、データが消えても元のDBから作り直せます。実務で最初に入れるのはキャッシュです。

- DBやAPIの結果のキャッシュ（実装は[Redisキャッシュの実装方法：Cache-AsideとTTL設計・スタンピード対策をredis-pyのコードで解説](https://www.issoh.co.jp/tech/details/19857/)）
- ログインセッションの保存（Djangoなら[Djangoのセッション設定：保存先5種の選び分けとRedis構成の判断](https://www.issoh.co.jp/tech/details/17102/)）
- プロセス間の通知（[Redis Pub/Subの使い方：PUBLISHとSUBSCRIBEの実装例、メッセージ消失の対策とStreamsとの使い分け](https://www.issoh.co.jp/tech/details/19865/)）
- レート制限のカウンターやランキングのように、`INCR`やソート済みセットで1コマンドに収まる集計

この範囲なら、redis-pyの同期クライアントを1つ共有し、タイムアウトを明示するだけで十分です。ORMのような抽象化ライブラリを挟むほどの規模ではありません。

### 業務データの正本をRedisに置かず、RDBとの役割分担を決める判断

注文、請求、在庫の確定値のように、消えたら復元できないデータの正本はRedisに置きません。Redisの永続化は設定次第で直近の書き込みを失い得ますし、レプリカへの複製も非同期です。冗長化の構成は[Redisの冗長化：レプリケーションとSentinelで自動フェイルオーバーを組む設定例とElastiCache Multi-AZとの比較](https://www.issoh.co.jp/tech/details/19851/)で扱いましたが、公式の接続ガイドが書くとおり、redis-pyはSentinelのフェイルオーバー通知を聞かないため、切り替わりの間に旧マスターが受けた書き込みは失われます。

正本はRDBに置き、Redisには読み取りの高速化や一時データだけを持たせる分担が、障害時の説明もしやすい形です。既存システムのどのデータをRedisへ逃がし、どれをRDBに残すかの線引きから迷う場合は、[データベース設計・移行支援](https://www.issoh.co.jp/service/system/database/)でデータの置き場所の設計から相談を受けています。

## よくある質問

PythonからRedisを使うときに、よく検索される質問に答えます。

### getで取得した値がb’…’のbytesになるのはなぜですか？

redis-pyが既定で応答をデコードせず、`bytes`のまま返すためです。接続時に`decode_responses=True`を付ければ`str`で返ります。既に`bytes`で受け取ったコードを直すなら、取得のたびに`.decode("utf-8")`を書くより、クライアントの生成箇所で指定する方が漏れがありません。ただし、画像やpickleのようなバイナリも同じRedisに入れている場合は、そのキーを読むクライアントだけ指定を外して、`UnicodeDecodeError`を避けてください。

### redis-pyの7系から8系へ上げるときは何を確かめればよいですか？

まず、Python 3.10以上かどうかです。次に、5秒を超えて待つコマンドの有無を探します。`BLPOP`・`BRPOP`・`XREAD`のBLOCK指定などがあれば、そのクライアントの`socket_timeout`を待ち時間より長くします。3つ目は、RESP3に対応していない互換製品やプロキシへ接続していないかの確認です。問題が出たら`protocol=2`で従来の通信に戻せます。型ヒントの変更も破壊的変更に含まれるので、mypyなどを使っているなら型チェックも流し直します。

### Redis ClusterやSentinelにはどのクラスで接続しますか？

Redis Clusterは`redis.cluster.RedisCluster`、Sentinel構成は`redis.sentinel.Sentinel`の`master_for()`で接続します。単一のRedis向けの`redis.Redis`でClusterへつなぐと、別のシャードにあるキーで`MOVED`エラーになります。ElastiCacheなどのマネージドでも、クラスターモードを有効にしているかどうかで使うクラスが変わるため、接続先の構成を先に確かめてください。Sentinelは、Sentinel自体とデータノードで認証情報が別になる点に注意します。

### Pub/Subや分散ロックもredis-pyで書けますか？

書けます。Pub/Subは`r.pubsub()`で購読用のオブジェクトを作り、`subscribe()`と`get_message()`で受け取ります。分散ロックは`r.lock()`で得られる`Lock`クラスが、`SET NX PX`での取得とトークンを照合する解放を実装済みです。ただし`Lock`は`timeout`の既定が無期限なので、必ず期限を渡します。どちらも用途ごとの注意点が多いため、本記事では接続とpipelineに範囲を絞り、詳細は関連記事で扱っています。

### hiredisは入れたほうがよいですか？

本番では入れておくのが無難です。`pip install "redis[hiredis]"`とすると、応答の解析がC実装に切り替わり、READMEによれば多くの場合コードの変更は要りません。8.1.0が要求するのはhiredis 3.2.0以上です。効果が大きいのは、`LRANGE`や`HGETALL`で大きな応答を受け取る処理です。一方で、ビルド済みのパッケージが無い環境ではインストール時にコンパイルが走るため、軽量なコンテナイメージでは入れるかどうかをビルド時間と比べて決めます。

## 関連記事

- [Redisとは：仕組みとデータ型・Redis 8.10系の新機能とライセンス、Dockerで動かす手順](https://www.issoh.co.jp/tech/details/18876/)：Redis本体の仕組みと版
- [Redisキャッシュの実装方法：Cache-AsideとTTL設計・スタンピード対策をredis-pyのコードで解説](https://www.issoh.co.jp/tech/details/19857/)：redis-pyで書くキャッシュの実装
- [RedisのSETNXロック実装：SET NX PXとLuaでの解放、Redlockとフェンシングトークンの判断](https://www.issoh.co.jp/tech/details/19929/)：redis-pyのLockクラスと分散ロック
- [Redis Pub/Subの使い方：PUBLISHとSUBSCRIBEの実装例、メッセージ消失の対策とStreamsとの使い分け](https://www.issoh.co.jp/tech/details/19865/)：Pythonからの購読と通知
- [Redis Clusterの構築手順：16384ハッシュスロットの仕組みとMOVED・ASK、redis-pyでの接続と再シャーディング](https://www.issoh.co.jp/tech/details/19853/)：RedisClusterクラスでの接続

---

出典: [PythonでRedisを使う方法：redis-py 8系の接続プール・pipeline・asyncioと既定値の変更点【2026年11月】](<https://www.issoh.co.jp/tech/details/19931/>)（株式会社一創）
