Upstash Python SDK

1.2.0 verified Tue May 12 auth: no python install: verified quickstart: stale

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).

pip install upstash

Common errors

error ModuleNotFoundError: No module named 'upstash_redis' ↓

cause The `upstash` unified SDK replaces older individual packages like `upstash-redis`. Attempts to import from the old package name will result in a ModuleNotFoundError.

fix

Install the unified upstash package and import the client directly from upstash.

# First, ensure the unified package is installed:
# pip install upstash

# Then, correct the import statement:
from upstash import Redis

redis = Redis(url='YOUR_UPSTASH_REDIS_REST_URL', token='YOUR_UPSTASH_REDIS_REST_TOKEN')

error KeyError: 'UPSTASH_REDIS_REST_URL' ↓

cause The Upstash client attempted to initialize by reading required connection environment variables (like URL or Token) that were not set and were not explicitly provided during client initialization.

fix

Set the necessary environment variables in your operating system or pass the url and token parameters directly to the client constructor.

# Option 1: Set environment variables (recommended for production)
# export UPSTASH_REDIS_REST_URL='your_redis_url'
# export UPSTASH_REDIS_REST_TOKEN='your_redis_token'
from upstash import Redis
redis = Redis() # Reads from environment variables by default

# Option 2: Pass directly in code
from upstash import Redis
redis = Redis(url='your_redis_url', token='your_redis_token')

error RuntimeWarning: coroutine 'Redis.get' was never awaited ↓

cause An asynchronous method of the Upstash client (e.g., `Redis.get()`, `Vector.query()`) was called in an `async` function without the `await` keyword, or called in a synchronous context without being run in an event loop.

fix

Ensure all asynchronous client calls are preceded by await within an async def function, and run the main async function using asyncio.run().

import asyncio
from upstash import Redis

async def main():
    redis = Redis(url='YOUR_UPSTASH_REDIS_REST_URL', token='YOUR_UPSTASH_REDIS_REST_TOKEN')
    await redis.set('mykey', 'myvalue') # Correct: using await
    value = await redis.get('mykey')    # Correct: using await
    print(value)
    await redis.close() # Ensure to close the client when done

if __name__ == '__main__':
    asyncio.run(main())

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()

breaking While the separate upstash-redis, upstash-vector, and upstash-qstash packages are being consolidated, the unified 'upstash' package is not yet available for installation on PyPI or for the specified Python environment (python:3.13-alpine). Attempting 'pip install upstash' will result in 'No matching distribution found'. ↓

fix Continue to use 'pip install upstash-redis' (or other specific Upstash SDKs like upstash-vector, upstash-qstash) until the unified 'upstash' package is officially released and available for your platform.

Install

pip install upstash-redis

pip install upstash-vector

pip install upstash-qstash

Install compatibility verified last tested: 2026-05-12

python os / libc variant status wheel install import disk

3.10 alpine (musl) upstash - - - -

3.10 alpine (musl) upstash-qstash - - - -

3.10 alpine (musl) upstash-redis - - 0.27s 71.3M

3.10 alpine (musl) upstash-vector - - - -

3.10 slim (glibc) upstash - - - -

3.10 slim (glibc) upstash-qstash - - - -

3.10 slim (glibc) upstash-redis - - 0.21s 143M

3.10 slim (glibc) upstash-vector - - - -

3.11 alpine (musl) upstash - - - -

3.11 alpine (musl) upstash-qstash - - - -

3.11 alpine (musl) upstash-redis - - 0.42s 78.1M

3.11 alpine (musl) upstash-vector - - - -

3.11 slim (glibc) upstash - - - -

3.11 slim (glibc) upstash-qstash - - - -

3.11 slim (glibc) upstash-redis - - 0.34s 149M

3.11 slim (glibc) upstash-vector - - - -

3.12 alpine (musl) upstash - - - -

3.12 alpine (musl) upstash-qstash - - - -

3.12 alpine (musl) upstash-redis - - 0.59s 69.2M

3.12 alpine (musl) upstash-vector - - - -

3.12 slim (glibc) upstash - - - -

3.12 slim (glibc) upstash-qstash - - - -

3.12 slim (glibc) upstash-redis - - 0.58s 140M

3.12 slim (glibc) upstash-vector - - - -

3.13 alpine (musl) upstash - - - -

3.13 alpine (musl) upstash-qstash - - - -

3.13 alpine (musl) upstash-redis - - 0.60s 65.3M

3.13 alpine (musl) upstash-vector - - - -

3.13 slim (glibc) upstash - - - -

3.13 slim (glibc) upstash-qstash - - - -

3.13 slim (glibc) upstash-redis - - 0.56s 139M

3.13 slim (glibc) upstash-vector - - - -

3.9 alpine (musl) upstash - - - -

3.9 alpine (musl) upstash-qstash - - - -

3.9 alpine (musl) upstash-redis - - 0.24s 70.3M

3.9 alpine (musl) upstash-vector - - - -

3.9 slim (glibc) upstash - - - -

3.9 slim (glibc) upstash-qstash - - - -

3.9 slim (glibc) upstash-redis - - 0.23s 142M

3.9 slim (glibc) upstash-vector - - - -

Imports

Redis
wrong
```
from upstash import Redis
```
correct
```
from upstash_redis import Redis
```
Redis client is imported from upstash_redis, not from the top-level upstash module.
Index
wrong
```
from upstash import Vector
```
correct
```
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 stale last tested: 2026-05-12

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)