Upstash Python SDK

1.2.0 · active · verified Tue Mar 17

Unified Python SDK for Upstash cloud services including Redis, Vector, QStash, and Workflow. Provides serverless-friendly clients optimized for edge and serverless environments with HTTP-based connections. Replaces the older individual packages (upstash-redis, upstash-vector, upstash-qstash).

Warnings

gotcha Upstash Redis uses HTTP REST calls, not the Redis wire protocol. Standard redis-py commands that rely on persistent TCP connections (SUBSCRIBE, BLPOP, WATCH) are not supported.
Fix: Use QStash for pub/sub messaging patterns instead of Redis SUBSCRIBE.
gotcha Redis.from_env() reads UPSTASH_REDIS_REST_URL and UPSTASH_REDIS_REST_TOKEN from environment. These must be the REST endpoint, not the standard Redis port 6379 URL.
Fix: Use the REST URL from the Upstash console (https://...upstash.io), not the redis:// connection string.
breaking The unified 'upstash' package changed internal module structure. Imports like 'from upstash.redis import Redis' do not work. Use 'from upstash_redis import Redis'.
Fix: from upstash_redis import Redis
gotcha Redis.get() returns None for missing keys, not raising a KeyError. Pipeline results are returned as a list, not individual values.
Fix: Always check for None when reading keys: value = redis.get('key') or 'default'
gotcha Each Redis command makes an individual HTTP request. Use pipelines to batch multiple commands and reduce latency.
Fix: pipe = redis.pipeline(); pipe.set('a', '1'); pipe.get('a'); results = pipe.execute()
deprecated The separate upstash-redis, upstash-vector, and upstash-qstash packages are being consolidated into the unified upstash package. Individual packages still work but may not receive updates.
Fix: pip install upstash for the unified SDK going forward.

Install

pip install upstash Python (unified SDK)
pip install upstash-redis Python (Redis only, legacy)
pip install upstash-vector Python (Vector only, legacy)
pip install upstash-qstash Python (QStash only, legacy)

Imports

Redis
```
from upstash_redis import Redis
```
Redis client is imported from upstash_redis, not from the top-level upstash module.
Index
```
from upstash_vector import Index
```
Vector client is the Index class from upstash_vector.
QStash
```
from upstash_qstash import QStash
```
QStash client is imported from upstash_qstash submodule.

Quickstart

Minimal Redis set/get using the Upstash Redis client with HTTP-based connection.

import os
from upstash_redis import Redis

redis = Redis(
    url=os.environ.get('UPSTASH_REDIS_REST_URL', ''),
    token=os.environ.get('UPSTASH_REDIS_REST_TOKEN', '')
)

redis.set('greeting', 'Hello from Upstash!')
value = redis.get('greeting')
print(value)

view raw JSON →