{"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":"python","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,"search_vec":"'1.7.0':75 'api':55 'asyncio':81 'aw':34 'base':15 'bug':67 'cach':80 'client':17 'cloud':38 'connectionless':12 'current':59 'databas':51,79 'design':21 'e.g':33 'environ':26 'fix':68 'function':39 'ga':61 'googl':37 'http':14,28,82 'http-base':13 'interact':47 'interfac':45 'lambda':35 'latest':71 'librari':9 'prefer':30 'provid':41 'python':3,19,44 'receiv':63 'redi':2,8,16,50,76 'regular':64 'rest':54 'sdk':4,57 'server':25 'serverless':23,77 'simpl':43 'specif':20 'stabl':72 'stage':62 'tcp':32 'updat':65 'upstash':1,7,49,78 'upstash-redi':6 'vercel':36 'version':73 'via':52","created_at":"2026-04-15T18:49:34.833212+00:00","updated_at":"2026-04-16T23:59:12.866461+00:00","problems":[{"fix":"Install the library using pip: `pip install upstash-redis`","cause":"The 'upstash-redis' library is not installed in the current Python environment or the import statement is misspelled.","error":"ModuleNotFoundError: No module named 'upstash_redis'"},{"fix":"Set the environment variables `UPSTASH_REDIS_REST_URL` and `UPSTASH_REDIS_REST_TOKEN` in your environment, or pass them directly to the `Redis` constructor: `redis = Redis(url='your_url', token='your_token')`","cause":"The 'upstash-redis' client could not find the 'UPSTASH_REDIS_REST_URL' and 'UPSTASH_REDIS_REST_TOKEN' environment variables, and they were not provided as arguments to the Redis constructor.","error":"ValueError: url and token must be set via constructor or environment variables"},{"fix":"Verify that your `UPSTASH_REDIS_REST_URL` and `UPSTASH_REDIS_REST_TOKEN` are correct and active for your Upstash Redis database instance. Generate a new token from the Upstash console if necessary.","cause":"The provided `UPSTASH_REDIS_REST_TOKEN` is incorrect, expired, or does not have sufficient permissions for the Upstash Redis API.","error":"upstash_redis.exceptions.RedisError: Operation failed: Request to Upstash Redis failed with status 401: Unauthorized"},{"fix":"Use the `hset` command, which accepts multiple field-value pairs: `redis.hset('myhash', 'field1', 'value1', 'field2', 'value2')`","cause":"The `hmset` command is deprecated in standard Redis and not directly implemented by the `upstash-redis` client; users should use `hset` which supports multiple field-value pairs.","error":"AttributeError: 'Redis' object has no attribute 'hmset'"}],"ecosystem":"pypi","meta_description":null,"install_score":null,"quickstart_score":null,"quickstart_tag":null,"pypi_latest":"1.7.0","cli_name":"","cli_version":null,"type":"library","homepage":"https://upstash.com","github":"https://github.com/upstash/redis-python","docs":null,"changelog":null,"pypi":"https://pypi.org/project/upstash-redis/","npm":null,"openapi_spec":null,"status_page":null,"smithery":null,"categories":["database","http-networking","aws","gcp"],"base_url":null,"auth_type":null,"provenance":{"verified_status":"passing","verified_at":"2026-06-28","last_verified":"2026-06-28","next_check":"2026-07-28","install_tag":null}}