Install & Compatibility
Where this runs
tested against v6.1.1 · 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
muslpy 3.10–3.910 runs
installs and imports cleanly · install 0.0s · import 0.382s · 20.5MB
glibcpy 3.10–3.910 runs
installs and imports cleanly · install 1.8s · import 0.336s · 21MB
19MB installed
● package 19MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
Valkey
✓ from valkey import Valkey
Redis
✓ from valkey import Redis
✗ from redis import Redis
Valkey-py provides a 'Redis' alias for compatibility, but `valkey.Valkey` is recommended as the official class name.
Connects to a Valkey server, pings it to verify the connection, then sets and retrieves a simple string key. It demonstrates using `from_url` for flexible connection and `decode_responses=True` for working with strings instead of bytes.
import valkey
import os
def main():
# Connect to Valkey (defaults to localhost:6379)
# Use VALKEY_URL environment variable for production configurations
valkey_url = os.environ.get('VALKEY_URL', 'valkey://localhost:6379')
r = valkey.from_url(valkey_url, decode_responses=True)
try:
r.ping()
print(f"Connected to Valkey at {valkey_url}")
# Set a key-value pair
r.set('mykey', 'Hello, Valkey!')
print("Set 'mykey' to 'Hello, Valkey!'")
# Get the value back
value = r.get('mykey')
print(f"Value of 'mykey': {value}")
except valkey.exceptions.ConnectionError as e:
print(f"Could not connect to Valkey: {e}")
finally:
# For async clients, explicitly await aclose()
# For sync clients, connection is managed by pool
pass
if __name__ == '__main__':
main()
Debug
Known issues
breakingStarting with `v6.1.0b1`, Valkey-py removed expiration/TTL commands not supported by Valkey (diverging from Redis behavior). Verify if your application relies on specific TTL commands that might have been dropped.fixReview your application's use of expiration/TTL commands. If relying on removed functionality, adjust your code or ensure your Valkey server supports the commands.
affects: >=6.1.0b1
breakingPython version support has changed. `v6.1.1` dropped Python 3.8 support, and `v6.2.0rc1` (future stable `6.2.0`) dropped Python 3.9 support. Valkey-py now officially requires Python 3.10 or newer.fixEnsure your project uses Python 3.10 or a newer compatible version.
affects: >=6.1.1 (for Python 3.8), >=6.2.0rc1 (for Python 3.9)
gotchaValkey-py is a fork of `redis-py`. While highly compatible with Redis 7.2, Valkey and Redis are separate projects with independent roadmaps. Expect potential future divergence in features, commands, and API behaviors.fixPrefer `valkey.Valkey()` over `valkey.Redis()` and consult Valkey-py's official documentation for the most accurate command and feature set. Avoid assuming full compatibility with all new Redis features or modules.
affects: All versions
gotchaBy default, Valkey-py returns responses as bytes. To receive decoded strings, you must explicitly pass `decode_responses=True` to the `Valkey` or `from_url` constructor.fixInitialize your client with `valkey.Valkey(decode_responses=True)` or `valkey.from_url(..., decode_responses=True)` if you primarily work with string data.
affects: All versions
gotchaWhen using `valkey.asyncio` clients, explicit disconnection via `await client.aclose()` is required to properly close connections and internal connection pools, especially if you create custom `ConnectionPool` instances.fixAlways call `await client.aclose()` when you are finished with an async client to prevent resource leaks.
affects: All async versions
gotchaFor Pub/Sub features, if `health_check_interval` is set (e.g., in a `from_url` connection), you must call `get_message()` or `listen()` (or `check_health()`) frequently enough to avoid connection timeouts. Failure to do so can lead to connection closure by the server.fixEnsure your Pub/Sub loop or background task frequently processes messages or explicitly calls `p.check_health()` to maintain the connection.
affects: All versions using Pub/Sub with `health_check_interval`
Errors
Common errors & fixes
ConnectionError: [Errno 111] Connection refused
The Valkey server is not running, is not accessible from the client's host, or is listening on a different IP/port than configured in the client.
fixEnsure the Valkey server is running, check its configured bind address and port (default 6379), verify network connectivity and firewall rules, and use the correct host/port in your client code: `client = valkey.Valkey(host='your_valkey_host', port=6379)`
ModuleNotFoundError: No module named 'redis'
The code is attempting to import from the `redis` package, but the `valkey-py` library is installed, which provides its client under the `valkey` namespace. This often happens when migrating from `redis-py` or using tutorials/examples written for `redis-py`.
fixReplace `import redis` with `import valkey` (or `import valkey as redis` for compatibility) and adjust class instantiation from `redis.Redis()` to `valkey.Valkey()`.
valkey.exceptions.AuthenticationError: invalid password
The Valkey server requires authentication, but the client either provided no password or an incorrect one.
fixProvide the correct password when instantiating the client: `client = valkey.Valkey(password='your_strong_password')`
AttributeError: 'Valkey' object has no attribute 'aclose'
An asynchronous method like `aclose` (used for `async with` context managers) is being called on a synchronous `valkey.Valkey` client instance.
fixFor asynchronous operations and `async with`, use the `valkey.asyncio.Valkey` client: `from valkey.asyncio import Valkey as AsyncValkey; async with AsyncValkey(...) as r: ...`
Upgrade
Version history
6.1.1latest on PyPI · released Aug 11, 2025
Audit
Dependencies
PythonrequiredRequires Python 3.10 or newer.
hiredisoptionalOptional C extension for faster response parsing, installed with 'valkey[libvalkey]'.