Install & Compatibility
Where this runs
tested against v1.7.0 · pip install
no network on importno background threads
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
muslpy 3.10–3.920 runs
installs and imports cleanly · install 0.0s · import 0.418s · 22.5MB
glibcpy 3.10–3.920 runs
installs and imports cleanly · install 2.2s · import 0.373s · 23MB
20MB installed
● package 20MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
Redis
✓ from upstash_redis import Redis
✗ from upstash_redis.client import Redis
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]
Redis (async)
✓ from upstash_redis.asyncio import Redis
This is the correct import path for the asynchronous Redis client.
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]
import os
from upstash_redis import Redis
# Ensure environment variables are set for demonstration
# In a real application, set UPSTASH_REDIS_REST_URL and UPSTASH_REDIS_REST_TOKEN
# in your environment or pass them directly to Redis().
os.environ['UPSTASH_REDIS_REST_URL'] = os.environ.get('UPSTASH_REDIS_REST_URL', 'YOUR_UPSTASH_REDIS_REST_URL')
os.environ['UPSTASH_REDIS_REST_TOKEN'] = os.environ.get('UPSTASH_REDIS_REST_TOKEN', 'YOUR_UPSTASH_REDIS_REST_TOKEN')
def run_sync_example():
try:
redis_sync = Redis.from_env()
redis_sync.set('mykey_sync', 'myvalue_sync')
value = redis_sync.get('mykey_sync')
print(f"Sync: Set 'mykey_sync' to 'myvalue_sync', retrieved: {value}")
redis_sync.delete('mykey_sync')
except Exception as e:
print(f"Sync example failed: {e}")
if __name__ == '__main__':
print("Running synchronous example...")
run_sync_example()
# Async example (requires asyncio and aiohttp)
import asyncio
from upstash_redis.asyncio import Redis
async def run_async_example():
try:
redis_async = Redis.from_env()
await redis_async.set('mykey_async', 'myvalue_async')
value = await redis_async.get('mykey_async')
print(f"Async: Set 'mykey_async' to 'myvalue_async', retrieved: {value}")
await redis_async.delete('mykey_async')
except Exception as e:
print(f"Async example failed: {e}")
print("\nRunning asynchronous example...")
asyncio.run(run_async_example())
Debug
Known issues
breakingIn 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]fixExplicitly serialize non-scalar values (e.g., dictionaries) to JSON strings using `json.dumps()` before passing them to `set()` or `hset()`.
affects: >=1.0.0
breakingWith 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]fixIf 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'))`). affects: >=1.0.0
gotchaThe 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]fixTo 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]
affects: >=1.5.0
gotchaThe '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]fixUpgrade 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.
affects: <1.2.0 (SDK), or direct REST API users
gotchaBy 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]fixIf 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]
affects: All versions
Errors
Common errors & fixes
ModuleNotFoundError: No module named 'upstash_redis'
The 'upstash-redis' library is not installed in the current Python environment or the import statement is misspelled.
fixInstall the library using pip: `pip install upstash-redis`
ValueError: url and token must be set via constructor or environment variables
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.
fixSet 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')`
upstash_redis.exceptions.RedisError: Operation failed: Request to Upstash Redis failed with status 401: Unauthorized
The provided `UPSTASH_REDIS_REST_TOKEN` is incorrect, expired, or does not have sufficient permissions for the Upstash Redis API.
fixVerify 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.
AttributeError: 'Redis' object has no attribute 'hmset'
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.
fixUse the `hset` command, which accepts multiple field-value pairs: `redis.hset('myhash', 'field1', 'value1', 'field2', 'value2')` Upgrade
Version history
1.7.0latest on PyPI · released Mar 18, 2026
Audit
Dependencies
aiohttprequiredUsed internally for handling asynchronous HTTP calls. Automatically installed as a transitive dependency.