Changes

🐛 Bug Fixes

• Preserve explicit None for client metadata config (#4081)

🧰 Maintenance

• Updating PyJWT dependency. (#4100)
• Addressing dependency vulnerabilities and flaky test fixes (source diff)

We'd like to thank all the contributors who worked on this release!
@elena-kolevska @vladvildanov @petyaslavova

Changes

🐛 Bug Fixes

• Preserve explicit None for client metadata config (#4081)

🧰 Maintenance

• Updating PyJWT dependency. (#4100)
• Addressing dependency vulnerabilities and flaky test fixes (source diff)

We'd like to thank all the contributors who worked on this release!
@elena-kolevska @vladvildanov @petyaslavova

Changes

🐛 Bug Fixes

• Preserve explicit None for client metadata config (#4081)

🧰 Maintenance

• Updating PyJWT dependency. (#4100)
• Addressing dependency vulnerabilities and flaky test fixes (source diff)

We'd like to thank all the contributors who worked on this release!
@elena-kolevska @vladvildanov @petyaslavova

Changes

🚀 Highlights

Async Cluster PubSub

This release introduces full asyncio Cluster PubSub support, bringing shard-channel capabilities (SSUBSCRIBE, SUNSUBSCRIBE, SPUBLISH) to the async RedisCluster client. The new ClusterPubSub class in redis.asyncio.cluster automatically routes shard-channel subscriptions to the correct cluster node based on key-slot hashing, manages per-node PubSub connections, and supports round-robin message retrieval across nodes. Users can create a cluster pubsub instance via RedisCluster.pubsub() and use ssubscribe(), sunsubscribe(), and get_sharded_message() just as they would with the sync cluster client.

Keyspace and subkey notifications

Redis Keyspace Notifications are now supported for standalone and cluster deployments in both sync and async modes. New classes — KeyspaceNotifications, ClusterKeyspaceNotifications, AsyncKeyspaceNotifications, and AsyncClusterKeyspaceNotifications — provide a high-level API for keyspace/keyevent subscriptions and subkey notification families: subkeyspace, subkeyevent, subkeyspaceitem, and subkeyspaceevent. Convenience methods like subscribe_keyspace(), subscribe_keyevent(), subscribe_subkeyspace(), subscribe_subkeyevent(), subscribe_subkeyspaceitem(), and subscribe_subkeyspaceevent() simplify common patterns, with channel classes for both key and subkey channels.

In cluster mode, subscriptions are managed across primary nodes because each node emits notifications only for keys it owns, with built-in topology-change handling. Sync run_in_thread() and async listen() workflows are supported.

Redis Array commands(https://redis.io/docs/latest/develop/data-types/arrays/)

redis-py now supports Redis Arrays, a preview Redis data type for sparse, index-addressable sequences of strings. New AR* command helpers cover indexed reads/writes, range scans, deletion, cursor-based insertion, ring-buffer writes, metadata, text search, and aggregation, including ARGET, ARSET, ARMGET, ARMSET, ARSCAN, ARGREP, ARRING, and AROP.

Type Hints Improvements (breaking changes)

The @overload pattern has been applied systematically across core commands (core.py), VectorSet commands, and module commands (Search, JSON, TimeSeries, Bloom filters) to provide distinct return types for sync and async clients. Previously, methods returned a combined ResponseT (i.e., Union[Awaitable[Any], Any]), which caused static analysis tools like mypy and Pyright to flag false positives. Now, sync clients see concrete return types (e.g., int, bool, list[str]) while async clients see Awaitable[...] wrappers. This is a breaking change for type-checking only—runtime behavior is unchanged, but code relying on the old union return types in type annotations may need updates. Two new protocol types, SyncClientProtocol and AsyncClientProtocol, are used in overload signatures to enable this distinction.

RESP3 by default with opt-in unified responses

redis-py 8.0.0 now uses RESP3 on the wire by default while preserving legacy RESP2-compatible Python response shapes for existing applications (#4052). Protocol-independent unified response shapes are available by setting legacy_responses=False, so affected commands return the same Python structure with RESP2 or RESP3.

Use protocol=2 to force RESP2 on the wire, protocol=3 to opt into native RESP3 response shapes, or legacy_responses=False to migrate to unified responses. See docs/unified_responses.rst and specs/unified_responses_migration_guide.md for the affected commands and migration details.

Connection and retry defaults

Default connection settings were updated: socket_timeout and socket_connect_timeout now default to 5 seconds, TCP keepalive is enabled by default, socket reads use a 32 KB buffer, connection pools default to max_connections=100, and retry defaults now use 10 attempts with exponential jitter backoff.

Note: socket_timeout can affect blocking commands such as BLPOP/BRPOP; if a command blocks longer than the client socket timeout, it may raise TimeoutError before the command timeout elapses (#2807).

🧪 Experimental Features

• Added support for new array commands (#4055)

🚀 New Features

• Support Cluster PubSub in asyncio (#3736)
• Add Redis Keyspace Notifications Support for Redis Cluster (#3962)
• Add random load balancing strategy which allows for use of the primary (#4027)
• Add FPHA (floating-point homogeneous array) arg support to JSON.SET (#4011)
• Added custom Claude command + XNACK command support (#4030)
• Adding Time Series Multiple Aggregators support (#4035)
• Adding support for new COUNT aggregator for some sorted set commands - ZINTER, ZINTERSTORE, ZUNION, ZUNIONSTORE (#4034)
• Adding support for new INCREX command (#4067 #4077)
• Add support for PubSub subscriptions with binary channel names and handlers (#4068)

🔥 Breaking changes

• Type hints improvements - fixing static code analysis issues related to combined sync and async return types(vectorsets + commands in core.py) (#3991)
• Type hints improvements - fixing static code analysis issues related to combined sync and async return types - modules (#4005)
• Add Redis Keyspace Notifications Support for Redis Cluster (#3962)
• Added support for subkey notifications (#4040)
• Changing the default protocol used to RESP3, keeping the responses for the default config compatible with the current RESP2 shape. Adding the possibility to opt-in for unified responses for both protocols. (#4025 #4031 #4052 #4046)
• Type Lock.extend and Lock.reacquire as Literal[True] (#4045)
• Handle cluster slot migration in ClusterPubSub (shard subscription reconciliation) (#4044)
• Avoid zero-timeout async reads in hiredis connections readiness checks and replace async's can_read_destructive with non-destructive can_read. (#4063)
• Updates in default connection and retry settings (#4082)

🐛 Bug Fixes

• fix: guard disconnect() against RuntimeError on Python 3.13+ (#3856) (#4013)
• Fix CacheProxyConnection hang when invalidation arrives on another connection (#3600) (#4014)
• fix: handle scientific notation in score_cast_func for RESP2 (#4016)
• Fix TypeError in CacheProxyConnection when cached response is non-bytes (#4017)
• Fix async cluster connection cleanup on topology refresh (#4057)
• Normalize scalar prefixes in IndexDefinition (#3983)
• Avoid zero-timeout async reads in hiredis connections readiness checks and replace async's can_read_destructive with non-destructive can_read. (#4063)
• Preserve explicit None for client metadata config (#4081)

⚠️ Deprecations

• Align deprecation of lib_name/lib_version in async cluster (#3995)
• Add deprecation notice to setex() method documentation (#4051)
• Avoid zero-timeout async reads in hiredis connections readiness checks and replace async's can_read_destructive with non-destructive can_read. (#4063)

🧰 Maintenance

• Adding unstable 8.8 build to pipeline test matrix. Updating the lib version in master. (#4004)
• Fix type hints for register_script to support RedisCluster (#3876)
• Updating dependencies to fix reported vulnerabilities (#4012)
• Bump release-drafter/release-drafter from 6 to 7 (#4019)
• Bump rojopolis/spellcheck-github-actions from 0.58.0 to 0.60.0 (#4018)
• Reorganize unit tests grouping - extracting the tests that define their hardcoded client configuration separately (#4029)
• Update home_json.py - this will make the docs examples interactive (#4020)
• Fix Sync ClusterPubSub.disconnect() — Potential AttributeError (#4036)
• Refactor ClusterPubSub to reuse NodesManager-managed connections. (#4037)
• Fix CROSSSLOT on sharded pubsub resubscription by grouping channels per slot (#4038)
• fix(cluster): enable health check in ClusterNode command execution (#4043)
• Add Python version '3.14t' to CI matrix (#4058)
• docs: fix typos in messages, docstrings, and comments (#4062)
• Updating hash commands type hints and jsonget return type hints (#4054)
• Fix flaky tests (#4071)
• Add CLAUDE.md and /sync-claude-md skill for managing (#4066)
• Randomize cluster startup node order during topology refresh (#4060)

We'd like to thank all the contributors who worked on this release!
@hydroblaze @Br1an67 @mokashang @swoutch @armorbreak001 @Brumbelow @paoloredis @Pack-Yak1 @abersheeran @alisaifee @majiayu000 @uglide @dmaier-redislabs @vladvildanov @petyaslavova

Changes

Unified command response types across RESP2 and RESP3 protocols

In this release, the command response types across RESP2 and RESP3 protocols are unified, ensuring that the same command returns the same Python type and structure regardless of which protocol version is in use — eliminating the need for protocol-specific branching in application code (#4025). Approximately 84 commands are affected across core Redis, Search, JSON, TimeSeries, and Probabilistic modules. Additionally, the default protocol has been changed from RESP2 to RESP3 for all Redis clients and connections, enabling richer native types (maps, sets, doubles, booleans) and improved performance out of the box (#4031).
These changes are breaking relative to redis-py 7.x and earlier, so users upgrading should carefully review the migration guide. For a complete list of affected commands and updated response formats, see docs/resp_unification.rst and the detailed migration guide at specs/resp2_resp3_migration_guide.md.
Users who need to retain the previous default protocol configuration can explicitly set protocol=2 when creating their client or connection.

🚀 New Features

• Add random load balancing strategy which allows for use of the primary (#4027)

🔥 Breaking changes

• RESP2 and RESP3 response unification (#4025)
• Changing the default RESP protocol configurations for Redis clients and connections to 3 (#4031)

🧰 Maintenance

• Reorganize unit tests grouping - extracting the tests that define their hardcoded client configuration separately (#4029)

We'd like to thank all the contributors who worked on this release!
@Pack-Yak1 @petyaslavova

Changes

Async Cluster PubSub & Keyspace Notifications

This release introduces full asyncio Cluster PubSub support, bringing shard-channel capabilities (SSUBSCRIBE, SUNSUBSCRIBE, SPUBLISH) to the async RedisCluster client. The new ClusterPubSub class in redis.asyncio.cluster automatically routes shard-channel subscriptions to the correct cluster node based on key-slot hashing, manages per-node PubSub connections, and supports round-robin message retrieval across nodes. Users can create a cluster pubsub instance via RedisCluster.pubsub() and use ssubscribe(), sunsubscribe(), and get_sharded_message() just as they would with the sync cluster client.

Alongside this, Redis Keyspace Notifications are now supported for both standalone and cluster deployments, in both sync and async modes. New classes—KeyspaceNotifications, ClusterKeyspaceNotifications, AsyncKeyspaceNotifications, and AsyncClusterKeyspaceNotifications—provide a high-level API for subscribing to keyspace and keyevent channels. In cluster mode, notifications are automatically subscribed across all primary nodes (since each node only emits notifications for keys it owns), with built-in topology-change handling. Convenience methods like subscribe_keyspace(), subscribe_keyevent(), and channel classes (KeyspaceChannel, KeyeventChannel) simplify common subscription patterns. Both sync run_in_thread() and async listen() workflows are supported.

Type Hints Improvements (breaking changes)

The @overload pattern has been applied systematically across core commands (core.py), VectorSet commands, and module commands (Search, JSON, TimeSeries, Bloom filters) to provide distinct return types for sync and async clients. Previously, methods returned a combined ResponseT (i.e., Union[Awaitable[Any], Any]), which caused static analysis tools like mypy and Pyright to flag false positives. Now, sync clients see concrete return types (e.g., int, bool, list[str]) while async clients see Awaitable[...] wrappers. This is a breaking change for type-checking only—runtime behavior is unchanged, but code relying on the old union return types in type annotations may need updates. Two new protocol types, SyncClientProtocol and AsyncClientProtocol, are used in overload signatures to enable this distinction.

🚀 New Features

• Support Cluster PubSub in asyncio (#3736)
• Add Redis Keyspace Notifications Support for Redis Cluster (#3962)

🔥 Breaking changes

• Type hints improvements - fixing static code analyses issues related to combined sync and async return types(vectorsets + commands in core.py) (#3991)
• Type hints improvements - fixing static code analyses issues related to combined sync and async return types - modules (#4005)
• Add Redis Keyspace Notifications Support for Redis Cluster (#3962)

🐛 Bug Fixes

• fix: guard disconnect() against RuntimeError on Python 3.13+ (#3856) (#4013)
• Fix CacheProxyConnection hang when invalidation arrives on another connection (#3600) (#4014)
• fix: handle scientific notation in score_cast_func for RESP2 (#4016)
• Fix TypeError in CacheProxyConnection when cached response is non-bytes (#4017)

⚠️ Deprecations

• Align deprecation of lib_name/lib_version in async cluster (#3995)

🧰 Maintenance

• Adding unstable 8.8 build to pipeline test matrix. Updating the lib version in master. (#4004)
• Fix type hints for register_script to support RedisCluster (#3876)
• Updating dependencies to fix reported vulnerabilities (#4012)
• Bump release-drafter/release-drafter from 6 to 7 (#4019)
• Bump rojopolis/spellcheck-github-actions from 0.58.0 to 0.60.0 (#4018)

We'd like to thank all the contributors who worked on this release!
@abersheeran @alisaifee @majiayu000 @dmaier-redislabs @vladvildanov @petyaslavova

Changes

🐛 Bug Fixes

• Fix AttributeError in cluster metrics recording when connection is None or ClusterNode object instance is used to extract the connection info (#3999)
• Fixing security concern in repr methods for ConnectionPools - passwords might leak in plain text logs (#3998)
• Refactored connection count and SCH metric collection (#4001)

🧪 Experimental Features

• Refactored health check logic for MultiDBClient (#3994)

🧰 Maintenance

• Expose basic Otel classes and functions to be importable through redis.observability to match the examples in the readthedocs (#3996)

We'd like to thank all the contributors who worked on this release!
@vladvildanov @petyaslavova

Changes

OpenTelemetry Native Metrics Support for asynchronous clients
Added comprehensive OpenTelemetry metrics support for asynchronous clients following the OpenTelemetry Database Client Semantic Conventions.
Metric groups include:

• Command metrics: Operation duration with retry tracking
• Connection basic: Connection count and creation time
• Resiliency: Errors, handoffs, timeout relaxation
• Connection advanced: Wait time and use time
• Pubsub metrics: Published and received messages
• Stream metrics: Processing duration and maintenance notifications

🚀 New Features

• Added OTel instrumentation and metrics export for async client (#3977)

🐛 Bug Fixes

• [async] Adding access to cluster client's nodes_manager and set_response_callback in ClusterPipeline objects (#3989)
• fix(connection): Ensure we have an initialized protocol in connection (#3981)

🧰 Maintenance

• fix: use KeysT for blpop and brpop keys parameter type annotation (#3987 #3990)
• Bump actions/upload-artifact from 6 to 7 (#3985)
• fix: replace 3 bare except clauses with except Exception (#3980)

We'd like to thank all the contributors who worked on this release!
@mitre88 @turanalmammadov @haosenwang1018 @Medno @vladvildanov @petyaslavova

Changes

🐛 Bug Fixes

• Handle connection attributes conditionally for metrics and set connection data on exceptions in cluster error handling (#3964)

⚠️ Deprecations

• Removed batch_size and consumer_name attributes from OTel metrics (#3978)

🧰 Maintenance

• Fixing error handling of connection buffer purging of closed connections. Enabling troubleshooting logging for maintenance notifications e2e tests. (#3971)
• Fix protocol validation: replace finally with else and store parsed int (#3965)
• Return copies from _get_free/in_use_connections and fix async _mock (#3967)
• Add missing shard channel message types to async PubSub (#3966)
• Fix issues with ClusterPipeline connection management (#3804)
• fix(pubsub): avoid UnicodeDecodeError on reconnect with binary channel names (#3944)
• Hold references to ClusterNode disconnect task (#3826)
• remove remaining imports of typing_extensions (#3873)

We'd like to thank all the contributors who worked on this release!
@dotlambda @rhoboro @skylarkoo7 @praboud @bysiber @vladvildanov @petyaslavova

Changes

Redis 8.6 Support
Added support for Redis 8.6, including new commands and features for streams idempotent production and HOTKEYS.

Smart Client Handoff (Maintenance Notifications) for Cluster
note: Pending a Redis Enterprise version release

This release introduces comprehensive support for Redis Enterprise Cluster maintenance notifications via SMIGRATING/SMIGRATED push notifications. The client now automatically handles slot migrations by:

Relaxing timeouts during migration (SMIGRATING) to prevent false failures
Triggering cluster state reloads upon completion (SMIGRATED)
Enabling seamless operations during Redis Enterprise maintenance windows

OpenTelemetry Native Metrics Support
Added comprehensive OpenTelemetry metrics support following the OpenTelemetry Database Client Semantic Conventions.
Metric groups include:

• Command metrics: Operation duration with retry tracking
• Connection basic: Connection count and creation time
• Resiliency: Errors, handoffs, timeout relaxation
• Connection advanced: Wait time and use time
• Pubsub metrics: Published and received messages
• Stream metrics: Processing duration and maintenance notifications

🚀 New Features

• Added OTel instrumentation and metrics export for sync client (#3954)
• Add maintenance notifications support for OSS API cluster clients (#3946)
• Adding hotkeys commands support. (#3924)
• Adds support for the new Idempotent Producers feature in Redis 8.6 (#3926)
• Adding support for vrange command. (#3927)
• Added a local digest command to the client to execute the XXH3 locally… (#3884)
• Add DriverInfo class for upstream driver tracking (#3880)
• Add ssl_password support to async Redis client (#3878)
• Add ssl_ca_path support to async Redis client (#3879)

⚠️ Deprecations

• Adding special handling of client_tracking_on and client_tracking_off for cluster clients. Marking those two functions as deprecated for cluster - embedded client-side caching feature should be used instead. (#3858)

🐛 Bug Fixes

• Fix handling of circular MOVED redirects in cluster slot mapping (#3899)
• fix(asyncio): prevent deadlock when Lock.release() is cancelled (#3900)
• Fix unrecoverable connection state (#3905)
• Fixed potential race condition between call_later() and run_forever() (#3897)
• Fix RuntimeError in ClusterPubSub sharded message generator (#3889)
• Fix async connection pool lock contention during connection establishment (#3885)
• Fix PubSub client health check handling for sync client implementation (#3870)
• Adding retries for the overall connect - socket connect + handshake. Fix for pubsub reconnect issues. (#3863)
• Adding special handling of client_tracking_on and client_tracking_off for cluster clients. Marking those two functions as deprecated for cluster - embedded client-side caching feature should be used instead. (#3858)
• [#3618] Fix client-side cache invalidation for mixed str and bytes Redis keys (#3766)
• [#3612] Generating unique command cache key (#3765)

🧰 Maintenance

• Fix type hints for spop and srandmember methods (#3943)
• Reorganize pipeline actions (#3951)
• Extending the tests to validate more supported scorers for hybrid search. Adding experimental_method annotation to hybrid_search commands. (#3939)
• Bump rojopolis/spellcheck-github-actions from 0.56.0 to 0.58.0 (#3930)
• Adds a new helper that runs linters and fixes issues (#3928)
• Added testing with Timeseries samples with NaN values (#3932)
• Added testing with TLS-based authentication (#3931)
• Added support for calling run-tests from other repositories (#3923)
• Updating hybrid tests to be compatible with 8.4 and 8.6 changes. Adding 8.6 RC1 image to test matrix (#3922)
• Fix ClusterClient behavior when cluster topology is refreshed. Fix several places where connections might leak. (#3917)
• Fix copy-paste error in CacheProxyConnection server version check (#3918)
• Improve NodesManager locking (#3803)
• DOC: README Update relative urls (#3914)
• Bump rojopolis/spellcheck-github-actions from 0.55.0 to 0.56.0 (#3902)
• Bump actions/upload-artifact from 5 to 6 (#3901)
• Fix type hinting of zrange and zrangestore (#3872)
• Remove last vestiges of mock.mock (#3830)
• Improve type hints of from_url method for async Redis client. (#3796)
• Fix type hints for the available 'from_url' methods (#3816)
• Bump rojopolis/spellcheck-github-actions from 0.53.0 to 0.55.0 (#3862)
• Bump actions/checkout from 5 to 6 (#3861)
• Use MaxConnectionsError in the asyncio pool too (#3859)
• Updates PR template order (#3855)
• Changing current version in pipeline test config to 8.4 as it is already GA (#3854)
• Added custom event handler section (#3853)
• Changing log level to be debug for failed maintenance notification enablement when enabled='auto' (#3851)
• Update Type Hints for List Command Parameters from str to KeyT (#3848)
• Expand cluster READ_COMMANDS with additional read-only commands and reorganize the list of commands by category (#3845)

We'd like to thank all the contributors who worked on this release!
@veeceey @dariaguy @Nepomuk5665 @praboud @Timour-Ilyas @barshaul @devbyteai @itssimon @majiayu000 @aveao @s-t-e-v-e-n-k @cheizdo2-art @Jonathan-Landeed @PeterJCLaw @ShubhamKaudewar @vchomakov @dmaier-redislabs @elena-kolevska @vladvildanov @petyaslavova