Registry / workflow / celery-redbeat

celery-redbeat

JSON →
library2.4.2pypypi✓ verified 25d ago

Celery RedBeat is a custom Celery Beat Scheduler that leverages Redis for persistent storage of scheduled tasks and their runtime metadata. It allows for dynamic creation, modification, and deletion of periodic tasks at runtime without requiring a restart of the Celery Beat service. This design provides fast startup times, even with a large number of tasks, and prevents multiple Beat instances from running simultaneously through a distributed lock mechanism. The current version is 2.3.3, and it maintains an active development and release cadence.

pip install celery-redbeat
INSTALL
IMPORT
SIG · CELERY-REDBEAT
C
celery-redbeat
workflowpythonv2.4.2
Install
4.0s avg
Import
741ms
Disk
43MB
Pass rate
10/ 10
Env Coverage10 / 10
glibc
3.93.13
musl
3.93.13
Install & Compatibility
Where this runs
tested against v2.4.2 · 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.768s · 46.5MB
glibc
py 3.103.95 runs
installs and imports cleanly · install 4.0s · import 0.714s · 47MB
43MB installed
● package 43MB
Code
Verified usage

Verified import paths — ran on the pinned version, not inferred.

RedBeatScheduler
from redbeat.schedulers import RedBeatScheduler
from redbeat import RedBeatScheduler
The `RedBeatScheduler` class is located within the `redbeat.schedulers` module, not directly under `redbeat`.
RedBeatSchedulerEntry
from redbeat import RedBeatSchedulerEntry

To get started, configure your Celery application to use `RedBeatScheduler` by setting `redbeat_redis_url` and specifying the scheduler when running `celery beat`. Tasks can be defined dynamically using `RedBeatSchedulerEntry` instances and saved to Redis. It's recommended to use a different Redis database for RedBeat than for your Celery broker.

import os from celery import Celery from celery.schedules import crontab from redbeat import RedBeatSchedulerEntry # Configure Celery app with RedBeat app = Celery('my_app', broker=os.environ.get('CELERY_BROKER_URL', 'redis://localhost:6379/0')) app.conf.update( redbeat_redis_url=os.environ.get('REDBEAT_REDIS_URL', 'redis://localhost:6379/1'), # Use a different DB than broker redbeat_lock_timeout=300, # 5 minutes timezone='UTC', enable_utc=True, # Other Celery settings ) # Define a Celery task @app.task def my_periodic_task(arg1, arg2): print(f"Executing task with {arg1} and {arg2}") return arg1 + arg2 # Example of dynamically scheduling a task # This code would typically run in an application context, not directly in the Beat process # To make it runnable for quickstart, wrap it in a function def schedule_task(): # Ensure RedBeat is properly configured and Redis is running # A new entry for an interval task entry_interval = RedBeatSchedulerEntry( 'my-interval-task', 'my_app.my_periodic_task', # Task path app.conf.beat_schedule.schedule(run_every=10), # Run every 10 seconds args=[10, 20], kwargs={'some_kwarg': 'value'}, app=app ) entry_interval.save() print(f"Scheduled interval task: {entry_interval.key}") # A new entry for a crontab task (every minute) entry_crontab = RedBeatSchedulerEntry( 'my-crontab-task', 'my_app.my_periodic_task', # Task path crontab(minute='*', hour='*', day_of_week='*'), # Run every minute args=['hello', 'world'], app=app ) entry_crontab.save() print(f"Scheduled crontab task: {entry_crontab.key}") # To run Celery Beat with RedBeat: # celery -A my_app beat -S redbeat.RedBeatScheduler --loglevel=info # To run Celery Worker: # celery -A my_app worker --loglevel=info # Example of how to call schedule_task() (for demonstration purposes) if __name__ == '__main__': # In a real application, you'd trigger this via API or startup logic # For this quickstart, we'll just demonstrate saving an entry # and assume you'll run Beat and Worker separately. print("To run, ensure Redis is active, then execute:") print("1. For Celery Beat: celery -A my_app beat -S redbeat.RedBeatScheduler --loglevel=info") print("2. For Celery Worker: celery -A my_app worker --loglevel=info") print("3. Then, from an interactive shell or a script, call schedule_task()") # Example of manual scheduling if app context is setup: # from my_app import app, my_periodic_task, schedule_task # schedule_task()
Debug
Known issues
breakingVersion 2.1.0 dropped support for Python versions older than 3.8. Ensure your Python environment meets this requirement before upgrading.
fix
Upgrade your Python environment to 3.8 or newer, or pin `celery-redbeat` to a version prior to 2.1.0.
affects: <2.1.0
breakingVersion 0.10.0 introduced significant API changes, including breaking changes due to a reworked API and improved Python 3 compatibility. Users upgrading from very old versions (pre-0.10.0) may need to update their task definitions and configurations.
fix
Refer to the `celery-redbeat` documentation for version 0.10.0+ to adjust task definitions and scheduler configurations.
affects: <0.10.0
gotchaRedBeat uses a distributed lock to prevent multiple Beat instances from running simultaneously. Misconfiguration of `redbeat_lock_key` or `redbeat_lock_timeout` can lead to multiple Beat instances (if `redbeat_lock_key` is `None`) or extended downtime if a Beat instance fails and the lock takes too long to expire.
fix
Ensure `redbeat_lock_key` is not `None` in production environments. Configure `redbeat_lock_timeout` appropriately (e.g., 5 times `CELERYBEAT_MAX_LOOP_INTERVAL`) for your application's recovery needs. Monitor Redis for lock key health.
affects: All versions
gotchaUsing the same Redis database for Celery's broker/result backend and RedBeat's schedule storage can lead to issues, particularly if idle connections are closed, potentially corrupting the scheduler state and causing tasks to stop running silently.
fix
Always configure `redbeat_redis_url` to point to a different Redis database (e.g., `redis://localhost:6379/1`) than your Celery broker/result backend (e.g., `redis://localhost:6379/0`).
affects: All versions
gotchaCelery Beat, including RedBeat, can sometimes silently stop dispatching tasks or fail to pick up new tasks, especially if workers are saturated with long-running tasks, if there are underlying Redis connection issues, or if Beat and Worker are run in the same process (which is not recommended for production).
fix
Run Celery Beat and Celery Workers as separate processes. Monitor Celery worker queues and task execution times. Implement robust logging and monitoring for both Celery Beat and Redis connections. Consider clearing Redis keys and recreating tasks if the scheduler gets into a corrupted state.
affects: All versions
Errors
Common errors & fixes
redis.exceptions.AuthenticationError: WRONGPASS invalid username-password pair or user is disabled.
This error occurs when RedBeat attempts to connect to a Redis Sentinel instance with ACL authentication enabled, but the `username` parameter is not explicitly passed, as RedBeat's default Sentinel client initialization does not extract it from the configuration.
fix
To resolve this, inject the `username` directly into the connection keyword arguments via the `redbeat_redis_use_ssl` configuration option, as it allows arbitrary parameters to be passed to the Redis client constructor.

