Install & Compatibility
Where this runs
tested against v2.6.0 · 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
muslpy 3.10–3.95 runs
installs and imports cleanly · install 0.0s · import 0.000s · 89.5MB
glibcpy 3.10–3.95 runs
installs and imports cleanly · install 5.7s · import 0.000s · 90MB
87MB installed
● package 87MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
TaskResult
✓ from django_celery_results.models import TaskResult
✗ from django_celery_results.models import TaskResult
GroupResult
✓ from django_celery_results.models import GroupResult
To quickly integrate `django-celery-results`, first add `django_celery_results` to your `INSTALLED_APPS` in `settings.py`. Then, configure Celery to use the Django ORM backend by setting `CELERY_RESULT_BACKEND = 'django-db'` and run Django migrations. It's also recommended to set `CELERY_RESULT_EXTENDED = True` to store full task metadata like arguments and names. A basic Celery app and a sample task are shown, along with how to retrieve results from the task object or directly from the database model.
# myproject/settings.py
INSTALLED_APPS = [
# ... other apps
'django_celery_results',
]
CELERY_RESULT_BACKEND = 'django-db'
CELERY_RESULT_EXTENDED = True # Recommended to store task args/kwargs/name
# myproject/celery.py (or similar Celery app configuration)
import os
from celery import Celery
os.environ.setdefault('DJANGO_SETTINGS_MODULE', 'myproject.settings')
app = Celery('myproject')
app.config_from_object('django.conf:settings', namespace='CELERY')
app.autodiscover_tasks()
# myapp/tasks.py
from celery import shared_task
@shared_task
def add(x, y):
return x + y
# To run and get result in Django shell:
# from myapp.tasks import add
# result = add.delay(4, 5)
# print(result.get(timeout=10)) # Output: 9
# Or to query from the DB:
# from django_celery_results.models import TaskResult
# task_db_result = TaskResult.objects.get(task_id=result.id)
# print(task_db_result.status)
# print(task_db_result.result)
Debug
Known issues
breakingAs of v2.4.0, the `TaskResult.task_name` field is no longer automatically populated by default due to a security concern. If your application relies on this field, you must explicitly set `CELERY_RESULT_EXTENDED = True` in your Django settings to store extended properties, which includes the task name, args, and kwargs.fixSet `CELERY_RESULT_EXTENDED = True` in your Django `settings.py`.
affects: >=2.4.0
breakingSupport for older Django and Python versions has been dropped. v2.4.0 dropped Django 2.2 support, and v2.0.0 dropped support for Django < 2.2 and Python < 3.6. Ensure your environment meets the minimum requirements.fixUpgrade Django to `3.2.25` or newer and Python to `3.6` or newer. Refer to the project's `pyproject.toml` or `setup.cfg` for exact dependency ranges.
affects: >=2.0.0, >=2.4.0
gotchaWhen using MySQL, you might encounter `django.db.utils.OperationalError: (1071, 'Specified key was too long; max key length is 767 bytes')` during migrations. This is due to indexing long string fields.fixSet `DJANGO_CELERY_RESULTS_TASK_ID_MAX_LENGTH=191` in your Django `settings.py` to shorten the `task_id` field length.
affects: All
deprecatedThe `default_app_config` attribute was deprecated in Django 3.1 and removed in Django 4.0. `django-celery-results` fixed this in v2.3.0. If you are on an older version of `django-celery-results` with Django 3.1+, you might see deprecation warnings.fixUpgrade `django-celery-results` to v2.3.0 or higher.
affects: <2.3.0 with Django >=3.1
gotchaA common pitfall in Django and Celery integration is dispatching a task immediately that relies on database changes that haven't been committed yet. The Celery task might run before the database transaction is complete.fixIf a task relies on data committed within the current request/transaction, use `transaction.on_commit` to defer the task dispatch until after the transaction is successfully committed. Example: `from django.db import transaction; transaction.on_commit(lambda: my_task.delay(arg))`
affects: All
gotchaThe default Celery configuration might not store detailed task arguments, keyword arguments, or other metadata. This can make debugging or re-running tasks difficult.fixSet `CELERY_RESULT_EXTENDED = True` in your Django `settings.py` to enable storing extended task properties like `args`, `kwargs`, and `task_name` in the `TaskResult` model.
affects: All
Upgrade
Version history
2.6.0latest on PyPI · released Apr 10, 2025
Audit
Dependencies
celeryrequiredCore task queue functionality.
DjangorequiredProvides the ORM and settings integration.