Valkey Python Client

Warnings

• breaking Starting 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.
  Fix: Review your application's use of expiration/TTL commands. If relying on removed functionality, adjust your code or ensure your Valkey server supports the commands.
• breaking Python 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.
  Fix: Ensure your project uses Python 3.10 or a newer compatible version.
• gotcha Valkey-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.
  Fix: Prefer `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.
• gotcha By 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.
  Fix: Initialize your client with `valkey.Valkey(decode_responses=True)` or `valkey.from_url(..., decode_responses=True)` if you primarily work with string data.
• gotcha When 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.
  Fix: Always call `await client.aclose()` when you are finished with an async client to prevent resource leaks.
• gotcha For 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.
  Fix: Ensure your Pub/Sub loop or background task frequently processes messages or explicitly calls `p.check_health()` to maintain the connection.

Install

• pip install valkey Default Install
• pip install "valkey[libvalkey]" With C-parser for performance

Imports

• Valkey

  from valkey import Valkey

• Redis

  from valkey import Redis

  Valkey-py provides a 'Redis' alias for compatibility, but `valkey.Valkey` is recommended as the official class name.

Quickstart

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()