Skip to main content

Drop in, configurable, dependency-free progress bars for your Django/Celery applications.

Project description

Celery Progress Bars for Django

Drop in, dependency-free progress bars for your Django/Celery applications.

Super simple setup. Lots of customization available.


Celery Progress Bar demo on Build With Django

Github demo application: build a download progress bar for Django

Starting with Celery can be challenging, eeintech built a complete Django demo application along with a step-by-step guide to get you started on building your own progress bar!


If you haven't already, make sure you have properly set up celery in your project.

Then install this library:

pip install celery-progress



First add celery_progress to your INSTALLED_APPS in

Then add the following url config to your main

from django.urls import re_path, include
re_path(r'^celery-progress/', include('celery_progress.urls')),  # the endpoint is configurable

Recording Progress

In your task you should add something like this:

from celery import shared_task
from celery_progress.backend import ProgressRecorder
import time

def my_task(self, seconds):
    progress_recorder = ProgressRecorder(self)
    result = 0
    for i in range(seconds):
        result += i
        progress_recorder.set_progress(i + 1, seconds)
    return result

You can add an optional progress description like this:

  progress_recorder.set_progress(i + 1, seconds, description='my progress description')

Displaying progress

In the view where you call the task you need to get the task ID like so:

def progress_view(request):
    result = my_task.delay(10)
    return render(request, 'display_progress.html', context={'task_id': result.task_id})

Then in the page you want to show the progress bar you just do the following.

Add the following HTML wherever you want your progress bar to appear:


<div class='progress-wrapper'>
  <div id='progress-bar' class='progress-bar' style="background-color: #68a9ef; width: 0%;">&nbsp;</div>
<div id="progress-bar-message">Waiting for progress to start...</div>

Import the javascript file.


<script src="{% static 'celery_progress/celery_progress.js' %}"></script>

Initialize the progress bar:

// vanilla JS version
document.addEventListener("DOMContentLoaded", function () {
  var progressUrl = "{% url 'celery_progress:task_status' task_id %}";


// JQuery
$(function () {
  var progressUrl = "{% url 'celery_progress:task_status' task_id %}";

Displaying the result of a task

If you'd like you can also display the result of your task on the front end.

To do that follow the steps below. Result handling can also be customized.

Initialize the result block:

This is all that's needed to render the result on the page.


<div id="celery-result"></div>

But more likely you will want to customize how the result looks, which can be done as below:

// JQuery
var progressUrl = "{% url 'celery_progress:task_status' task_id %}";

function customResult(resultElement, result) {
  $( resultElement ).append(
    $('<p>').text('Sum of all seconds is ' + result)

$(function () {
  CeleryProgressBar.initProgressBar(progressUrl, {
    onResult: customResult,


The initProgressBar function takes an optional object of options. The following options are supported:

Option What it does Default Value
pollInterval How frequently to poll for progress (in milliseconds) 500
progressBarId Override the ID used for the progress bar 'progress-bar'
progressBarMessageId Override the ID used for the progress bar message 'progress-bar-message'
progressBarElement Override the element used for the progress bar. If specified, progressBarId will be ignored. document.getElementById(progressBarId)
progressBarMessageElement Override the element used for the progress bar message. If specified, progressBarMessageId will be ignored. document.getElementById(progressBarMessageId)
resultElementId Override the ID used for the result 'celery-result'
resultElement Override the element used for the result. If specified, resultElementId will be ignored. document.getElementById(resultElementId)
onProgress function to call when progress is updated onProgressDefault
onSuccess function to call when progress successfully completes onSuccessDefault
onError function to call on a known error with no specified handler onErrorDefault
onRetry function to call when a task attempts to retry onRetryDefault
onIgnored function to call when a task result is ignored onIgnoredDefault
onTaskError function to call when progress completes with an error onError
onNetworkError function to call on a network error (ignored by WebSocket) onError
onHttpError function to call on a non-200 response (ignored by WebSocket) onError
onDataError function to call on a response that's not JSON or has invalid schema due to a programming error onError
onResult function to call when returned non empty result CeleryProgressBar.onResultDefault
barColors dictionary containing color values for various progress bar states. Colors that are not specified will defer to defaults barColorsDefault

The barColors option allows you to customize the color of each progress bar state by passing a dictionary of key-value pairs of state: #hexcode. The defaults are shown below.

State Hex Code Image Color
success #76ce60 #76ce60
error #dc4f63 #dc4f63
progress #68a9ef #68a9ef
ignored #7a7a7a #7a7a7a

WebSocket Support

Additionally, this library offers WebSocket support using Django Channels courtesy of EJH2.

A working example project leveraging WebSockets is available here.

To use WebSockets, install with pip install celery-progress[websockets,redis] or pip install celery-progress[websockets,rabbitmq] (depending on broker dependencies).

See WebSocketProgressRecorder and websockets.js for details.

Project details

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Files for celery-progress, version 0.1.1
Filename, size File type Python version Upload date Hashes
Filename, size celery_progress-0.1.1-py3-none-any.whl (15.3 kB) File type Wheel Python version py3 Upload date Hashes View
Filename, size celery-progress-0.1.1.tar.gz (12.8 kB) File type Source Python version None Upload date Hashes View

Supported by

AWS AWS Cloud computing Datadog Datadog Monitoring DigiCert DigiCert EV certificate Facebook / Instagram Facebook / Instagram PSF Sponsor Fastly Fastly CDN Google Google Object Storage and Download Analytics Microsoft Microsoft PSF Sponsor Pingdom Pingdom Monitoring Salesforce Salesforce PSF Sponsor Sentry Sentry Error logging StatusPage StatusPage Status page