celery-progress

What it is and what it does

Celery Progress is a Django integration library that bridges Celery background tasks and the frontend by providing real-time progress bar updates. It works by recording task progress on the backend using a ProgressRecorder wrapper and polling (or streaming via WebSocket) task status to the frontend, where a JavaScript component renders a visual progress bar. The library is dependency-free at runtime, requiring only that you have Django and Celery already configured.

You add it to Django's INSTALLED_APPS, wire up its URL endpoints, wrap your Celery tasks with ProgressRecorder calls, and initialize the frontend JavaScript with a task ID. The library handles polling intervals, customizable colors, messages, result display, and experimental support for Celery groups. It is designed for straightforward setup with optional customization of progress bar appearance and behavior.

Use it for:

• Display a real-time progress bar while a long-running Celery task (e.g., file export, data processing) executes in the background.
• Show task status updates and final results to users without page reloads, improving perceived responsiveness of async operations.
• Track progress of multiple related tasks using Celery groups with a single unified progress indicator.
• Customize progress bar colors, polling intervals, and callback handlers to match application UI and error-handling requirements.
• Stream live task updates via WebSocket using Django Channels for lower-latency progress notifications in real-time applications.

Worth the install?

AI-flagged interpretation of the facts on this page — verify before relying

Provides drop-in progress bars for Django views that display real-time updates from Celery background tasks, with optional WebSocket support via Django Channels.

Yes, if you are building a Django application with Celery tasks and need a simple, zero-dependency progress bar for the frontend. The library is stable and well-suited for standard use cases. However, note that maintenance is dormant (last update 561 days ago); verify compatibility with your specific Django and Celery versions before relying on it for new projects, and be prepared to maintain a fork if breaking changes occur in future Django releases.

Install

celery-progress on PyPI

pip install celery-progress

uv add celery-progress

poetry add celery-progress

Installing celery-progress

Before you install

Low friction installation with no runtime dependencies. Dormant maintenance status (last commit 2025-01-30, no updates in 561 days), but the package is stable and archived repository shows active development ceased rather than abandonment.

License in practice

MIT License permits commercial and private use with minimal restrictions—you may use, modify, and distribute the package freely provided you retain the license notice.

Quickstart

pip install celery-progress

# In Django settings.py:
INSTALLED_APPS = [..., 'celery_progress']

# In urls.py:
path('celery-progress/', include('celery_progress.urls'))

# In task:
from celery_progress.backend import ProgressRecorder
@shared_task(bind=True)
def my_task(self):
    progress_recorder = ProgressRecorder(self)
    progress_recorder.set_progress(1, 10)

# In template:
<script src="{% static 'celery_progress/celery_progress.js' %}"></script>
<script>
CeleryProgressBar.initProgressBar("{% url 'celery_progress:task_status' task_id %}");
</script>

Requires Django and Celery to be already set up in your project; WebSocket support requires Django Channels.

Verify before relying

• Whether the package works with Django versions beyond 5.1 or Python versions beyond 3.12.
• Current state of WebSocket support implementation and any known limitations.
• Whether dormant status indicates the package is sufficiently stable or if active maintenance is needed for new Django/Celery releases.

Package facts

Evidence: celery_progress-0.5-py3-none-any.whl

Tags

More WWW/HTTP packages