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で動かす手順で扱いました。ここからはPython側のコードに絞ります。
hiredis導入の前提:Python 3.10以上と検証用のRedis
ここでは、pip install “redis[hiredis]”を実行する前の環境と、接続確認用のRedisを準備します。
2026年11月17日時点でPyPIの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は、多くの場合コードの変更なしに速くなると書いています。永続化ボリュームやパスワードを付けた起動はRedisをDockerで動かす手順:compose.yamlでの永続化・redis.conf・パスワード設定を参照してください。
decode_responses=True指定でstrを受け取る接続確認
この接続コードでは、bytesではなくstrで応答を受け取る指定と、その確認方法を示します。
redis-pyは既定で応答をbytesで返します。公式の接続ガイドのとおり、文字列で受け取るなら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の公式解説によると、redis://は平文、rediss://はTLSで、末尾の数字がDB番号です。
import os
import redis
# 例: REDIS_URL=rediss://default:p%40ss%3Aw%[email protected]: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のリリースノートは、接続と再試行の既定値の変更を破壊的変更として挙げています。
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で、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には、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では、通常の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のとおり、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での接続と再シャーディングで扱いました。
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とフェンシングトークンの判断で扱った分散ロックの領分です。
redis.asyncioで非同期に使う実装とFastAPIでのaclose漏れ対策
asyncioのアプリでは、同じパッケージのredis.asyncioを使います。コマンドはすべてコルーチンなのでawaitを付けます。
redis.asyncioの基本とawaitを付けたpipelineの書き方
redis-pyのasyncioの例は、非同期版には後始末を自動で行う仕組みがないため、明示的に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の変更点にまとめています。
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のコードで解説)
- ログインセッションの保存(DjangoならDjangoのセッション設定:保存先5種の選び分けとRedis構成の判断)
- プロセス間の通知(Redis Pub/Subの使い方:PUBLISHとSUBSCRIBEの実装例、メッセージ消失の対策とStreamsとの使い分け)
- レート制限のカウンターやランキングのように、
INCRやソート済みセットで1コマンドに収まる集計
この範囲なら、redis-pyの同期クライアントを1つ共有し、タイムアウトを明示するだけで十分です。ORMのような抽象化ライブラリを挟むほどの規模ではありません。
業務データの正本をRedisに置かず、RDBとの役割分担を決める判断
注文、請求、在庫の確定値のように、消えたら復元できないデータの正本はRedisに置きません。Redisの永続化は設定次第で直近の書き込みを失い得ますし、レプリカへの複製も非同期です。冗長化の構成はRedisの冗長化:レプリケーションとSentinelで自動フェイルオーバーを組む設定例とElastiCache Multi-AZとの比較で扱いましたが、公式の接続ガイドが書くとおり、redis-pyはSentinelのフェイルオーバー通知を聞かないため、切り替わりの間に旧マスターが受けた書き込みは失われます。
正本はRDBに置き、Redisには読み取りの高速化や一時データだけを持たせる分担が、障害時の説明もしやすい形です。既存システムのどのデータをRedisへ逃がし、どれをRDBに残すかの線引きから迷う場合は、データベース設計・移行支援でデータの置き場所の設計から相談を受けています。
よくある質問
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で動かす手順:Redis本体の仕組みと版
- Redisキャッシュの実装方法:Cache-AsideとTTL設計・スタンピード対策をredis-pyのコードで解説:redis-pyで書くキャッシュの実装
- RedisのSETNXロック実装:SET NX PXとLuaでの解放、Redlockとフェンシングトークンの判断:redis-pyのLockクラスと分散ロック
- Redis Pub/Subの使い方:PUBLISHとSUBSCRIBEの実装例、メッセージ消失の対策とStreamsとの使い分け:Pythonからの購読と通知
- Redis Clusterの構築手順:16384ハッシュスロットの仕組みとMOVED・ASK、redis-pyでの接続と再シャーディング:RedisClusterクラスでの接続