Configuration

Pass one QueueConfig to the plugin:

from litestar_queues import QueueConfig, QueuePlugin, WorkerConfig

queue_plugin = QueuePlugin(
    config=QueueConfig(
        queue_backend="memory",
        execution_backend="local",
        worker=WorkerConfig(placement="asgi"),
    )
)

Use this page as a map; each linked guide owns the detailed behavior.

Concern	Settings	Guide
Persistence	queue_backend	Choose backends
Runtime identity	namespace	Runtime namespace
Execution placement	execution_backend	Choose backends
Worker placement	worker.placement	Run workers
Claiming and concurrency	worker.batch_size, worker.max_concurrency	Run workers
Idle waiting	worker.poll_interval, worker.poll_backoff_max, worker.poll_backoff_multiplier, worker.poll_jitter	Pick up new work faster
Heartbeats and recovery	worker.heartbeat_interval, worker.heartbeat_miss_threshold, worker.stale_after, worker.stale_check_interval	Recover work whose worker died
Queued task expiration	worker.expiry_check_interval, task expires_in, enqueue expires_in / expires_at	Task options
Shutdown	worker.graceful_shutdown_timeout, worker.final_cancel_timeout	Run workers
Task discovery	task_modules	Define and enqueue
Argument identity size guard	max_argument_identity_bytes	Task options
Schedules	initialize_schedules, scheduler_canary_task	Schedules
Bounded maintenance	maintenance	Queue maintenance
Events	events.delivery, events.history, events.stream	Task events, Event history, SSE and WebSockets
Observability	observability	Observability
External dependencies	task_dependency_resolver, task_dependency_provider	Task Dependencies

External dependencies

QueueConfig.task_dependency_resolver and QueueConfig.task_dependency_provider allow injecting external resources into queued tasks. You may configure at most one of these hooks; configuring both raises a QueueConfigurationError. See Task Dependencies for details.

Adaptive polling

Polling-only workers reduce idle backend traffic by increasing their wait after empty cycles. The default grows from 0.1 seconds to at most 30 seconds, applies bounded jitter, and resets immediately when work or a native notification arrives:

worker = WorkerConfig(
    poll_interval=0.1,
    poll_backoff_max=10.0,
    poll_backoff_multiplier=2.0,
    poll_jitter=0.15,
)

For polling-only backends, poll_backoff_max is the worst-case discovery latency for newly inserted work. Native notifications still wake immediately, and known scheduled or retry work clamps the wait to its due time. Set poll_backoff_max=None to retain fixed-interval polling when latency matters more than idle load.

Validation requires poll_interval > 0, poll_backoff_max >= poll_interval when a maximum is set, poll_backoff_multiplier >= 1.0, and 0.0 <= poll_jitter <= 1.0. The stored interval resets to poll_interval on startup, claimed work, a native notification, and recoverable backend or listener errors.

Defaults favor zero-configuration background execution: ephemeral SQLite, local execution, and one server-owned worker started by litestar run. Choose persistent storage and placement explicitly for durable deployments.

Runtime namespace

namespace renames every runtime name the package owns — loggers, metrics, channels, keys, and generated routes — from a single setting. Most applications leave it alone; see Runtime namespace when you need to change it.