{"id":6940,"library":"upstash-redis","title":"Upstash Redis Python SDK","description":"The `upstash-redis` library is a connectionless, HTTP-based Redis client for Python, specifically designed for serverless and serverful environments where HTTP is preferred over TCP (e.g., AWS Lambda, Vercel, Google Cloud Functions). It provides a simple, Pythonic interface to interact with Upstash Redis databases via their REST API. The SDK is currently in GA stage, receives regular updates and bug fixes, and its latest stable version is 1.7.0.","status":"active","version":"1.7.0","language":"en","source_language":"en","source_url":"https://github.com/upstash/redis-python","tags":["redis","serverless","upstash","database","cache","asyncio","http"],"install":[{"cmd":"pip install upstash-redis","lang":"bash","label":"Install stable version"}],"dependencies":[{"reason":"Used internally for handling asynchronous HTTP calls. Automatically installed as a transitive dependency.","package":"aiohttp","optional":false}],"imports":[{"note":"The direct import `from upstash_redis import Redis` is the current and recommended path for the synchronous client. The `from upstash_redis.client import Redis` path was used in earlier versions but is generally not recommended anymore. [4, 9]","wrong":"from upstash_redis.client import Redis","symbol":"Redis","correct":"from upstash_redis import Redis"},{"note":"This is the correct import path for the asynchronous Redis client.","symbol":"Redis (async)","correct":"from upstash_redis.asyncio import Redis"}],"quickstart":{"code":"import os\nfrom upstash_redis import Redis\n\n# Ensure environment variables are set for demonstration\n# In a real application, set UPSTASH_REDIS_REST_URL and UPSTASH_REDIS_REST_TOKEN\n# in your environment or pass them directly to Redis().\nos.environ['UPSTASH_REDIS_REST_URL'] = os.environ.get('UPSTASH_REDIS_REST_URL', 'YOUR_UPSTASH_REDIS_REST_URL')\nos.environ['UPSTASH_REDIS_REST_TOKEN'] = os.environ.get('UPSTASH_REDIS_REST_TOKEN', 'YOUR_UPSTASH_REDIS_REST_TOKEN')\n\ndef run_sync_example():\n    try:\n        redis_sync = Redis.from_env()\n        redis_sync.set('mykey_sync', 'myvalue_sync')\n        value = redis_sync.get('mykey_sync')\n        print(f\"Sync: Set 'mykey_sync' to 'myvalue_sync', retrieved: {value}\")\n        redis_sync.delete('mykey_sync')\n    except Exception as e:\n        print(f\"Sync example failed: {e}\")\n\nif __name__ == '__main__':\n    print(\"Running synchronous example...\")\n    run_sync_example()\n\n    # Async example (requires asyncio and aiohttp)\n    import asyncio\n    from upstash_redis.asyncio import Redis\n\n    async def run_async_example():\n        try:\n            redis_async = Redis.from_env()\n            await redis_async.set('mykey_async', 'myvalue_async')\n            value = await redis_async.get('mykey_async')\n            print(f\"Async: Set 'mykey_async' to 'myvalue_async', retrieved: {value}\")\n            await redis_async.delete('mykey_async')\n        except Exception as e:\n            print(f\"Async example failed: {e}\")\n\n    print(\"\\nRunning asynchronous example...\")\n    asyncio.run(run_async_example())\n","lang":"python","description":"This quickstart demonstrates how to initialize both synchronous and asynchronous Upstash Redis clients using environment variables (`UPSTASH_REDIS_REST_URL` and `UPSTASH_REDIS_REST_TOKEN`). It performs a simple `SET` and `GET` operation. In serverless environments, it is recommended to initialize the client outside the request handler to maximize reuse and efficiency. [1, 3, 8, 9]"},"warnings":[{"fix":"Explicitly serialize non-scalar values (e.g., dictionaries) to JSON strings using `json.dumps()` before passing them to `set()` or `hset()`.","message":"In version 1.0.0, the `set` and `hset` commands changed their `value` type from `Any` to `ValueT` (Union[str, int, float, bool]). Directly passing dictionaries or other complex objects for JSON storage will now result in a type error. You must explicitly `json.dumps()` such values before setting them. [2]","severity":"breaking","affected_versions":">=1.0.0"},{"fix":"If your code relies on the previous `Set` return type, you will need to explicitly convert the `List` result to a `set` (e.g., `set(redis.smembers('my_set'))`).","message":"With version 1.0.0, the return types for set-related commands like `sdiff`, `sunion`, `sinter`, and `smembers` were changed from `Set` to `List`. This was done to avoid unnecessary set allocations. [2]","severity":"breaking","affected_versions":">=1.0.0"},{"fix":"To opt-out, set `allow_telemetry=False` when initializing the `Redis` client (e.g., `Redis.from_env(allow_telemetry=False)`) or set the environment variable `UPSTASH_DISABLE_TELEMETRY=true`. [5, 7, 11]","message":"The SDK collects anonymous telemetry data by default (e.g., SDK version, platform, Python runtime version). This feature was introduced around v1.5.0. [1, 3, 5, 7, 9, 11]","severity":"gotcha","affected_versions":">=1.5.0"},{"fix":"Upgrade to SDK v1.2.0+ for automatic handling. If using older versions or the REST API directly, capture the `upstash-sync-token` from a write response and include it in subsequent read requests.","message":"The 'Read Your Writes' consistency feature, which ensures that write operations are completed before subsequent reads, is automatically managed by the SDK for versions 1.2.0 and later. If you are using an older SDK version or interacting directly with the REST API, you need to manually manage the `upstash-sync-token` header for strong consistency. [13]","severity":"gotcha","affected_versions":"<1.2.0 (SDK), or direct REST API users"},{"fix":"If you are certain your data is valid JSON and you want to avoid the encoding overhead, you can set `rest_encoding=None` or `rest_encoding=False` when initializing the client (e.g., `Redis.from_env(rest_encoding=None)`). [5]","message":"By default, the Upstash REST proxy may base64 encode/decode data, especially when dealing with JSON. While this ensures data integrity, it can introduce slight latency, particularly for very large payloads. [1, 5]","severity":"gotcha","affected_versions":"All versions"}],"env_vars":null,"last_verified":"2026-04-15T00:00:00.000Z","next_check":"2026-07-14T00:00:00.000Z","problems":[]}