A Python library that converts cron expressions into human readable strings.

cron-descriptor, cron-expression, python
pip install cron-descriptor==1.4.0


Cron Descriptor

Python tests Donate

A Python library that converts cron expressions into human readable strings. Ported to Python from https://github.com/bradyholt/cron-expression-descriptor.

Author: Adam Schubert (https://www.salamek.cz)
Original Author & Credit: Brady Holt (http://www.geekytidbits.com)
License: MIT


  • Supports all cron expression special characters including * / , - ? L W, #
  • Supports 5, 6 (w/ seconds or year), or 7 (w/ seconds and year) part cron expressions
  • Provides casing options (Sentence, Title, Lower, etc.)
  • Localization with support for 17 languages
  • Supports Python 2.7 - 3.10


Using PIP

pip install cron-descriptor

Usage example


from cron_descriptor import get_description, ExpressionDescriptor

print(get_description("* 2 3 * *"))


print(str(ExpressionDescriptor("* 2 3 * *")))


# Consult Options.py/CasingTypeEnum.py/DescriptionTypeEnum.py for more info
from cron_descriptor import Options, CasingTypeEnum, DescriptionTypeEnum, ExpressionDescriptor

descriptor = ExpressionDescriptor(
    expression = "*/10 * * * *",
    casing_type = CasingTypeEnum.Sentence,
    use_24hour_time_format = True

# GetDescription uses DescriptionTypeEnum.FULL by default:

# Or passing Options class as second argument:

options = Options()
options.casing_type = CasingTypeEnum.Sentence
options.use_24hour_time_format = True
descriptor = ExpressionDescriptor("*/10 * * * *", options)

Languages Available

Language Locale Code Contributor
English en Brady Holt
Brazilian pt_PT Renato Lima
Chinese Simplified zh_CN Star Peng
Spanish es_ES Ivan Santos
Norwegian nb_NO Siarhei Khalipski
Turkish tr_TR Mustafa SADEDİL
Dutch nl_NL TotalMace
Russian ru_RU LbISS
French fr_FR Arnaud TAMAILLON
German de_DE Michael Schuler
Ukrainian uk_UA Taras
Italian it_IT rinaldihno
Czech cs_CZ Adam Schubert
Swedish sv_SE Åke Engelbrektson
Tamil ta_IN Sankar Hari
Persian fa_IR M. Yas. Davoodeh
Korean ko_KR KyuJoo Han
Japanese ja_JP Tho Nguyen

Original Source


Running Unit Tests

python setup.py test


cron-descriptor is using Gettext for translations.

To create new translation or edit existing one, i suggest using Poedit.

You can copy/rename and translate any file from locale directory:

cp ./cron_descriptor/locale/de_DE.po ./cron_descriptor/locale/YOUR_LOCALE_CODE.po
poedit ./cron_descriptor/locale/YOUR_LOCALE_CODE.po

or you can generate new untranslated *.po file from sources by running in cron_descriptor directory:

cd cron_descriptor
xgettext *.py -o locale/YOUR_LOCALE_CODE.po

Generating *.mo file from *.po file. In root directory run command:

msgfmt -o cron_descriptor/locale/YOUR_LOCALE_CODE.mo cron_descriptor/locale/YOUR_LOCALE_CODE.po


All suggestions and PR's are welcomed

Just clone this repository and register pre-commit hook by running:

ln -s ../../pre-commit.sh .git/hooks/pre-commit

Then install dev requirements:

pip install pep8
pip install flake8
pip install pep8-naming