queuefy 1.0.3

Asynchronous task queue and scheduler for Python, where one task runs on exactly one worker.

🚀 Project

Queuefy is a task queue and a scheduler that are the same thing.

Everything it does reduces to a single row: a run that is due, which exactly one worker claims. An immediate task, an interval, a fixed datetime and a cron expression differ only in when the next run is written, and in nothing else.

That is why there is no separate scheduler process, no broker and no leader election. Start it on ten machines and the nightly report still runs once.

✨ Features

• Run a task now, off the request that asked for it
• Run a task every N seconds
• Run a task once, at a stated date and time
• Run a task on a cron expression
• One run on exactly one worker, however many processes, workers and machines
• Retries with fixed, linear, exponential and jittered policies
• Timeouts, heartbeats and recovery of what a dead worker was holding
• Named queues and priorities
• Lifecycle hooks for auditing, metrics and alerting
• Pluggable stores: PostgreSQL 14+, MySQL 8.0+, Redis 7+, SQLite and memory
• Survives a kill: what a dead worker held comes back, and a schedule resumes where it stopped
• No dependencies in the core
• 100% branch coverage: one contract against every store, plus multi-worker, multi-machine, everyday, disaster and interrupted-call suites

📦 Install

pip install "queuefy[sqlalchemy]"

Or with Redis:

pip install "queuefy[redis]"

🧭 The four ways to ask for work

💡 How to use

import asyncio

from sqlalchemy.ext.asyncio import create_async_engine

from queuefy.app import Queuefy
from queuefy.store.sqlalchemy import SqlAlchemyStore
from queuefy.worker import Worker

app = Queuefy(SqlAlchemyStore(create_async_engine("sqlite+aiosqlite:///app.db")))


@app.task("send_email", max_attempts=5, timeout=30)
async def send_email(to: str, subject: str):
    ...


@app.task("nightly_report", cron="0 4 * * *")
async def nightly_report():
    ...


async def main():
    await app.setup()
    await app.enqueue("send_email", to="reader@example.com", subject="Welcome")
    await Worker(app, concurrency=8).run()


asyncio.run(main())

🧱 The words it uses

Three of them, and each means one thing:

📚 Documentation

• Getting started
• Tasks — the four kinds, and what a name means
• Workers — concurrency, leases and many machines
• Retries and failures — policies, timeouts, permanent errors
• Hooks — being told about every run
• Stores — SQLAlchemy, Redis, memory, and writing your own
• Frameworks — the rule that covers all of them, and what a handler may touch
  • FastAPI — a worker on the lifespan, and a handler that uses the session
  • Django — a management command, the ORM from a handler, and transactions
  • Flask — a worker in its own process, and the application context
• Contribution — how to help

☕ Buy me a coffee

Support the continuous development of this project.

📄 License

MIT

Copyright (c) 2026, Paulo Coutinho