Registry / database / coredis

coredis

JSON →
library6.8.0pypypi✓ verified 25d ago

coredis is a fast, async, and fully-typed Redis client for Python, offering support for Redis Cluster, Sentinel, and various Redis modules. It is built with structured concurrency using `anyio`, supporting both `asyncio` and `trio`. The library is actively maintained with frequent releases, often multiple times a month for bug fixes and minor features, with major architectural rewrites released periodically. The current version is 6.5.1.

pip install coredis
INSTALL
IMPORT
SIG · COREDIS
C
coredis
databasepythonv6.8.0
Install
4.2s avg
Import
1009ms
Disk
30MB
Pass rate
10/ 10
Env Coverage10 / 10
glibc
3.93.13
musl
3.93.13
Install & Compatibility
Where this runs
tested against v6.8.0 · pip install
no network on importno background threads
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
musl
py 3.103.95 runs
installs and imports cleanly · install 0.0s · import 1.072s · 33.5MB
glibc
py 3.103.95 runs
installs and imports cleanly · install 4.2s · import 0.946s · 35MB
30MB installed
● package 30MB
Code
Verified usage

Verified import paths — ran on the pinned version, not inferred.

Redis
from coredis import Redis
RedisCluster
from coredis import RedisCluster
Sentinel
from coredis import Sentinel
TCPLocation
from coredis.connection import TCPLocation
Used for specifying startup nodes for RedisCluster.
Pipeline, PubSub, Lock, Streams, Cache
from coredis.patterns import Pipeline, PubSub
from coredis import Pipeline
Prior to v6.0.0rc3, these patterns were directly under `coredis` or `coredis.commands`. They were moved to `coredis.patterns`.

This quickstart demonstrates connecting to a single Redis instance, performing basic `SET`, `GET`, `INCR` operations, and using a command pipeline. It leverages `anyio.run` to execute the asynchronous code and uses `os.environ.get` for flexible Redis URL configuration.

