Skip to main content

Cron expression parser and evaluator

Project description



Cron Sim(ulator), a cron expression parser and evaluator. Works with Python 3.6+. CronSim is written for and being used in Healthchecks (a cron job monitoring service).

Development priorities:

  • Correctness. CronSim tries to match Debian's cron as closely as possible, including its quirky behaviour during DST transitions.
  • Readability. Prefer simple over clever.
  • Minimalism. Don't implement features that Healthchecks will not use (for example, iteration in reverse, or the seconds field in cron expressions).


pip install cronsim


from datetime import datetime
from cronsim import CronSim

it = CronSim("0 0 * 2 MON#5",
for x in range(0, 10):


2044-02-29 00:00:00
2072-02-29 00:00:00
2112-02-29 00:00:00
2140-02-29 00:00:00
2168-02-29 00:00:00
2196-02-29 00:00:00
2208-02-29 00:00:00
2236-02-29 00:00:00
2264-02-29 00:00:00
2292-02-29 00:00:00

CronSim Works With zoneinfo

CronSim starting from version 2.0 is designed to work with timezones provided by the zoneinfo module.

A previous version, CronSim 1.0, was designed for pytz and relied on its following non-standard features:

  • the non-standard is_dst flag in the localize() method
  • the pytz.AmbiguousTimeError and pytz.NonExistentTimeError exceptions
  • the normalize() method

Supported Cron Expression Features

CronSim aims to match Debian's cron implementation (which itself is based on Paul Vixie's cron, with modifications). If CronSim evaluates an expression differently from Debian's cron, that's a bug.

CronSim is open to adding support for non-standard syntax features, as long as they don't conflict or interfere with the standard syntax.

DST Transitions

CronSim handles Daylight Saving Time transitions the same as Debian's cron. Debian has special handling for jobs with a granularity greater than one hour:

Local time changes of less than three hours, such as  those  caused  by
the  start or end of Daylight Saving Time, are handled specially.  This
only applies to jobs that run at a specific time and jobs that are  run
with  a    granularity  greater  than  one hour.  Jobs that run more fre-
quently are scheduled normally.

If time has moved forward, those jobs that would have run in the inter-
val that has been skipped will be run immediately.  Conversely, if time
has moved backward, care is taken to avoid running jobs twice.

See test cases in, TestDstTransitions class for examples of this special handling.

Cron Expression Feature Matrix

Feature Debian croniter cronsim
Seconds in the 6th field No Yes No
"L" as the day-of-month No Yes Yes
"L" in the day-of-week field No No Yes
Nth weekday of month No Yes Yes

Seconds in the 6th field: an optional sixth field specifying seconds. Supports the same syntax features as the minutes field.

Example: * * * * * */15 (every 15 seconds).

"L" as the day-of-month: support for the "L" special character in the day-of-month field. Interpreted as "the last day of the month".

Example: 0 0 L * * (at the midnight of the last day of every month).

"L" in the day-of-week field: support for the "{weekday}L" syntax. For example, "5L" means "the last Friday of the month".

Example: 0 0 * * 6L (at the midnight of the last Saturday of every month).

Nth weekday of month: support for "{weekday}#{nth}" syntax. For example, "MON#1" means "first Monday of the month", "MON#2" means "second Monday of the month".

Example: 0 0 * * MON#1 (at midnight of the first monday of every month).

Project details

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

cronsim-2.1.tar.gz (10.9 kB view hashes)

Uploaded source

Supported by

AWS AWS Cloud computing Datadog Datadog Monitoring Facebook / Instagram Facebook / Instagram PSF Sponsor Fastly Fastly CDN Google Google Object Storage and Download Analytics Huawei Huawei PSF Sponsor Microsoft Microsoft PSF Sponsor NVIDIA NVIDIA PSF Sponsor Pingdom Pingdom Monitoring Salesforce Salesforce PSF Sponsor Sentry Sentry Error logging StatusPage StatusPage Status page