Registry / workflow / celery-progress

celery-progress

JSON →
library0.5pypypiunverified

Celery Progress (celery-progress) is a Python library that provides drop-in, configurable, dependency-free progress bars for Django/Celery applications. It enables real-time progress updates for long-running asynchronous tasks directly in the web UI. Currently at version 0.5, it is actively maintained and offers simple integration with Django's URL routing and Celery's task management, including support for group results.

pip install celery-progress
INSTALL
IMPORT
SIG · CELERY-PROGRESS
C
celery-progress
workflowpythonv0.5
Install
3.1s avg
Import
Disk
72MB
Pass rate
10/ 10
Env Coverage10 / 10
glibc
3.93.13
musl
3.93.13
Install & Compatibility
Where this runs
tested against v0.5 · pip install
no network on importno background threads
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
musl
py 3.103.960 runs
installs and imports cleanly · install 0.0s · import 0.000s · 72.7MB
glibc
py 3.103.960 runs
installs and imports cleanly · install 3.1s · import 0.000s · 74MB
72MB installed
● package 72MB
Code
Verified usage

Verified import paths — ran on the pinned version, not inferred.

ProgressRecorder
from celery_progress.recorder import ProgressRecorder
from celery_progress.backend import ProgressRecorder

To use `celery-progress`, first ensure Celery and Django are configured with a result backend (e.g., Redis). Add `celery_progress` to `INSTALLED_APPS` and include its URL patterns using `django.urls.path`. In your Celery task, import `ProgressRecorder`, instantiate it with `self` (from `bind=True`), and call `set_progress(current, total, description)` to update the state. In a Django view, call your task with `.delay()` to get the `task_id`, then pass this `task_id` to your template. In the frontend HTML, include the `celery_progress.js` static file and initialize `CeleryProgressBar` with the task status URL. The `onSuccess` callback can be used to handle task completion and display results.

import os import time from celery import shared_task from celery_progress.backend import ProgressRecorder # settings.py # INSTALLED_APPS = [ # ..., # 'celery_progress', # ] # CELERY_BROKER_URL = os.environ.get('CELERY_BROKER_URL', 'redis://localhost:6379/0') # CELERY_RESULT_BACKEND = os.environ.get('CELERY_RESULT_BACKEND', 'redis://localhost:6379/0') # urls.py (in your project's main urls.py) # from django.urls import path, include # urlpatterns = [ # ..., # path('celery-progress/', include('celery_progress.urls')), # ] @shared_task(bind=True) def my_long_task(self, total_steps): progress_recorder = ProgressRecorder(self) for i in range(total_steps): time.sleep(1) # Simulate work progress_recorder.set_progress(i + 1, total_steps, description=f'Step {i+1} of {total_steps}') return 'Task Completed!' # views.py # from django.shortcuts import render # from .tasks import my_long_task # def start_task_view(request): # if request.method == 'POST': # result = my_long_task.delay(10) # Start the task asynchronously # return render(request, 'task_progress.html', {'task_id': result.task_id}) # return render(request, 'start_task.html') # task_progress.html (template) # <div class='progress-wrapper'> # <div id='progress-bar' class='progress-bar' style="background-color: #68a9ef; width: 0%;">&nbsp;</div> # </div> # <div id="progress-bar-message">Waiting for progress to start...</div> # <div id="celery-result"></div> # # {% load static %} # <script src="{% static 'celery_progress/celery_progress.js' %}"></script> # <script> # document.addEventListener("DOMContentLoaded", function() { # var progressUrl = "{% url 'celery_progress:task_status' task_id %}"; # CeleryProgressBar.initProgressBar(progressUrl, { # onSuccess: function(result, elm) { # document.getElementById('celery-result').innerHTML = 'Result: ' + result; # } # }); # }); # </script>
Debug
Known issues
breakingChanged URL pattern definition for Django versions >= 4.0. The library switched from `django.conf.urls.url` to `django.urls.re_path`.
fix
Update your project's `urls.py` to use `path('celery-progress/', include('celery_progress.urls'))` or `re_path(r'^celery-progress/', include('celery_progress.urls'))` instead of `url()` for compatibility with Django 4+.
affects: >=0.2
gotchaThe default `get_progress` endpoint for `celery-progress` is publicly accessible, allowing anyone to query task statuses by `task_id`. This can pose a security risk.
fix
Wrap the `celery_progress.views.get_progress` view in your own Django view with appropriate permission checks (e.g., `@login_required` or custom permissions) and route to your protected view instead of the default `celery_progress.urls`.
affects: All versions
gotchaCelery requires a properly configured result backend (e.g., Redis or RabbitMQ) for `celery-progress` to function correctly. Without it, task progress and results cannot be retrieved.
fix
Ensure `CELERY_RESULT_BACKEND` is explicitly set in your Django settings. For example, `CELERY_RESULT_BACKEND = 'redis://localhost:6379/0'` or `CELERY_RESULT_BACKEND = 'rpc://'` (with caution).
affects: All versions
gotchaWhen using Celery's RPC result backend (default in some setups), `celery-progress` may fail to pull all task states for multiple concurrent tasks because the RPC backend only allows results to be retrieved once by the client that initiated the task.
fix
For applications with multiple concurrent tasks or needing persistent result storage, use a persistent result backend like Redis (`redis://`) or a database backend (`db+postgresql://`).
affects: All versions
Upgrade
Version history
0.5latest on PyPI · released Jan 30, 2025
Audit
Dependencies
djangorequiredRequired for web integration, URL routing, and templating. The library is built specifically for Django applications.
celeryrequiredCore dependency for asynchronous task execution and management. This library extends Celery's functionality.
redisoptionalCommonly used as both Celery broker and result backend, which is essential for `celery-progress` to track task states. RabbitMQ is an alternative.
rabbitmqoptionalAlternative to Redis as a Celery broker and result backend. Essential for `celery-progress` to track task states.
Agent activity
22 hits · last 30 days
node
20
OpenAI (training)
1
Resources
celery-progress — pip install celery-progress · libregistry