{"id":1995,"library":"django-celery-beat","title":"Django Celery Beat","description":"django-celery-beat is an extension that enables storing and managing Celery periodic task schedules directly within the Django database. It provides a convenient Django Admin interface for creating, editing, and deleting these tasks, offering dynamic scheduling capabilities without code changes. The current version is 2.9.0, and the library maintains a regular release cadence with several updates annually.","status":"active","version":"2.9.0","language":"en","source_language":"en","source_url":"https://github.com/celery/django-celery-beat","tags":["django","celery","scheduling","periodic tasks","beat","admin","database"],"install":[{"cmd":"pip install django-celery-beat","lang":"bash","label":"Install stable version"}],"dependencies":[{"reason":"Core task queue and scheduler framework.","package":"celery"},{"reason":"Provides the web framework and ORM for database-backed scheduling.","package":"django"},{"reason":"Used for timezone-aware scheduling, explicitly mentioned in past release notes and runtime requirements.","package":"django-timezone-field"}],"imports":[{"symbol":"PeriodicTask","correct":"from django_celery_beat.models import PeriodicTask"},{"symbol":"IntervalSchedule","correct":"from django_celery_beat.models import IntervalSchedule"},{"symbol":"CrontabSchedule","correct":"from django_celery_beat.models import CrontabSchedule"},{"symbol":"SolarSchedule","correct":"from django_celery_beat.models import SolarSchedule"},{"symbol":"ClockedSchedule","correct":"from django_celery_beat.models import ClockedSchedule"}],"quickstart":{"code":"# myproject/settings.py\nINSTALLED_APPS = [\n    # ...\n    'django.contrib.admin',\n    'django_celery_beat',\n    # 'myapp' where your tasks are defined\n]\n\n# Configure Celery Beat scheduler to use the database\nCELERY_BEAT_SCHEDULER = 'django_celery_beat.schedulers:DatabaseScheduler'\n\n# myproject/celery.py\nimport os\nfrom celery import Celery\n\nos.environ.setdefault('DJANGO_SETTINGS_MODULE', 'myproject.settings')\n\napp = Celery('myproject')\n\n# Using a string here means the worker doesn't have to serialize\n# the configuration object to child processes.\n# - namespace='CELERY' means all celery-related configuration keys\n#   should have a `CELERY_` prefix.\napp.config_from_object('django.conf:settings', namespace='CELERY')\n\n# Auto-discover tasks in all installed apps\napp.autodiscover_tasks()\n\n@app.task(bind=True, ignore_result=True)\ndef debug_task(self):\n    print(f'Request: {self.request!r}')\n\n# myapp/tasks.py\nfrom celery import shared_task\nfrom celery.utils.log import get_task_logger\n\nlogger = get_task_logger(__name__)\n\n@shared_task\ndef my_periodic_task():\n    logger.info('Executing my_periodic_task!')\n\n# To run:\n# 1. Apply migrations: python manage.py migrate django_celery_beat\n# 2. Start Celery worker: celery -A myproject worker -l info\n# 3. Start Celery Beat: celery -A myproject beat -l info --scheduler django_celery_beat.schedulers:DatabaseScheduler\n# 4. In Django Admin (e.g., http://127.0.0.1:8000/admin/django_celery_beat/periodictask/add/):\n#    - Create a Crontab Schedule (e.g., 'Every minute': minute='*', hour='*', day_of_week='*', day_of_month='*', month_of_year='*')\n#    - Create a Periodic Task:\n#      - Name: 'Run My Periodic Task'\n#      - Task: 'myapp.tasks.my_periodic_task' (full path to your task)\n#      - Schedule: Choose the Crontab Schedule created above\n#      - Enabled: True\n","lang":"python","description":"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."},"warnings":[{"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.","message":"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.","severity":"breaking","affected_versions":"<2.8.0 (Django 5.x+), <2.2.1 (Celery 5.x+)"},{"fix":"Run `python manage.py shell` and execute: `from django_celery_beat.models import PeriodicTask; PeriodicTask.objects.all().update(last_run_at=None)`.","message":"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.","severity":"gotcha","affected_versions":"All versions with timezone changes"},{"fix":"In your `celery.py`, update `app.config_from_object` to include `namespace='CELERY'`.","message":"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`.","severity":"gotcha","affected_versions":"All versions where `CELERY_BEAT_SCHEDULER` is set via Django settings."},{"fix":"Configure your deployment environment (e.g., Docker Compose, systemd) to run only one `celery -A [project-name] beat` process.","message":"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.","severity":"gotcha","affected_versions":"All versions"},{"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.","message":"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.","severity":"deprecated","affected_versions":"Older projects using `djcelery`"}],"env_vars":null,"last_verified":"2026-04-09T00:00:00.000Z","next_check":"2026-07-08T00:00:00.000Z"}