Huey Periodic Tasks: crontab, the Consumer, Time Zones, Missed Runs
Contents
A Huey periodic task runs only while a Huey consumer is running with periodic scheduling enabled: once a minute, the consumer checks every @huey.periodic_task against the current time and enqueues the ones that match. Start the consumer with -n, or run none, and periodic tasks silently stop. Run two consumers without -n on one of them, and every run happens twice. Minutes that pass while no consumer is running are skipped, not caught up.
This guide covers Huey 3.5 (3.5.4 was current on PyPI on November 16, 2026), with source links to that tag. The periodic task API described here is the same one Huey 2.x used; 3.0 removed Python 2 support and added features such as timeout, and later 3.x releases changed scheduler stall handling and crontab validation, noted below. For Python scheduling in general, see the Python integration page.
How Huey Runs a Periodic Task#
A periodic task is a task with a schedule test attached:
# tasks.py
from huey import RedisHuey, crontab
huey = RedisHuey("reports")
@huey.periodic_task(crontab(minute="0", hour="3"))
def nightly_cleanup():
print("Removing expired exports")The decorator takes a validate_datetime function, here built by crontab(), plus the same options as an ordinary task: retries, retry_delay, retry_backoff, priority, context, name, expires, and timeout (api.py). Periodic tasks can't take required arguments, and their return values aren't meant to be read.
The consumer does the rest. It has three parts: worker threads or processes that execute tasks, a scheduler loop that moves delayed tasks into the queue, and, inside that loop, the periodic check. Every 60 seconds the scheduler asks each periodic task whether the current time matches and enqueues the ones that do. A worker then picks the task up like any other (consumer.py). The consumer logs Periodic tasks are enabled. at startup and Enqueueing periodic task ... each time it enqueues one.
So a periodic run needs, in order: a consumer process, its periodic check enabled, a matching minute, and a free worker.
The Consumer Must Run With Periodic Enabled#
Start the consumer by pointing it at your Huey instance:
huey_consumer.py tasks.huey -w 4 -k threadIn Django with huey.contrib.djhuey, the equivalent is python manage.py run_huey. Options that affect periodic tasks (consumer docs):
| Option | Default | Effect on periodic tasks |
|---|---|---|
-n, --no-periodic |
Off | This consumer never enqueues periodic tasks |
-w, --workers |
1 | One worker means a long task delays every task behind it |
-k, --worker-type |
thread |
thread, process, or greenlet |
-s, --scheduler-interval |
1 second | How often the scheduler loop runs; must divide 60. Periodic checks stay once a minute |
-g, --graceful-signal |
INT |
Which of SIGINT or SIGTERM finishes running tasks before exit (added in 3.4) |
-t, --shutdown-timeout |
None | Caps the graceful wait, then interrupts what's left (added in 3.4) |
The common ways periodic tasks stop:
- No consumer is running. Enqueueing tasks from your web app works without a consumer; periodic tasks don't, because nothing checks the schedule. A deploy that starts the web process but not the consumer stops every periodic task.
- The only consumer has
-n. Often copied from a multi-consumer setup into a single-consumer one. Check the startup log forPeriodic tasks are disabled. - The consumer can't import the module. A periodic task is registered when its module is imported. If
tasks.pyimports thehueyinstance but the consumer is pointed at a module that never importstasks.py, the consumer starts fine with no periodic tasks. In Django, djhuey autodiscoverstasks.pyin installed apps. - The task is in the queue but workers are busy. A one-worker consumer running a 20-minute task delays the 03:00 cleanup until it finishes. Add workers, or move long work to its own queue and consumer.
Run One Periodic Scheduler per Queue#
Every consumer with periodic enabled enqueues each due periodic task. Two consumers on one queue means every periodic task runs twice; five consumers, five times. The consumer docs say to pass -n to all but one.
In practice:
- Scaled worker deployments: run one consumer with periodic enabled and the rest with
-n. In Kubernetes or a PaaS that usually means two process types, not one scaled deployment. - Rolling deploys: while old and new consumers overlap, both may enqueue the same minute. Make periodic tasks safe to run twice, or guard them with a lock.
Huey has its own lock for that. lock_task goes directly below the task decorator; if the lock is held, the run is skipped:
from huey import RedisHuey, crontab
huey = RedisHuey("reports")
@huey.periodic_task(crontab(minute="*/15"))
@huey.lock_task("sync-inventory")
def sync_inventory():
print("Syncing inventory")The lock prevents overlap, not a second enqueue. A duplicate that arrives after the first run finishes still runs. For "exactly once per scheduled minute," record the scheduled minute somewhere the task can check (idempotent scheduled jobs).
crontab() Rules That Differ From cron#
crontab(minute='*', hour='*', day='*', month='*', day_of_week='*', strict=False) takes cron-like strings or integers: *, */n, m-n, m-n/step, and comma lists. Differences from a crontab line:
- Argument order is by name. There's no expression string;
crontab(hour="3")with nominutemeans every minute from 03:00 to 03:59. Always setminute. - Day fields combine with AND. Huey checks every field, so
crontab(day="1-7", day_of_week="1")means the first Monday of the month. Vixie cron treats a restricted day-of-month and day-of-week as OR. - Sunday is 0 or 7, Saturday 6.
- No names,
L,W, or#. Since 3.4, a field that matches no values raisesValueError, andstrict=Trueraises on any input it doesn't recognize. - Helpers:
crontab.hourly()isminute="0";crontab.daily()is midnight.
validate_datetime can be any function that takes a datetime and returns True when the task should run, so a schedule crontab can't express, such as the last business day of the month, can be written as plain Python.
Time Zones: UTC by Default#
Huey(..., utc=True) is the default. With it, the consumer passes the current UTC time to each periodic task's test, so crontab(minute="0", hour="3") runs at 03:00 UTC whatever the server's zone. With utc=False, the test receives the consumer host's local time (datetime.datetime.now()), which makes the schedule depend on the machine's TZ and daylight saving time.
Two practical notes:
- In Django, set it in the
HUEYsettings dict, for exampleHUEY = {"name": "reports", "utc": False, ...}; djhuey passes the keys to the storage class. - With local time, a run scheduled inside the spring-forward gap doesn't happen that day, and one inside the repeated fall-back hour can match twice. Cron and daylight saving time covers both cases; UTC avoids them.
Missed Runs While the Consumer Is Down#
Huey keeps no record of when a periodic task last ran. The scheduler only asks "does now match?", so a minute that passes while no consumer is running is gone. A consumer that's down from 02:55 to 03:10 skips the 03:00 run, and nothing logs that it was missed.
The same is true after a stall. Since 3.0.2, if the scheduler loop falls behind, for example after the machine was suspended, it skips the checks it missed instead of running them back to back, which used to enqueue duplicates. Daily and weekly tasks are the ones most affected, because one missed minute means a missed day or week; missed runs after downtime compares this with other schedulers.
If a run must happen, make the task work out what it owes from a stored watermark, such as the last processed date, instead of relying on every scheduled minute firing.
Shutdown Interrupts Running Tasks by Default#
By default SIGINT is graceful: workers finish their current tasks, then the consumer exits. SIGTERM is immediate: running tasks are interrupted. Most process managers, Docker, and Kubernetes stop processes with SIGTERM, so a deploy that restarts the consumer mid-run kills the run. Huey doesn't guarantee at-least-once delivery, so an interrupted task isn't retried. Use -g TERM (3.4 and later) to make SIGTERM graceful, and -t to bound the wait to less than your platform's kill timeout.
Get Alerted When a Periodic Task Doesn't Run#
Huey's own signals report what happens inside a running consumer. SIGNAL_ERROR fires when a task raises and SIGNAL_INTERRUPTED when shutdown interrupts one:
from huey import RedisHuey
from huey.signals import SIGNAL_ERROR
huey = RedisHuey("reports")
@huey.signal(SIGNAL_ERROR)
def log_task_error(signal, task, exc=None):
print(f"{task.name} failed: {type(exc).__name__}")Nothing in the consumer can report the failures above that matter most: no consumer, -n on the only consumer, a module that wasn't imported, a minute that passed during a deploy. Those need a check outside the process that knows when each run is due.
The cronradar Python SDK (0.1.1) does this with a context manager inside the task. Install it with pip install cronradar and set CRONRADAR_API_KEY in the consumer's environment. To keep the Huey schedule and the reported schedule from drifting apart, define the fields once:
# tasks.py
import cronradar
from huey import RedisHuey, crontab
huey = RedisHuey("reports")
NIGHTLY_CLEANUP = {"minute": "0", "hour": "3"}
def as_cron(fields):
"""Five-field cron for a crontab() argument dict."""
return " ".join(
str(fields.get(name, "*")) for name in ("minute", "hour", "day", "month", "day_of_week")
)
@huey.periodic_task(crontab(**NIGHTLY_CLEANUP))
def nightly_cleanup():
with cronradar.job("nightly-cleanup", schedule=as_cron(NIGHTLY_CLEANUP)):
remove_expired_exports()
def remove_expired_exports():
print("Removing expired exports")cronradar.job reports a start when the block begins and a completion when it ends. If the block raises, it reports a failure with the exception's message and re-raises the exception, so Huey's retries and SIGNAL_ERROR work as before. Its requests time out after five seconds and never raise into the task.
What it catches:
- No run: the first report creates the monitor from
schedule. After that, when no start arrives by the expected time plus the grace period, the monitor goes fromwarningtocriticaland alerts by email, Slack, webhook, Discord, or PagerDuty. That covers a stopped consumer, a-nflag, a skipped minute, and a task stuck behind busy workers past its grace period. - Failure: a raised exception alerts immediately. With
retries, each failed attempt reports a failure. - Interrupted: a run killed by SIGTERM leaves a start with no finish, which is flagged as stuck.
- Duplicates: two runs are both recorded; CronRadar doesn't alert on an extra run.
Two schedule details. CronRadar evaluates schedules in the application's time zone, set in its settings (UTC if unset), which matches Huey's default utc=True when the application is left on UTC. And because Huey combines the day fields with AND, avoid restricting both day and day_of_week in a monitored task; check the schedule syntax for how CronRadar combines them.
If you'd rather not add a dependency, the same lifecycle works over HTTP: a start request, then complete or fail, to https://cron.life/api/v1/ping/{key}/... with the API key as the Basic auth username, a five-second timeout, and errors logged instead of raised. Celery beat not running has a standard-library helper that works unchanged in a Huey task. The Python integration guide covers the SDK. Use a separate CronRadar application and key per environment.
Frequently Asked Questions#
Why is my Huey periodic task not running?#
Check that a consumer is running, that its startup log says Periodic tasks are enabled., and that the module defining the task is imported by the module the consumer loads. Then check the schedule: a crontab() without minute runs every minute of the hour, and with the default utc=True the hour is UTC.
Does Huey run periodic tasks missed while the consumer was down?#
No. The consumer checks once a minute whether each periodic task matches the current time and keeps no history, so minutes that pass with no consumer running are skipped. Since 3.0.2 the scheduler also skips checks it missed during a stall instead of running them late.
Why does my Huey periodic task run twice?#
More than one consumer is enqueuing periodic tasks for the same queue. Every consumer with periodic scheduling enabled enqueues each due task, so run -n on all consumers but one. During a rolling deploy, old and new consumers can overlap, so make the task safe to run twice.
What time zone do Huey crontab schedules use?#
UTC by default, because Huey is created with utc=True. Pass utc=False to evaluate schedules in the consumer host's local time, which then follows that machine's time zone and daylight saving time.
How do I stop Huey from interrupting tasks on deploy?#
By default SIGTERM interrupts running tasks and SIGINT lets them finish. Start the consumer with -g TERM (Huey 3.4 and later) so SIGTERM is graceful, and set -t to a shutdown timeout shorter than your platform's kill timeout.
Put this guide to work
Connect your Python job to monitoring
Follow the current integration guide, check the release limitations, and verify a real run and alert delivery.
PyPI installs cronradar 0.1.2. It reports the jobs you wrap and does not discover jobs automatically.