Skip to content
Tutorials Center
My learning

Topics

Lesson 16 of 36 ยท Scheduling and Beat

Crontab and Solar Schedules in Celery

Use Celery crontab schedules to run tasks at exact times: fields, ranges, steps, day-of-week and month rules, timezones, solar schedules and a runnable cron matcher.

An interval schedule says "every N seconds". A crontab schedule says "at these clock times": every day at 07:30, every Monday at 09:00, the first day of each month at midnight. Celery's crontab follows the familiar Unix cron idea but is written with keyword arguments.

The crontab fields

Python
from celery.schedules import crontab

crontab()                                  # every minute
crontab(minute=0, hour=0)                  # every day at midnight
crontab(minute=30, hour=7)                 # every day at 07:30
crontab(minute=0, hour="*/3")              # every three hours: 0, 3, 6, ...
crontab(minute="*/15")                     # every 15 minutes
crontab(minute=0, hour="9-17")             # on the hour, 09:00 to 17:00
crontab(minute=0, hour=9, day_of_week="mon-fri")   # weekdays at 09:00
crontab(minute=0, hour=0, day_of_month=1)  # first of each month
crontab(minute=0, hour=6, month_of_year="*/3")     # 06:00 on every day of Jan, Apr, Jul, Oct
Argument Range Notes
minute 0-59 Defaults to * (every minute).
hour 0-23
day_of_week 0-6 or sun..sat 0 is Sunday. Names are friendlier.
day_of_month 1-31
month_of_year 1-12

Each field accepts the same value syntaxes:

  • * for every value,
  • a number (5),
  • a range (9-17),
  • a step (*/15 or 10-40/10),
  • a comma list (1,15,30) or a list in Python ([1, 15, 30]).

Important trap: unspecified fields default to *, but minute defaults to * too. crontab(hour=7) therefore means every minute during the 07:00 hour, 60 runs, not once at 07:00. If you want one run, set minute=0.

A second trap is combining day_of_month and day_of_week. In Celery, both conditions must be true (AND), unlike classic Unix cron which uses OR when both are restricted. crontab(day_of_month=13, day_of_week="fri") fires only on Friday the 13th.

Putting crontab in the schedule

Python
app.conf.beat_schedule = {
    "morning-digest": {
        "task": "shop.tasks.send_digest",
        "schedule": crontab(hour=7, minute=30),
    },
    "monday-report": {
        "task": "shop.tasks.weekly_report",
        "schedule": crontab(hour=9, minute=0, day_of_week="mon"),
        "args": ("sales",),
    },
}

Try it: a crontab matcher

Beat evaluates a crontab by asking, for a given minute, whether it matches all five fields. This runnable implementation parses the same syntax (*, ranges, steps, lists, day names) and finds the next run times. It is a stand-in, not Celery's code, but follows the same rules including the AND semantic of day fields.

Python Stand-in: parse and match crontab fields

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with input()), it gets the next line from this box.

The last line demonstrates the most common mistake: crontab(hour=7) fires 60 times a day.

Time zones and daylight saving

Crontab fields are evaluated in the app's timezone:

Python
app.conf.timezone = "America/New_York"

Be careful with local time:

  • During the spring clock change, the hour from 02:00 to 03:00 does not exist, so a job at 02:30 may be skipped that day.
  • During the autumn change, 01:30 occurs twice, and a job might run twice.

If exact once-per-day behaviour matters, pick UTC (timezone = "UTC") or schedule at an hour that never falls in the clock-change gap, such as 12:00. You can also give a single crontab its own handling with nowfun, an advanced option that passes a function returning the "current time".

Solar schedules

For tasks tied to sun events (turn on lights at sunset), Celery provides solar:

Python
from celery.schedules import solar

app.conf.beat_schedule = {
    "lights-on": {
        "task": "home.tasks.lights_on",
        "schedule": solar("sunset", 52.52, 13.405),   # event, latitude, longitude
    },
}

Supported events include dawn_astronomical, dawn_nautical, dawn_civil, sunrise, solar_noon, sunset, dusk_civil, dusk_nautical and dusk_astronomical. You provide a latitude and longitude, and celery.schedules uses the ephem library to calculate the time (install it with pip install ephem). Solar schedules are rare, but they are an honest example of why a schedule is an object with a method "when is next?", not just a number.

Missed runs

Beat is not a job guarantee. If Beat is down at 07:30, the digest is not sent after it comes back; for crontab schedules Beat only looks at the present minute. Design around that:

  • Keep Beat supervised so it restarts quickly.
  • Make tasks catch up: "send every digest not yet sent", rather than "send today's digest". That way a missed run is repaired by the next one.
  • For critical jobs, add monitoring that alerts when the expected output did not appear.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. How often does crontab(hour=7) run?

    minute defaults to *, so the entry matches every minute of hour 7. Set minute=0 for a single run.
  2. 2. What does crontab(minute='*/15') mean?

    A step of 15 over the minute range 0-59 yields 0, 15, 30 and 45.
  3. 3. How does Celery combine day_of_month and day_of_week when both are set?

    Celery requires all fields to match, so day_of_month=13 with day_of_week='fri' means Friday the 13th.
  4. 4. Beat was down at 07:30 and restarted at 07:45. What happens to a crontab(hour=7, minute=30) entry?

    Crontab entries only fire in their minute. Design catch-up logic into the task if misses matter.

Summary

  • crontab(minute, hour, day_of_week, day_of_month, month_of_year) gives clock-aligned schedules; fields accept values, ranges, steps and lists.
  • Unset fields mean "every", so always set minute when you want one run per hour or day.
  • Day fields combine with AND in Celery; times use the configured timezone, so beware daylight saving.
  • Solar schedules compute sun events from a latitude and longitude.
  • Missed runs are not replayed: write tasks that catch up.

Next: Dynamic Schedules: Database-Backed Periodic Tasks