Example `celeryconfig.py` modification:
`app.conf.redbeat_redis_use_ssl = {'username': 'your_username', 'ssl': False}`
ImportError: No module named 'celery.utils.timeutils'
This error typically arises when an older version of `celery-redbeat` is used with Celery 4.x or newer, as the `celery.utils.timeutils` module was removed or refactored in later Celery versions.
fix
Upgrade `celery-redbeat` to a version that is compatible with your Celery installation (e.g., `celery-redbeat` 0.10.0 or later for Celery 4.0+).

`pip install --upgrade celery-redbeat`
No module named 'celery.five'
This issue occurs when `celery-redbeat` tries to import `celery.five`, a compatibility module that existed in Celery 4.x but was removed in Celery 5.x, indicating an incompatibility between `celery-redbeat` and Celery 5.x.
fix
Upgrade `celery-redbeat` to a version that officially supports Celery 5.x, or temporarily pin your Celery version to 4.x if an updated `celery-redbeat` is not yet available.

`pip install --upgrade celery-redbeat`
RedBeatSchedulerEntry: 'app' parameter missing or misconfigured (conf object's redis_url property is not set)
When creating `RedBeatSchedulerEntry` instances programmatically, if the `app` parameter (referencing the Celery app instance) is omitted or the provided app is not fully configured with Redis settings, the scheduler entry will not have access to the `redis_url`, leading to connection issues.
fix
Ensure that the `Celery` app instance, fully configured with `redbeat_redis_url` (or other Redis settings), is explicitly passed to the `RedBeatSchedulerEntry` constructor.

Example:
```python
from celery import Celery
from redbeat import RedBeatSchedulerEntry

app = Celery('my_app', broker='redis://localhost:6379/0', backend='redis://localhost:6379/1')
app.conf.redbeat_redis_url = 'redis://localhost:6379/1'

# ... define your task and schedule ...

interval = app.conf.beat_schedule['my_task']['schedule'] # Example, get from your defined schedules
entry = RedBeatSchedulerEntry('my_task_name', 'my_app.tasks.my_task', interval, app=app)
entry.save()
```
Upgrade
Version history
2.4.2latest on PyPI · released Jul 27, 2026
Audit
Dependencies
celeryrequiredRedBeat is a scheduler for Celery and requires a Celery application to function.
redisrequiredRedBeat uses Redis as its backend for storing schedule data.
Agent activity
22 hits · last 30 days
node
18
OpenAI (training)
1
Resources
celery-redbeat — pip install celery-redbeat · libregistry