Install & Compatibility
Where this runs
tested against v2.1.0 · 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
muslpy 3.10–3.95 runs
installs and imports cleanly · install 0.0s · import 0.090s · 18.4MB
glibcpy 3.10–3.95 runs
installs and imports cleanly · install 1.6s · import 0.082s · 19MB
16MB installed
● package 16MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
get_description
✓ from cron_descriptor import get_description
✗ from cron_descriptor.ExpressionDescriptor 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
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))
Debug
Known issues
breakingThe 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.fixWrap `ExpressionDescriptor()` instantiation in a `try...except` block to catch parsing errors.
affects: <=1.2.x to >=1.3
breakingThe `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`.fixEnsure all cron expressions passed to the descriptor are valid, or implement `try...except` blocks around `ExpressionDescriptor` instantiation.
affects: <=1.2.x to >=1.3
breakingIn 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.fixReview `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.
affects: <=2.0.2 to >=2.0.3
breakingCustom 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.fixUpdate `except` blocks to catch the new exception names (e.g., `CronDescriptorError` instead of `CronDescriptorException`). Consult the source for specific exception names if needed.
affects: <=2.0.2 to >=2.0.3
gotchaUsing 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.fixUse `?` 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).
affects: All versions
Errors
Common errors & fixes
ModuleNotFoundError: No module named 'cron_descriptor'
The 'cron-descriptor' library is not installed in your Python environment or the environment where the script is being executed.
fixInstall the library using pip: `pip install cron-descriptor`
cron_descriptor.Exception.FormatError: An error occurred when generating the expression description. Check the cron expression syntax.
The provided cron expression string is syntactically incorrect or contains unsupported patterns, causing the library to fail during parsing.
fixReview 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.
ImportError: cannot import name 'NonExistentClass' from 'cron_descriptor' (or similar for other names)
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.
fixVerify the correct name and source of the component you intend to import. Common imports are `get_description`, `ExpressionDescriptor`, `Options`, `CasingTypeEnum`, and `DescriptionTypeEnum`.
Upgrade
Version history
2.1.0latest on PyPI · released Jun 2, 2026
Audit
Dependencies
pythonrequiredRequires Python >=3.9