Awesome Open Source
Awesome Open Source


Simple Flask scheduled tasks without extra daemons

PyPI PyPI - Python Version Github Action Supported Platforms

This project is strongly inspired by django-crontab, and only works on Python 3.5+. Due to the coming EOL of Python 2 on 2020/01/01, there is no plan for Python 2 support.

Quick Start

Install via pip:

$ pip install flask-crontab

Instantiate the extension in your after the creation of Flask app:

from flask import Flask
from flask_crontab import Crontab

app = Flask(__name__)
crontab = Crontab(app)

If you are using App Factory pattern, you can also register the extension later:

crontab = Crontab()

def create_app():

Now create a scheduled job:

@crontab.job(minute="0", hour="6")
def my_scheduled_job():

An app context is automatically activated for every job run, so that you can access objects that are attached to app context. Then add the job to crontab:

$ flask crontab add

That's it! If you type in crontab -l in your shell, you can see some new lines created by flask-crontab.

Show jobs managed by current app:

$ flask crontab show

Purge all jobs managed by current app:

$ flask crontab remove

Run a specific job given by hash:

$ flask crontab run <job_hash>

See supported options via --help for every commands.

Decorator API

def job(
    minute: str = "*",
    hour: str = "*",
    day: str = "*",
    month: str = "*",
    day_of_week: str = "*",
    args: Tuple[Any, ...] = (),
    kwargs: Optional[Dict[str, Any]] = None,
) -> Callable:

The decorator accepts five arguments minute, hour, day, month, day_of_month, which are the same as crontab 5-parts time format. Any part that is not given defaults to *. Besides, job decorator accepts args and kwargs which will be passed to the decorated function as positional arguments and keywords arguments, respectively.


Config item Description Default value
CRONTAB_EXECUTABLE The absolute path of crontab /usr/bin/crontab
CRONTAB_LOCK_JOBS Whether lock jobs when running False


This project is publised under MIT license.

Get A Weekly Email With Trending Projects For These Topics
No Spam. Unsubscribe easily at any time.
Python (1,136,873
Flask (9,793
Extension (3,525
Crontab (365
Background Jobs (152
Related Projects