●Change8

Migrating to Redis Python v8.0.0

Version v8.0.0 introduces 4 breaking changes. This guide details how to update your code.

Released: 5/28/2026

4
Breaking Changes
5
Migration Steps
25
Affected Symbols

⚠️ Check Your Code

If you use any of these symbols, you need to read this guide:

redis.asyncio.cluster.ClusterPubSubRedisCluster.pubsub()KeyspaceNotificationsClusterKeyspaceNotificationsAsyncKeyspaceNotificationsAsyncClusterKeyspaceNotificationssubscribe_keyspace()subscribe_keyevent()subscribe_subkeyspace()subscribe_subkeyevent()subscribe_subkeyspaceitem()subscribe_subkeyevent()core.pyVectorSet commandsSearch module commandsJSON module commandsTimeSeries module commandsBloom filter module commandsSyncClientProtocolAsyncClientProtocolLock.extendLock.reacquireClusterPubSub.disconnect()async's can_read_destructivehiredis connections readiness checks

Breaking Changes

●Issue #1

Type hints were systematically updated using @overload across core, VectorSet, and module commands. Code relying on the old union return types (e.g., Union[Awaitable[Any], Any]) in type annotations for sync/async methods may need updates, although runtime behavior is unchanged.

●Issue #2

The default protocol changed to RESP3. While default response shapes remain RESP2-compatible, explicitly setting `protocol=2` is required to force RESP2 on the wire.

●Issue #3

ClusterPubSub now handles cluster slot migration (shard subscription reconciliation), which may affect custom subscription management logic.

●Issue #4

Async reads in hiredis connections readiness checks now avoid zero-timeouts, replacing async's can_read_destructive with non-destructive can_read. This might affect low-level connection handling logic.

Migration Steps

  1. 1
    If using static analysis tools (mypy, Pyright), review return type annotations for core, VectorSet, and module commands, as they now return distinct sync/async types instead of a union.
  2. 2
    To maintain RESP2 wire protocol, explicitly set `protocol=2` if necessary, as RESP3 is now the default.
  3. 3
    To migrate to protocol-independent unified response shapes (where RESP2/RESP3 return the same Python structure), set `legacy_responses=False`.
  4. 4
    If using RESP3 natively without legacy responses, set `protocol=3`.
  5. 5
    Review code that relies on connection timeouts, as `socket_timeout` now defaults to 5 seconds and may cause `TimeoutError` for long-blocking commands.

Release Summary

This release introduces major features including full asyncio Cluster PubSub support and Redis Keyspace Notifications across sync/async modes, while defaulting to the RESP3 protocol. It also includes significant improvements to type hinting for static analysis and updates to default connection settings.

Need More Details?

View the full release notes and all changes for Redis Python v8.0.0.

View Full Changelog