Django Celery Beat

Warnings

• breaking Always 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.
  Fix: Check 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.
• gotcha If 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.
  Fix: Run `python manage.py shell` and execute: `from django_celery_beat.models import PeriodicTask; PeriodicTask.objects.all().update(last_run_at=None)`.
• gotcha When 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`.
  Fix: In your `celery.py`, update `app.config_from_object` to include `namespace='CELERY'`.
• gotcha You 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.
  Fix: Configure your deployment environment (e.g., Docker Compose, systemd) to run only one `celery -A [project-name] beat` process.
• deprecated The `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.
  Fix: Remove `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.

Install

• pip install django-celery-beat Install stable version

Imports

• PeriodicTask

  from django_celery_beat.models import PeriodicTask

• IntervalSchedule

  from django_celery_beat.models import IntervalSchedule

• CrontabSchedule

  from django_celery_beat.models import CrontabSchedule

• SolarSchedule

  from django_celery_beat.models import SolarSchedule

• ClockedSchedule

  from django_celery_beat.models import ClockedSchedule

Quickstart

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