import anyio import coredis import os async def main() -> None: # Connect to Redis. Use a URL from an environment variable or default to localhost redis_url = os.environ.get('COREDIS_URL', 'redis://localhost:6379/0') # Optionally, decode responses to get Python strings instead of bytes client = coredis.Redis.from_url(redis_url, decode_responses=True) async with client: # Clear the database (use with caution in production!) print(f"Flushing database...") await client.flushdb() # Basic SET and GET operations print(f"Setting 'mykey' to 'hello'") await client.set("mykey", "hello") value = await client.get("mykey") print(f"Value of 'mykey': {value}") assert value == "hello" # Increment a numerical value print(f"Incrementing 'counter'") await client.set("counter", 1) assert await client.incr("counter") == 2 print(f"Value of 'counter' after increment: {await client.get('counter')}") # Using a pipeline for multiple commands in a single round trip print("Running a pipeline...") async with client.pipeline() as pipeline: pipeline.incr("pipeline_counter") pipeline.get("pipeline_counter") pipeline.delete(["pipeline_counter"]) results = await pipeline.execute() print(f"Pipeline results: {results}") # Expected: [1, '1', 1] (if decode_responses=True) if __name__ == "__main__": # coredis uses anyio, supporting asyncio and trio. Specify your preferred backend. anyio.run(main, backend="asyncio")
Debug
Known issues
breakingVersion 6.0.0 introduced a major architectural rewrite, migrating the entire library to `anyio` for structured concurrency, supporting both `asyncio` and `trio`. This requires significant changes to existing applications built on 5.x, especially regarding connection management and asynchronous patterns.
fix
Refer to the official 'Migrating from 5.x to 6.0' guide in the coredis documentation for detailed upgrade instructions. Update your async code to follow `anyio`'s structured concurrency patterns, typically using `async with client:` for resource management.
affects: >=6.0.0
breakingSeveral submodules for application patterns (e.g., Pub/Sub, Pipeline, Stream, Cache, Lock) were moved from `coredis.commands.*` or directly under `coredis` to `coredis.patterns` in version 6.0.0rc3.
fix
Update your import statements to reflect the new `coredis.patterns` module path. For example, `from coredis.pipeline import Pipeline` becomes `from coredis.patterns import Pipeline`.
affects: >=6.0.0rc3
gotchaVersion 6.5.0 introduced a regression where batch request cancellations were suppressed, potentially leading to unexpected behavior in certain scenarios.
fix
Upgrade to coredis version 6.5.1 or newer to fix this regression.
affects: 6.5.0
gotchaIn versions prior to 6.2.0, if `__aenter__` failed during connection pool initialization, the connection pool could become unusable as its counter would be stuck.
fix
Upgrade to coredis version 6.2.0 or newer to ensure proper connection pool task group cleanup and recovery from initialization errors.
affects: <6.2.0
gotchaIn versions prior to 6.1.0, there was an incorrect initialization of the connection capacity limiter, leading to a module-level shared capacity limiter instead of an instance-specific one.
fix
Upgrade to coredis version 6.1.0 or newer to resolve this issue and ensure correct connection capacity limiting.
affects: <6.1.0
gotchaIn versions prior to 5.7.0, username and password provided as keyword arguments to `from_url` might not have been correctly used if no credentials were found within the URL string itself.
fix
Upgrade to coredis version 5.7.0 or newer. Ensure the URL contains credentials (e.g., `redis://user:password@host:port`) or pass them explicitly and correctly.
affects: <5.7.0
Errors
Common errors & fixes
ModuleNotFoundError: No module named 'coredis.response'
This error typically occurred in older versions of coredis (e.g., v3.0.0) due to a packaging issue where the 'response' directory was missing from the installed package.
fix
Ensure you have the latest stable version of coredis installed. Upgrade using `pip install --upgrade coredis`.
coredis.exceptions.ConnectionError: You must set server_hostname when using ssl without a host
This error occurs when attempting to establish an SSL/TLS connection to Redis using coredis without specifying the `server_hostname` in the connection parameters, often with services like AWS ElastiCache. It can also be caused by incorrect connection string parsing due to special characters in the password.
fix
Provide the full hostname/endpoint when configuring the SSL connection. For example, `coredis.Redis(host='your-endpoint.redis.cache.amazonaws.com', port=6380, ssl=True, server_hostname='your-endpoint.redis.cache.amazonaws.com', password='your_password')`. Ensure no unescaped special characters like '#' are in the password if using a URI.
coredis.exceptions.RedisClusterError: Redis Cluster cannot be connected. Please provide at least one reachable node.
This exception is raised when the coredis `RedisCluster` client cannot discover or connect to any of the provided startup nodes, or if the Redis Cluster is not healthy (e.g., 'CLUSTERDOWN'). It can also occur if the Redis cluster version is too old and does not support the HELLO command (e.g., Redis 5.x with coredis defaults).
fix
Verify that the Redis Cluster nodes are running and reachable from the client, and that the provided host/port configurations are correct. Ensure your Redis Cluster version is 6.x or newer, or explicitly configure `protocol_version=2` if using Redis 5.x. Check firewall rules and network connectivity. For `coredis` v6.2.0 and later, the base exception name is `coredis.exceptions.RedisClusterError` (an alias for older `RedisClusterException` is maintained).
coredis.exceptions.AuthenticationFailureError
This error is raised when authentication parameters were provided to the Redis client but they were invalid, such as an incorrect password or ACL user.
fix
Ensure the `password` (and `username` if using Redis ACLs) provided during client initialization matches the configuration of your Redis server. Example: `client = coredis.Redis(host='localhost', port=6379, password='correct_password')`.
Upgrade
Version history
6.8.0latest on PyPI · released Jul 23, 2026
Audit
Dependencies
anyiorequiredCore dependency for structured concurrency and async backend support (asyncio/trio).
beartypeoptionalOptional dependency for runtime type validation, enabled via COREDIS_RUNTIME_CHECKS environment variable.
Agent activity
26 hits · last 30 days
node
22
OpenAI (training)
1
Resources