Task queues, workers, schedules, realtime event streams, and storage/execution backends for Litestar.
Quickstart · Architecture · Storage Backends · Execution & Operations · Events & Streams · API Reference
litestar-queues decouples authoritative task storage (BaseQueueBackend) from execution delivery (BaseExecutionBackend). Persist tasks, retries, uniqueness reservations, and event history in SQLSpec (PostgreSQL, MySQL, MariaDB, SQLite, DuckDB, CockroachDB, Spanner, Oracle, SQL Server), Advanced Alchemy, Redis, or Valkey while dispatching execution across local workers, Google Cloud Tasks, Google Cloud Run Jobs, Pub/Sub, SQS, RabbitMQ, or Kafka using an ID-only wire payload ({"version": 1, "task_id": "<uuid>"}).
Install
uv add litestar-queues
Add optional extras for your storage or execution backend (sqlspec, advanced-alchemy, redis, valkey, cloud-tasks, cloudrun, pubsub, sqs, rabbitmq, kafka, otel, prometheus).
Quickstart
from uuid import UUID
from litestar import Litestar, get, post
from litestar.di import NamedDependency
from litestar.exceptions import NotFoundException
from litestar.params import FromPath, FromQuery
from litestar_queues import QueueConfig, QueuePlugin, QueueService, task
@task(queue="reports")
async def render_report(report_id: str, requested_by: str) -> dict[str, str]:
"""Render an analytics report in the background."""
return {"report_id": report_id, "requested_by": requested_by, "status": "ready"}
@post("/reports/{report_id:str}")
async def start_report(
report_id: FromPath[str],
queue_service: NamedDependency[QueueService],
requested_by: FromQuery[str] = "team@example.com",
) -> dict[str, str]:
"""Enqueue a background report job and return its tracking ID."""
handle = await queue_service.enqueue(render_report, report_id, requested_by=requested_by)
return {"task_id": str(handle.id), "status": handle.status or "pending"}
@get("/tasks/{task_id:uuid}")
async def get_report_status(task_id: FromPath[UUID], queue_service: NamedDependency[QueueService]) -> dict[str, object]:
"""Inspect the status and return value of a queued task."""
record = await queue_service.get_task(task_id)
if record is None:
raise NotFoundException(detail=f"Task {task_id} not found")
return {
"task_id": str(record.id),
"status": record.status,
"is_terminal": record.is_terminal,
"result": record.result,
}
app = Litestar(route_handlers=[start_report, get_report_status], plugins=[QueuePlugin(config=QueueConfig())])
Start the server and its supervised worker process:
LITESTAR_APP=app:app uv run litestar run --reload
Enqueue a report job and inspect its status:
curl -X POST http://127.0.0.1:8000/reports/q3-revenue
curl http://127.0.0.1:8000/tasks/<task_id>
Capabilities
| Area | Highlights |
|---|---|
| Storage Backends | Zero-config EphemeralQueueBackend (WAL SQLite), InMemoryQueueBackend, SQLSpecQueueBackend (9+ relational databases & third-party adapters), SQLAlchemyBackend (Advanced Alchemy), RedisQueueBackend, and ValkeyQueueBackend. |
| Execution & Workers | WorkerConfig(placement="server" | "asgi" | "external"), multi-backend routing (QueueConfig.execution_backends), Google Cloud Tasks push callbacks (CloudTasksOIDCGuard), Cloud Run Jobs, Pub/Sub, SQS, RabbitMQ, and Kafka. |
| Tasks & Schedules | Priority queues, retries with exponential/jittered backoff, argument-identity uniqueness & forever reservations, cooperative & remote cancellation, cron/interval ScheduleConfig, and attempt-scoped TaskDependencyProvider. |
| Events & Observability | Live SSE & WebSocket event streams (EventStreamConfig), durable event history (EventHistoryConfig, QueueEventQuery, EventHistoryExtraColumn), and low-cardinality OpenTelemetry, Prometheus, and SQLCommenter telemetry (ObservabilityConfig). |
Documentation
- Getting Started & Installation
- Core Concepts & Guides
- Storage Backends (SQLSpec, Advanced Alchemy, Redis, Valkey)
- Execution Backends, Bounded Maintenance & CLI
- Task Events, Realtime Streams, History & Observability
- Architecture & Runnable Examples
- API & CLI Reference
Contributing & License
Run make install, make test-unit, make lint, and make docs before submitting changes; see the Contributing & Testing guide for details. litestar-queues supports Python 3.11 through 3.15 and is distributed under the MIT License.
Metadata
Release files for litestar-queues 0.14.0
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| litestar_queues-0.14.0.tar.gz | 1.3 MB | With provenance | Details for litestar_queues-0.14.0.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| litestar_queues-0.14.0-py3-none-any.whl | Python 3 | none | any | Details for litestar_queues-0.14.0-py3-none-any.whl |
Total release size: 1.7 MB
Release files / litestar_queues-0.14.0.tar.gz
| Download URL | litestar_queues-0.14.0.tar.gz |
|---|---|
| Size | 1.3 MB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
f3e3d353e445b6dcf23cbe95166591b2015b12889aa1aa9d9921f758525344d1
|
|
BLAKE2b-256 checksum How to use checksums |
78ac263d73d6126b733358a857394dfb2d0fccbcd31a706f33f72825a5d8da31
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Nov 3, 2026.
Transparency logRelease files / litestar_queues-0.14.0-py3-none-any.whl
| Download URL | litestar_queues-0.14.0-py3-none-any.whl |
|---|---|
| Size | 418.0 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
334358bc008d28b5f4f05515cccdd71239b6dcf55037dd4dc34e361b8d5aa468
|
|
BLAKE2b-256 checksum How to use checksums |
5193d944f1348c07c871583a9228114ea6517afd7c93c8a831d186e1e6b51538
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Nov 3, 2026.
Transparency logSecurity for litestar-queues 0.14.0
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
Full provenance
Both files in this release have been uploaded with provenance metadata.
Attestation for litestar_queues-0.14.0.tar.gz
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Nov 3, 2026.
Transparency logA note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.