Cron Descriptor

2.0.8 verified Tue May 12 auth: no python install: verified

A Python library that converts cron expressions into human readable strings. As of version 2.0.8, it supports Python 3.9 - 3.14 and offers localization for approximately 31 languages. The library is actively maintained with frequent releases.

pip install cron-descriptor

Common errors

error ModuleNotFoundError: No module named 'cron_descriptor' ↓

cause The 'cron-descriptor' library is not installed in your Python environment or the environment where the script is being executed.

fix

Install the library using pip: pip install cron-descriptor

error cron_descriptor.Exception.FormatError: An error occurred when generating the expression description. Check the cron expression syntax. ↓

cause The provided cron expression string is syntactically incorrect or contains unsupported patterns, causing the library to fail during parsing.

fix

Review and correct the cron expression string to adhere to standard cron syntax. Ensure it's a valid 5, 6 (with seconds or year), or 7 part cron expression.

error ImportError: cannot import name 'NonExistentClass' from 'cron_descriptor' (or similar for other names) ↓

cause You are attempting to import a class, function, or variable name that does not exist or is not directly exposed by the 'cron_descriptor' module.

fix

Verify the correct name and source of the component you intend to import. Common imports are get_description, ExpressionDescriptor, Options, CasingTypeEnum, and DescriptionTypeEnum.

Warnings

breaking The parsing of cron expressions moved from `ExpressionDescriptor.get_description()` to the `ExpressionDescriptor` constructor in version 1.3. This means parsing exceptions are now thrown when creating an `ExpressionDescriptor` instance, not when calling `get_description()`. Update your exception handling logic accordingly. ↓

fix Wrap `ExpressionDescriptor()` instantiation in a `try...except` block to catch parsing errors.

breaking The `throw_exception_on_parse_error` option was removed in version 1.3. The library now always throws an exception if a cron expression cannot be parsed, effectively behaving as if `throw_exception_on_parse_error=True`. ↓

fix Ensure all cron expressions passed to the descriptor are valid, or implement `try...except` blocks around `ExpressionDescriptor` instantiation.

breaking In version 2.0.3, the `Options` constructor parameters (`locale_code`, `use_24hour_time_format`) now explicitly override auto-detected system locale settings. If you previously relied on auto-detection and then set these in `Options` objects, their behavior might change to reflect the explicit settings. ↓

fix Review `Options` constructor usage to ensure desired locale and time format behavior. Explicitly set `locale_code` if you need a specific localization, or omit it to rely on auto-detection.

breaking Custom exceptions within the library were renamed from `*Exception` (e.g., `CronDescriptorException`) to `*Error` (e.g., `CronDescriptorError`) in version 2.0.3. Update `except` clauses to catch the new exception names. ↓

fix Update `except` blocks to catch the new exception names (e.g., `CronDescriptorError` instead of `CronDescriptorException`). Consult the source for specific exception names if needed.

gotcha Using both Day of Month and Day of Week fields with explicit values (e.g., `1 1 1 1 1`) can be ambiguous in cron. While this library generally handles `?` to signify 'no specific value' for one of them, be aware that other cron parsers or environments might have different interpretations or stricter validation. ↓

fix Use `?` in either the Day of Month or Day of Week field if you intend for one to be ignored. For example, `0 0 1 * ?` (1st of every month, any day of week) or `0 0 ? * MON` (every Monday, any day of month).

Install compatibility verified last tested: 2026-05-12

python os / libc status wheel install import disk

3.10 alpine (musl) wheel - 0.06s 18.4M

3.10 alpine (musl) - - 0.06s 18.4M

3.10 slim (glibc) wheel 1.5s 0.04s 19M

3.10 slim (glibc) - - 0.04s 19M

3.11 alpine (musl) wheel - 0.12s 20.4M

3.11 alpine (musl) - - 0.14s 20.4M

3.11 slim (glibc) wheel 1.6s 0.11s 21M

3.11 slim (glibc) - - 0.10s 21M

3.12 alpine (musl) wheel - 0.10s 12.2M

3.12 alpine (musl) - - 0.10s 12.2M

3.12 slim (glibc) wheel 1.5s 0.11s 13M

3.12 slim (glibc) - - 0.11s 13M

3.13 alpine (musl) wheel - 0.10s 12.0M

3.13 alpine (musl) - - 0.09s 11.9M

3.13 slim (glibc) wheel 1.5s 0.09s 12M

3.13 slim (glibc) - - 0.09s 12M

3.9 alpine (musl) wheel - 0.05s 17.9M

3.9 alpine (musl) - - 0.06s 17.9M

3.9 slim (glibc) wheel 1.8s 0.05s 18M

3.9 slim (glibc) - - 0.05s 18M

Imports

get_description
wrong
```
from cron_descriptor.ExpressionDescriptor import get_description
```
correct
```
from cron_descriptor import get_description
```
Direct import from the top-level package is the current standard. Older versions might have had deeper imports, or some examples might mistakenly show a submodule.

ExpressionDescriptor

from cron_descriptor import ExpressionDescriptor

Options
```
from cron_descriptor import Options
```

CasingTypeEnum

from cron_descriptor import CasingTypeEnum

DescriptionTypeEnum

from cron_descriptor import DescriptionTypeEnum

Quickstart last tested: 2026-04-24

Demonstrates basic usage with the `get_description` function and the `ExpressionDescriptor` class, including how to customize output with `Options` for casing, 24-hour format, and locale.

from cron_descriptor import get_description, ExpressionDescriptor, Options, CasingTypeEnum, DescriptionTypeEnum

# Simple usage
print(get_description("* 2 3 * *"))

# Using ExpressionDescriptor class
descriptor_instance = ExpressionDescriptor("* 2 3 * *")
print(str(descriptor_instance))

# Advanced usage with Options
options = Options()
options.casing_type = CasingTypeEnum.Sentence
options.use_24hour_time_format = True
options.locale_code = 'en' # Explicitly set locale for consistency

advanced_descriptor = ExpressionDescriptor("*/10 * * * *", options)
print(advanced_descriptor.get_description(DescriptionTypeEnum.FULL))