You’ve probably noticed that some tasks in your Django app seem to take a long time. For example, maybe sending confirmation emails, resizing images, or processing large data files slows things down.
The good news? You don’t have to sit around waiting. You can hand those tasks off to something else and let your app keep doing its thing. That “something else” is Celery.
Celery lets you run time-consuming tasks in the background while your app stays fast. And if you’re using Django, it’s actually not that hard to plug it in – once you understand how the pieces work together.
In this guide, I’ll walk you through what Celery is, why it’s useful, and exactly how to set it up with Django step by step.
Table Of Contents
What Is Celery and Why Should You Use It in Django?
Imagine you’re running an online shop. Someone places an order. You want to:
Save the order to the database
Send them an invoice by email
Notify your warehouse
Maybe even start printing a shipping label
If your app tries to do all this at once, your user is going to be stuck staring at a loading screen. Instead, what if you only saved the order right away – and passed the rest to Celery to handle in the background?
That’s exactly what Celery does.
It’s a task queue — which just means it runs things later, so your main app doesn’t have to wait. It’s especially helpful for:
Sending emails
Data imports/exports
Running machine learning models
Scraping data
Generating reports
And yeah, it works really well with Django.
How Celery Works (The Simple Version)
Celery is made up of a few parts:
Task producer (your Django app) – This is where you call a task.
Broker (usually Redis) – This is the middleman. It takes the task and holds it until a worker can grab it.
Worker – This is Celery’s background process that grabs tasks from the broker and runs them.
Here’s the flow:
Django app → Redis → Celery Worker → Done ✅
Now let’s actually set this up.
How to Use Celery in Django
1. Install the right packages
You’ll need celery and a message broker. Redis is a popular choice.
pip install celery redis
Also make sure you have Redis running. You can install it locally via Homebrew (brew install redis) or use a Docker container.
If you’re using Docker:
docker run -p 6379:6379 redis
2. Create a celery.py file in your project folder
Let’s say your Django project is called myproject. Inside that same folder (where settings.py is), create a file called celery.py.
<span class="hljs-comment"># myproject/celery.py</span>
<span class="hljs-keyword">import</span> os
<span class="hljs-keyword">from</span> celery <span class="hljs-keyword">import</span> Celery
os.environ.setdefault(<span class="hljs-string">"DJANGO_SETTINGS_MODULE"</span>, <span class="hljs-string">"myproject.settings"</span>)
app = Celery(<span class="hljs-string">"myproject"</span>)
app.config_from_object(<span class="hljs-string">"django.conf:settings"</span>, namespace=<span class="hljs-string">"CELERY"</span>)
app.autodiscover_tasks()
Here’s what’s happening:
os.environ...sets up Django’s settings.Celery("myproject")creates a new Celery app with your project name.app.config_from_object(...)tells Celery to read config from Django’s settings file.autodiscover_tasks()tells Celery to find tasks in your Django apps automatically.
3. Add Celery to __init__.py
Still in your myproject/ folder, open __init__.py and add:
<span class="hljs-keyword">from</span> .celery <span class="hljs-keyword">import</span> app <span class="hljs-keyword">as</span> celery_app
__all__ = (<span class="hljs-string">"celery_app"</span>,)
This makes sure Celery starts with Django.
4. Set the broker URL in your settings
Open settings.py and add:
CELERY_BROKER_URL = <span class="hljs-string">'redis://localhost:6379/0'</span>
This tells Celery to use Redis as the broker.
5. Write your first task
Go to one of your Django apps (say you’ve got an app called shop), and create a file called tasks.py.
<span class="hljs-comment"># shop/tasks.py</span>
<span class="hljs-keyword">from</span> celery <span class="hljs-keyword">import</span> shared_task
<span class="hljs-meta">@shared_task</span>
<span class="hljs-function"><span class="hljs-keyword">def</span> <span class="hljs-title">send_invoice_email</span>(<span class="hljs-params">order_id</span>):</span>
<span class="hljs-comment"># Imagine this sends an email</span>
print(<span class="hljs-string">f"Sending invoice email for order <span class="hljs-subst">{order_id}</span>"</span>)
The @shared_task decorator tells Celery this is a background task.
6. Call the task from your views
Here’s how you’d use it in a Django view:
<span class="hljs-comment"># shop/views.py</span>
<span class="hljs-keyword">from</span> .tasks <span class="hljs-keyword">import</span> send_invoice_email
<span class="hljs-keyword">from</span> django.shortcuts <span class="hljs-keyword">import</span> render
<span class="hljs-function"><span class="hljs-keyword">def</span> <span class="hljs-title">place_order</span>(<span class="hljs-params">request</span>):</span>
<span class="hljs-comment"># pretend this saves an order</span>
order_id = <span class="hljs-number">1234</span> <span class="hljs-comment"># this would come from your model</span>
<span class="hljs-comment"># run the task in the background</span>
send_invoice_email.delay(order_id)
<span class="hljs-keyword">return</span> render(request, <span class="hljs-string">"order_complete.html"</span>)
Notice the .delay() – this is what sends the task to Celery.
7. Run the Celery worker
Now open a terminal and start the worker:
celery -A myproject worker --loglevel=info
You should see the worker start and wait for tasks. When you place an order, it’ll print something like:
<span class="hljs-selector-tag">Sending</span> <span class="hljs-selector-tag">invoice</span> <span class="hljs-selector-tag">email</span> <span class="hljs-selector-tag">for</span> <span class="hljs-selector-tag">order</span> 1234
Optional: Using Django Admin to Monitor Tasks
If you want to monitor task status in the admin, you can use django-celery-results.
pip install django-celery-results
Then update your settings.py:
INSTALLED_APPS += [<span class="hljs-string">"django_celery_results"</span>]
CELERY_RESULT_BACKEND = <span class="hljs-string">"django-db"</span>
Run migrations:
python manage.py migrate
Now Celery will save task results in your database, and you can see them in Django admin.
FAQ
What happens if Redis goes down?
Your tasks won’t be sent or picked up. But once Redis comes back, things should resume.
Can I retry failed tasks?
Yes! Celery supports retries. You can set how many times a task should retry and how often. Example:
<span class="hljs-meta">@shared_task(bind=True, max_retries=3)</span>
<span class="hljs-function"><span class="hljs-keyword">def</span> <span class="hljs-title">risky_task</span>(<span class="hljs-params">self</span>):</span>
<span class="hljs-keyword">try</span>:
<span class="hljs-comment"># Do something risky</span>
<span class="hljs-keyword">pass</span>
<span class="hljs-keyword">except</span> Exception <span class="hljs-keyword">as</span> e:
<span class="hljs-keyword">raise</span> self.retry(exc=e, countdown=<span class="hljs-number">60</span>)
Is Celery the only option?
No. There’s also Django Q, Dramatiq, and Huey. But Celery is the most mature and has the biggest community.
Wrapping It Up
Using Celery in Django doesn’t just speed things up – it also helps improve the experience for your users.
Offloading heavy or slow tasks makes your app feel snappier and more reliable.
Once you get the basics down, you’ll find yourself using it for all kinds of things.
Further Reading and Resources
Source: freeCodeCamp Programming Tutorials: Python, JavaScript, Git & MoreÂ
