Upstash QStash Python SDK

3.4.0 verified Mon Apr 27 auth: no python

Python SDK for Upstash QStash, a message queue and workflow orchestration service for serverless applications. v3.4.0 removes deprecated LLMs support and adds new QStash features. Regular releases.

pip install qstash

Common errors

error ModuleNotFoundError: No module named 'qstash.client' ↓

cause Incorrect import path for QStashClient.

fix

Use from qstash import QStashClient instead.

error ImportError: cannot import name 'QStash' from 'qstash' ↓

cause The class was renamed; older code uses `QStash`.

fix

Use QStashClient instead of QStash. Import from qstash.

error qstash.errors.QStashError: Authentication failed ↓

cause Missing or invalid QStash token.

fix

Set the environment variable QSTASH_TOKEN properly. Obtain from Upstash dashboard under QStash > Settings.

Warnings

breaking In v3.0.0, the entire LLM chat completion support was removed. Any code using `client.llm.chat` or similar will break. ↓

fix Migrate to a separate LLM SDK (e.g., OpenAI) and remove usage of deprecated methods.

deprecated The `delay` and `not_before` parameters in `enqueue` are removed in v2.0.1+. Use `schedule` or manual delay instead. ↓

fix Remove these parameters; if you need delayed execution, use schedules or set a later `not_before` via the API's `schedule` method.

gotcha Client initialization can fail silently if the token is missing; always validate `QSTASH_TOKEN` is set. ↓

fix Check that the environment variable exists before creating the client: `assert os.environ.get('QSTASH_TOKEN'), 'Missing QStash token'`

gotcha Async client requires an event loop; using it in synchronous context will raise RuntimeError. ↓

fix Ensure you use `await` inside an async function or run with `asyncio.run()`. Example: `asyncio.run(main())`.

Imports

QStashClient

wrong

from qstash.client import QStashClient

correct

from qstash import QStashClient

The correct import is directly from 'qstash'.

QStashAsyncClient
```
from qstash import QStashAsyncClient
```

Quickstart

Initialize client with your QStash token (from Upstash console) and publish a message.

import os
from qstash import QStashClient

client = QStashClient(token=os.environ.get('QSTASH_TOKEN', ''))
response = client.publish(url="https://example.com/api", body="Hello, QStash!")
print(response)