{"id":2350,"library":"valkey","title":"Valkey Python Client","description":"Valkey-py is a high-performance Python client for Valkey, a robust open-source (BSD) key/value datastore. Forked from redis-py, it supports a variety of workloads including caching, message queues, and acting as a primary database. The library is actively maintained with frequent releases, including release candidates for upcoming versions.","status":"active","version":"6.1.1","language":"en","source_language":"en","source_url":"https://github.com/valkey-io/valkey-py","tags":["database","kv-store","nosql","redis-compatible","async","client"],"install":[{"cmd":"pip install valkey","lang":"bash","label":"Default Install"},{"cmd":"pip install \"valkey[libvalkey]\"","lang":"bash","label":"With C-parser for performance"}],"dependencies":[{"reason":"Requires Python 3.10 or newer.","package":"Python","optional":false},{"reason":"Optional C extension for faster response parsing, installed with 'valkey[libvalkey]'.","package":"hiredis","optional":true}],"imports":[{"symbol":"Valkey","correct":"from valkey import Valkey"},{"note":"Valkey-py provides a 'Redis' alias for compatibility, but `valkey.Valkey` is recommended as the official class name.","wrong":"from redis import Redis","symbol":"Redis","correct":"from valkey import Redis"}],"quickstart":{"code":"import valkey\nimport os\n\ndef main():\n    # Connect to Valkey (defaults to localhost:6379)\n    # Use VALKEY_URL environment variable for production configurations\n    valkey_url = os.environ.get('VALKEY_URL', 'valkey://localhost:6379')\n    r = valkey.from_url(valkey_url, decode_responses=True)\n\n    try:\n        r.ping()\n        print(f\"Connected to Valkey at {valkey_url}\")\n\n        # Set a key-value pair\n        r.set('mykey', 'Hello, Valkey!')\n        print(\"Set 'mykey' to 'Hello, Valkey!'\")\n\n        # Get the value back\n        value = r.get('mykey')\n        print(f\"Value of 'mykey': {value}\")\n\n    except valkey.exceptions.ConnectionError as e:\n        print(f\"Could not connect to Valkey: {e}\")\n    finally:\n        # For async clients, explicitly await aclose()\n        # For sync clients, connection is managed by pool\n        pass\n\nif __name__ == '__main__':\n    main()","lang":"python","description":"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."},"warnings":[{"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.","message":"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.","severity":"breaking","affected_versions":">=6.1.0b1"},{"fix":"Ensure your project uses Python 3.10 or a newer compatible version.","message":"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.","severity":"breaking","affected_versions":">=6.1.1 (for Python 3.8), >=6.2.0rc1 (for Python 3.9)"},{"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.","message":"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.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Initialize your client with `valkey.Valkey(decode_responses=True)` or `valkey.from_url(..., decode_responses=True)` if you primarily work with string data.","message":"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.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Always call `await client.aclose()` when you are finished with an async client to prevent resource leaks.","message":"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.","severity":"gotcha","affected_versions":"All async versions"},{"fix":"Ensure your Pub/Sub loop or background task frequently processes messages or explicitly calls `p.check_health()` to maintain the connection.","message":"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.","severity":"gotcha","affected_versions":"All versions using Pub/Sub with `health_check_interval`"}],"env_vars":null,"last_verified":"2026-04-09T00:00:00.000Z","next_check":"2026-07-08T00:00:00.000Z"}