celery-manager

A dashboard and control API for Celery background tasks — for any Django, Flask, or FastAPI project that already uses Celery.

Documentation · Quickstart · PyPI

Point it at your existing Celery app and you get a web UI and a REST API to see what your tasks are doing, act on them, and — the feature this project exists for — pause or cancel a single future occurrence of a periodic task without touching your beat schedule or restarting anything.

Production adoption: the 0.2 guide covers external schedulers, OIDC, dispatch policies, bounded logs/results and storage isolation. The requirements roadmap tracks the real-project review and follow-ups.

What you get

• Task visibility — every task run (decorated or not) with status, args, worker, queue, timings, exceptions, and full tracebacks.
• Full run history — browse past runs beyond the newest page, search by task name, task ID, or args/kwargs content, and filter by status and date range.
• Live progress — call celery_manager.report_progress(current, total, message) inside a task body and watch the bar move, with elapsed time and a projected finish while the task is still running.
• Log capture — logging output from inside a task body (and print() too, in a real worker — see why), attached to that run and readable in the dashboard.
• Control — cancel/terminate, retry (optionally with edited args), bulk retry, bulk cancel, and start any registered task from a searchable picker with prefilled arguments. Retries keep their lineage.
• Workflows — chains, groups and chords shown as a collapsible tree on every run that belongs to one.
• Per-occurrence schedule control — skip or cancel one upcoming run of a periodic task, or pause a whole schedule indefinitely or until a set time; it resumes from the current time, with no catch-up.
• Insights — runs, success rate and p50/p95 runtime over 1h–30d, a page per task, and failures grouped by exception signature with retry-all.
• Workers and queues — live worker state, pool grow/shrink, queue consume/cancel, shutdown, runtime rate limits, broker queue depth and purge.
• Shareable views — filters live in the URL, saved views, and CSV/JSON export of any filtered list.
• Live updates — the dashboard follows changes from the events listener, workers and other API processes within about a second.
• Schema migrations — Alembic migrations ship in the package and run at startup, or as a deploy step with celery-manager migrate.
• Audit log — who did what, when, for every control action.
• Light and dark themes — an explicit per-user choice, not just whatever the OS says.
• Brandable — set the product name, accent colour, and logo from a settings screen; it applies for everyone on the deployment.
• Built-in auth — bcrypt-hashed users and signed session cookies.
• Roles — viewer (read-only), operator (day-to-day controls) and admin (purge, worker shutdown, settings), enforced on the server.
• No Node toolchain required — the React dashboard ships prebuilt inside the Python package.

Install

celery-manager is an alpha, so pass --pre to pip:

pip install --pre celery-manager

With extras:

pip install --pre "celery-manager[standalone]"   # adds uvicorn
pip install --pre "celery-manager[flask]"        # adds Flask and a2wsgi

Alternatively, install a tagged release straight from git:

pip install "git+https://github.com/Pythondeveloper6/[email protected]"

(Extras with git: "celery-manager[standalone] @ git+https://github.com/Pythondeveloper6/[email protected]".)

Optional extras:

• standalone — pulls in uvicorn, to run the dashboard on its own rather than mounting it into an ASGI app you already serve.
• flask — pulls in Flask and a2wsgi, to mount the dashboard in a Flask (WSGI) app; see Integrating with your app.

Wire it up

celery-manager runs in two places, and both need configuring — this is the step most easily missed:

from celery_manager.config import CeleryManagerConfig

config = CeleryManagerConfig(
    celery_app=your_celery_app,
    db_url="sqlite:///celery_manager.db",   # any SQLAlchemy URL
    secret_key="a-real-secret-in-production",
)

1. The dashboard process — build the ASGI app and serve or mount it:

from celery_manager.api.app import create_app

app, _ = create_app(config)   # then: uvicorn your_module:app

2. The Celery worker process — where @track-decorated tasks actually run:

import celery_manager

celery_manager.setup(config)   # at import time, in your tasks module

@app.task(bind=True)
@celery_manager.track(schedule_name="send-report-every-2-hours")
def send_report(self):
    ...

For per-occurrence skips, run beat with celery-manager's scheduler. It tags each firing with its scheduled time, so a skip hits exactly that run, however late it starts, and never a manual .delay():

celery -A your_module beat -S celery_manager.beat:Scheduler

Then run the events listener alongside your worker and beat, so the dashboard sees every task rather than only the decorated ones:

celery-manager events --celery-app your_module:your_celery_app \
                      --db-url sqlite:///celery_manager.db

The listener sees nothing unless workers emit events: set worker_send_task_events = True and task_send_sent_event = True (or run the worker with -E). See Required Celery settings.

Two things that stop people on a first run, both covered in the Quickstart: there is no default account, so you have to create one (celery-manager create-user admin --role admin --db-url ...); and on plain HTTP you need cookie_secure=False, or you will log in successfully and then immediately appear logged out.

Documentation

Full documentation is at https://pythondeveloper6.github.io/celery-manager/ (source in docs/, an MkDocs Material site — run mkdocs serve after pip install -e ".[docs]"):

• Features — everything it does, in plain words.
• Quickstart — install through first sign-in.
• The @track decorator — wiring, skip/cancel, logs.
• Live progress — reporting progress from inside a task.
• REST API — every endpoint and payload.
• Dashboard — the screens and what they do.
• Insights — trends, per-task pages and grouped failures.
• Workers and rate limits — live worker state and controls.
• Queues, purge and bulk cancel — broker depth and clean-up.
• Configuration — every config field, the schema and upgrade story, and production notes.
• Working on celery-manager — running the tests, building the docs, and rebuilding the committed dashboard bundle.

Changes between versions — including what breaks for development builds — are in CHANGELOG.md.

A complete runnable Django example is in examples/django_demo/.

Roadmap

Shipped in 0.1.0a5: alerts, missed-run detection, Prometheus/OpenTelemetry metrics, sign-in with your app's users, user management in the dashboard, editing schedules from the UI, maintenance windows, a dead-letter view and data retention; and for Redis and RabbitMQ: broker health, queue wait time and depth history, delayed and stuck tasks, browsing waiting messages, and RabbitMQ management and dead-letter queues. Read the roadmap →

Requirements

Python 3.10+, Celery 5.x. Storage defaults to SQLite with zero configuration and swaps to Postgres/MySQL/anything SQLAlchemy supports via db_url.

Status

This is an alpha, 0.1.0a5. It is feature-complete for the v1 scope, but APIs may change before 0.1.0. See plan.md for the implementation history and the backlog of known gaps and planned follow-ups.

License

MIT — see LICENSE.