Celery Missing Import in Documentation in Django tutorial

The Fix

pip install celery==5.5.0

Based on closed celery/celery issue #9098 · PR/commit linked

Production note: Most teams hit this during upgrades or environment changes. Roll out with a canary and smoke critical endpoints (health, OpenAPI/docs) before 100%.

Jump to Verify Open PR/Commit

@@ -298,3 +298,4 @@ Jeremy Z. Othieno 2023/07/27
 Andy Zickler, 2024/01/18
 Johannes Faigle, 2024/06/18
+Giovanni Giampauli, 2024/06/26
diff --git a/examples/django/proj/celery.py b/examples/django/proj/celery.py
index ec3354dcdf3..182da54fb55 100644

repro.py

import os

from celery import Celery

# Set the default Django settings module for the 'celery' program.
os.environ.setdefault('DJANGO_SETTINGS_MODULE', 'proj.settings')

app = Celery('proj')

# Using a string here means the worker doesn't have to serialize
# the configuration object to child processes.
# - namespace='CELERY' means all celery-related configuration keys
#   should have a `CELERY_` prefix.
app.config_from_object('django.conf:settings', namespace='CELERY')

# Load task modules from all registered Django apps.
app.autodiscover_tasks()


@app.task(bind=True, ignore_result=True)
def debug_task(self):
    print(f'Request: {self.request!r}')

verify

Re-run the minimal reproduction on your broken version, then apply the fix and re-run.

fix.md

Option A — Upgrade to fixed release\npip install celery==5.5.0\nWhen NOT to use: This fix is not applicable if the import is already present in the code.\n\n

Why This Fix Works in Production

Trigger: Missing Import in Documentation in Django tutorial
Mechanism: The documentation lacked an import statement necessary for task discovery in Django
Why the fix works: Added a missing import in the Django tutorial documentation to ensure proper task discovery. (first fixed release: 5.5.0).

Production impact:

If left unfixed, the same config can fail only in production (env differences), causing startup failures or partial feature outages.

Why This Breaks in Prod

The documentation lacked an import statement necessary for task discovery in Django
Production symptom (often without a traceback): Missing Import in Documentation in Django tutorial

Proof / Evidence

GitHub issue: #9098
Fix PR: https://github.com/celery/celery/pull/9099
First fixed release: 5.5.0
Reproduced locally: No (not executed)
Last verified: 2026-02-09
Confidence: 0.85
Did this fix it?: Yes (upstream fix exists)
Own content ratio: 0.46

Verified Execution

We executed the runnable minimal repro in a temporary environment and captured exit codes + logs.

Status: PASS
Ran: 2026-02-11T16:52:29Z
Package: celery
Fixed: 5.5.0
Mode: fixed_only
Outcome: ok

Logs

affected (exit=None)

fixed (exit=0)

\n\n[stderr]\n/tmp/ss-exec-95mddanf/site/celery/fixups/django.py:57: FixupWarning: Environment variable DJANGO_SETTINGS_MODULE is defined
but Django isn't installed.  Won't apply Django fix-ups!

  warnings.warn(FixupWarning(ERR_NOT_INSTALLED))

Discussion

High-signal excerpts from the issue thread (symptoms, repros, edge-cases).

Jump to Sources Open on GitHub

“**Description:** The code snippet provided in the documentation needs an additional import to function correctly. Without this import, the code does not raise any errors, but it fails to discover @shared_tasks in other files. **Link to Docu”

Issue thread · issue description · source

Failure Signature (Search String)

Missing Import in Documentation in Django tutorial
The code snippet provided in the documentation needs an additional import to function correctly. Without this import, the code does not raise any errors, but it fails to discover

Copy-friendly signature

signature.txt

Failure Signature
-----------------
Missing Import in Documentation in Django tutorial
The code snippet provided in the documentation needs an additional import to function correctly. Without this import, the code does not raise any errors, but it fails to discover `@shared_task`s in other files.

Error Message

Signature-only (no traceback captured)

error.txt

Error Message
-------------
Missing Import in Documentation in Django tutorial
The code snippet provided in the documentation needs an additional import to function correctly. Without this import, the code does not raise any errors, but it fails to discover `@shared_task`s in other files.

Minimal Reproduction

repro.py

import os

from celery import Celery

# Set the default Django settings module for the 'celery' program.
os.environ.setdefault('DJANGO_SETTINGS_MODULE', 'proj.settings')

app = Celery('proj')

# Using a string here means the worker doesn't have to serialize
# the configuration object to child processes.
# - namespace='CELERY' means all celery-related configuration keys
#   should have a `CELERY_` prefix.
app.config_from_object('django.conf:settings', namespace='CELERY')

# Load task modules from all registered Django apps.
app.autodiscover_tasks()


@app.task(bind=True, ignore_result=True)
def debug_task(self):
    print(f'Request: {self.request!r}')

What Broke

Tasks marked with @shared_task were not discovered, leading to silent failures.

Why It Broke

The documentation lacked an import statement necessary for task discovery in Django

Fix Options (Details)

Option A — Upgrade to fixed release Safe default (recommended)

pip install celery==5.5.0

When NOT to use: This fix is not applicable if the import is already present in the code.

Use when you can deploy the upstream fix. It is usually lower-risk than long-lived workarounds.

Fix reference: https://github.com/celery/celery/pull/9099

First fixed release: 5.5.0

Last verified: 2026-02-09. Validate in your environment.

When NOT to Use This Fix

This fix is not applicable if the import is already present in the code.

Verify Fix

verify

Re-run the minimal reproduction on your broken version, then apply the fix and re-run.

Did This Fix Work in Your Case?

Quick signal helps us prioritize which fixes to verify and improve.

Prevention

Capture the exact failing error string in logs and tests so you can reproduce via a minimal script.
Pin production dependencies and upgrade only with a reproducible test that hits the failing path.

Version Compatibility Table

Version	Status
5.5.0	Fixed

Related Issues

No related fixes found.

Cluster: celery:configuration-error Celery hub Celery best practices All hubs All clusters

Related clusters: Data consistency Duplicates Duplicate processing

Sources

We don’t republish the full GitHub discussion text. Use the links above for context.

Celery Missing Import in Documentation in Django tutorial (Fix)