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": "user@example.com"})

@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

Fit

localqueue is a strong fit for single-host workers, local recovery flows, and durable retries that should stay close to the application. For a broader shape comparison, see docs/compare.md.