Registry / database / django-celery-beat

django-celery-beat

JSON →
library2.9.0pypypi✓ verified 26d ago

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.

pip install django-celery-beat
INSTALL
IMPORT
SIG · DJANGO-CELERY-BEAT
D
django-celery-beat
databasepythonv2.9.0
Install
5.7s avg
Import
Disk
88MB
Pass rate
10/ 10
Env Coverage10 / 10
glibc
3.93.13
musl
3.93.13
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
musl
py 3.103.95 runs
installs and imports cleanly · install 0.0s · import 0.000s · 90.4MB
glibc
py 3.103.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.
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.
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.
fix
Run `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`.
fix
In 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.
fix
Configure 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.
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.
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.
Agent activity
29 hits · last 30 days
node
24
OpenAI (training)
1
Resources
django-celery-beat — pip install django-celery-beat · libregistry