{"id":7531,"library":"py-redis","title":"py-redis (Redis Client Wrapper)","description":"py-redis is a convenience wrapper for the official `redis-py` package, simplifying Redis client instantiation. It allows configuring the client via environment variables (REDIS_HOST, REDIS_PORT, REDIS_DB, REDIS_PASSWORD) and provides a single function to get a pre-configured `redis.Redis` instance. The current version is 1.1.1, and its release cadence is infrequent as it primarily provides a thin stable wrapper.","status":"active","version":"1.1.1","language":"en","source_language":"en","source_url":"https://github.com/pkeilbach/pyredis","tags":["redis","client","wrapper","configuration","database","cache"],"install":[{"cmd":"pip install py-redis","lang":"bash","label":"Install py-redis"}],"dependencies":[{"reason":"Required as `py-redis` wraps the official `redis-py` client library.","package":"redis","optional":false}],"imports":[{"note":"While `py-redis` wraps `redis-py`, you should use `get_redis_client` to leverage its environment variable configuration and default settings, rather than directly importing `Redis` from `redis`.","wrong":"from redis import Redis","symbol":"get_redis_client","correct":"from pyredis import get_redis_client"}],"quickstart":{"code":"import os\nfrom pyredis import get_redis_client\n\n# Configure Redis connection via environment variables for robustness\n# Example: REDIS_HOST=localhost REDIS_PORT=6379 REDIS_DB=0 REDIS_PASSWORD=\"\"\n\n# Fallback to defaults if env vars are not set\nredis_host = os.environ.get('REDIS_HOST', 'localhost')\nredis_port = int(os.environ.get('REDIS_PORT', '6379'))\nredis_db = int(os.environ.get('REDIS_DB', '0'))\nredis_password = os.environ.get('REDIS_PASSWORD') or None\n\ntry:\n    # Get a configured Redis client instance\n    # decode_responses=True is highly recommended for working with strings\n    redis_client = get_redis_client(\n        host=redis_host,\n        port=redis_port,\n        db=redis_db,\n        password=redis_password,\n        decode_responses=True\n    )\n\n    # Test the connection\n    redis_client.ping()\n    print(\"Successfully connected to Redis!\")\n\n    # Perform a simple operation\n    redis_client.set('mykey', 'Hello, py-redis!')\n    value = redis_client.get('mykey')\n    print(f\"Retrieved from Redis: {value}\")\n\n    redis_client.delete('mykey') # Clean up\n\nexcept Exception as e:\n    print(f\"Could not connect to Redis or an error occurred: {e}\")\n    print(\"Please ensure Redis server is running and connection details are correct.\")\n","lang":"python","description":"This quickstart demonstrates how to get a Redis client using `get_redis_client`, leveraging environment variables for configuration. It then performs a basic `set` and `get` operation, ensuring `decode_responses=True` for string handling."},"warnings":[{"fix":"Explicitly check both environment variables and `get_redis_client` call arguments to understand the final configuration applied.","message":"Parameters passed directly to `get_redis_client()` will override any corresponding environment variables (e.g., `REDIS_HOST`, `REDIS_PORT`). Ensure your explicit arguments align with or intentionally override your environment setup.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Always explicitly set `decode_responses=True` in `get_redis_client()` if you expect Python strings, or manually decode the byte strings using `.decode('utf-8')` after retrieval.","message":"By default, `redis-py` (and thus `py-redis` if `decode_responses` is not set) returns byte strings. If you omit `decode_responses=True`, you'll receive bytes, which can lead to `TypeError` when expecting strings (e.g., in JSON serialization).","severity":"gotcha","affected_versions":"All versions"},{"fix":"Refer to `redis-py`'s changelog for major version updates. Ensure your `redis-py` dependency (either explicit or through `py-redis`'s requirements) is stable and compatible with your `py-redis` version.","message":"As `py-redis` is a thin wrapper around `redis-py`, breaking changes or deprecations in the underlying `redis-py` library (which `py-redis` depends on) can indirectly affect your application, especially if `redis-py` itself is updated.","severity":"gotcha","affected_versions":"Any version where `redis-py` has major updates"}],"env_vars":null,"last_verified":"2026-04-16T00:00:00.000Z","next_check":"2026-07-15T00:00:00.000Z","problems":[{"fix":"pip install py-redis","cause":"The `py-redis` package is not installed in the current Python environment.","error":"ModuleNotFoundError: No module named 'pyredis'"},{"fix":"Ensure your Redis server is running and accessible. Verify the host, port, and password provided to `get_redis_client()` or set in environment variables (`REDIS_HOST`, `REDIS_PORT`, `REDIS_PASSWORD`) are correct.","cause":"The Redis server is either not running, not accessible from the current machine, or configured on a different host/port than specified.","error":"redis.exceptions.ConnectionError: Error 111 connecting to localhost:6379. Connection refused."},{"fix":"Pass `decode_responses=True` to `get_redis_client()` to automatically decode Redis responses into strings, or manually decode the byte strings using `.decode('utf-8')` after retrieval.","cause":"You retrieved data from Redis that is still in `bytes` format (because `decode_responses=False` or was omitted), but you're trying to use it where a string is expected (e.g., `json.loads()`).","error":"TypeError: Object of type bytes is not JSON serializable"},{"fix":"pip install redis (This is usually handled automatically when `py-redis` is installed, but can occur if dependencies are manipulated or if `py-redis` was installed with `--no-deps`.)","cause":"The core `redis-py` library, which `py-redis` depends on, is not installed.","error":"ModuleNotFoundError: No module named 'redis'"}]}