Install & Compatibility
Where this runs
tested against v2.9.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 · 90.4MB
glibcpy 3.10–3.95 runs
installs and imports cleanly · install 5.7s · import 0.000s · 91MB
88MB installed
● package 88MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
PeriodicTask
✓ from django_celery_beat.models import PeriodicTask
✗ from django_celery_beat.models import PeriodicTask
This quickstart demonstrates how to integrate `django-celery-beat` into a Django project. It covers configuring the `settings.py` to enable the app and set the database scheduler, setting up `celery.py` for task discovery, defining a simple periodic task in `tasks.py`, and finally, how to create a periodic task through the Django Admin interface using a crontab schedule. Ensure `celery` and `django` are already set up in your project.
# myproject/settings.py
INSTALLED_APPS = [
# ...
'django.contrib.admin',
'django_celery_beat',
# 'myapp' where your tasks are defined
]
# Configure Celery Beat scheduler to use the database
CELERY_BEAT_SCHEDULER = 'django_celery_beat.schedulers:DatabaseScheduler'
# myproject/celery.py
import os
from celery import Celery
os.environ.setdefault('DJANGO_SETTINGS_MODULE', 'myproject.settings')
app = Celery('myproject')
# 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')
# Auto-discover tasks in all installed apps
app.autodiscover_tasks()
@app.task(bind=True, ignore_result=True)
def debug_task(self):
print(f'Request: {self.request!r}')
# myapp/tasks.py
from celery import shared_task
from celery.utils.log import get_task_logger
logger = get_task_logger(__name__)
@shared_task
def my_periodic_task():
logger.info('Executing my_periodic_task!')
# To run:
# 1. Apply migrations: python manage.py migrate django_celery_beat
# 2. Start Celery worker: celery -A myproject worker -l info
# 3. Start Celery Beat: celery -A myproject beat -l info --scheduler django_celery_beat.schedulers:DatabaseScheduler
# 4. In Django Admin (e.g., http://127.0.0.1:8000/admin/django_celery_beat/periodictask/add/):
# - Create a Crontab Schedule (e.g., 'Every minute': minute='*', hour='*', day_of_week='*', day_of_month='*', month_of_year='*')
# - Create a Periodic Task:
# - Name: 'Run My Periodic Task'
# - Task: 'myapp.tasks.my_periodic_task' (full path to your task)
# - Schedule: Choose the Crontab Schedule created above
# - Enabled: True
Debug
Known issues
breakingAlways ensure your `django-celery-beat` version is compatible with your `Django` and `Celery` versions. Recent versions (2.8.0, 2.7.0, 2.6.0) have added explicit support for `Django` 5.0, 5.1, 5.2 and `Python` 3.12, 3.13. `celery>=5.0,<6.0` is generally required. Consult the official changelog for specific compatibility matrices to avoid unexpected behavior or errors.fixCheck the `django-celery-beat` GitHub releases and PyPI page for supported Django/Celery/Python versions. Upgrade `django-celery-beat` if needed, or downgrade other dependencies to match.
affects: <2.8.0 (Django 5.x+), <2.2.1 (Celery 5.x+)
gotchaIf you change your Django `TIME_ZONE` setting, existing periodic task schedules will still be based on the old timezone. To force Celery Beat to re-evaluate schedules with the new timezone, you must reset the `last_run_at` field for all periodic tasks.fixRun `python manage.py shell` and execute: `from django_celery_beat.models import PeriodicTask; PeriodicTask.objects.all().update(last_run_at=None)`.
affects: All versions with timezone changes
gotchaWhen configuring `CELERY_BEAT_SCHEDULER` in Django's `settings.py`, you must ensure your `celery.py` file uses `app.config_from_object('django.conf:settings', namespace='CELERY')`. Without `namespace='CELERY'`, Celery Beat may default to the `PersistentScheduler` (file-based) instead of `DatabaseScheduler`.fixIn your `celery.py`, update `app.config_from_object` to include `namespace='CELERY'`.
affects: All versions where `CELERY_BEAT_SCHEDULER` is set via Django settings.
gotchaYou must ensure only a single Celery Beat scheduler process is running for a given schedule at any time. Running multiple Beat instances will lead to duplicate task executions.fixConfigure your deployment environment (e.g., Docker Compose, systemd) to run only one `celery -A [project-name] beat` process.
affects: All versions
deprecatedThe `djcelery` library, which previously provided Django integration for Celery, is deprecated and does not support modern Django versions. Users migrating from older setups should switch to `django-celery-beat` for periodic tasks.fixRemove `djcelery`, install `django-celery-beat`, update `INSTALLED_APPS`, and potentially migrate data from `djcelery` models to `django_celery_beat` models as per migration guides or custom scripts. `django-celery-results` is the equivalent for task results.
affects: Older projects using `djcelery`
Upgrade
Version history
2.9.0latest on PyPI · released Feb 28, 2026
Audit
Dependencies
celeryrequiredCore task queue and scheduler framework.
djangorequiredProvides the web framework and ORM for database-backed scheduling.
django-timezone-fieldrequiredUsed for timezone-aware scheduling, explicitly mentioned in past release notes and runtime requirements.