localqueue 0.5.0

Durable local queues for Python, with persistent retry state powered by Tenacity.

localqueue

localqueue is a small durable queue for one machine. It stores work on the local filesystem by default and keeps retry state with Tenacity.

Use it when the work can stay local and you want one of these outcomes:

• accept work now and perform the side effect later on the same machine
• inspect failed jobs and replay them from the terminal
• keep retry budgets across process restarts without adding a broker

It fits scripts, CLI tools, cron jobs, and small Python workers that share one local store.

localqueue queue exec emails -- python scripts/send_email.py

from localqueue import PersistentQueue, QoS, QueueSpec, persistent_worker

spec = (
    QueueSpec("emails")
    .with_qos(QoS.AT_LEAST_ONCE)
    .with_retry(max_retries=3)
    .with_dead_letter_on_failure(False)
    .with_release_delay(30.0)
    .with_circuit_breaker(threshold=3, cooldown=30.0)
    .with_dead_letter_queue()
)

queue = PersistentQueue(spec=spec)
worker_config = queue.build_worker_config()
queue.put({"to": "[e-mail]"})

@persistent_worker(queue, config=worker_config)
def send_email(job: dict[str, str]) -> None:
    deliver(job["to"])

Reuse same config for multiple queue names with with_name(...), or override the spec name directly in the constructor:

base = QueueSpec("orders.base").with_qos(QoS.AT_LEAST_ONCE)

payments = PersistentQueue(spec=base.with_name("orders.payment"))
refunds = PersistentQueue("orders.refund", spec=base)

Full docs live at brunoportis.github.io/localqueue. The source docs are in docs/.

Container examples live in examples/docker-compose/. Step-by-step reproducible docs for them live in docs/examples.md.

Start with docs/use-cases.md if you want the shortest path to deciding whether the project fits your workflow.

For development and release workflow details, see docs/develop.md.

Install

pip install localqueue

For the CLI:

pip install "localqueue[cli]"

For the optional LMDB backend:

pip install "localqueue[lmdb]"

Running with Docker

The image is also published on GitHub Container Registry:

docker pull ghcr.io/brunoportis/localqueue:latest
docker run --rm ghcr.io/brunoportis/localqueue:latest --help

When not to use

localqueue is not a distributed broker. If you need multi-host coordination, high write concurrency, managed retention, or strict cross-service ordering, use a system designed for that operating model.