Flask-APScheduler

1.13.1 · active · verified Tue Apr 14

Flask-APScheduler is a Flask extension that integrates the APScheduler library, enabling scheduled tasks within Flask applications. It loads scheduler configurations and job definitions from Flask's settings, provides a REST API for managing jobs, and supports authentication for the API. The library is actively maintained with regular updates, including recent releases to support newer Flask and Python versions.

Warnings

breaking Flask-APScheduler version 1.13.0 and older versions might not be compatible with Flask 3.x. Version 1.13.1 added explicit support for Flask 3.x.
Fix: Upgrade to Flask-APScheduler 1.13.1 or newer for Flask 3.x compatibility. Ensure Flask >= 2.2.5 is installed.
breaking Version 1.13.0 dropped support for Python versions older than 3.8 and removed several deprecated methods. Attempting to run on older Python versions or using removed methods will result in errors.
Fix: Ensure your Python environment is 3.8 or newer. Review your code for deprecated methods if upgrading from a significantly older version.
gotcha Flask-APScheduler explicitly pins APScheduler to version 3.x (e.g., in 1.12.0) to prevent unexpected errors due to significant changes in APScheduler 4.x. Directly installing APScheduler 4.x might cause incompatibilities.
Fix: Do not manually install APScheduler 4.x if using Flask-APScheduler. Let Flask-APScheduler manage the APScheduler dependency or consult documentation for explicit compatibility.
gotcha When deploying with a WSGI server (like Gunicorn), ensure only one worker process starts the APScheduler instance. APScheduler 3.x is designed to run with a single worker process, and multiple instances can lead to jobs running multiple times or other inconsistencies.
Fix: Configure your WSGI server to run with a single worker process, or implement logic to ensure `scheduler.start()` is called only once (e.g., in the main process before forking workers, or within a specific worker).
gotcha If using a persistent jobstore (e.g., SQLAlchemyJobStore), do not register jobs from configuration files (e.g., `app.config`). These jobs should be registered using decorators (`@scheduler.task`) or via the `scheduler.add_job()` method to avoid duplication on application restart.
Fix: Register persistent jobs only through decorators or `add_job` calls, not via `SCHEDULER_JOBS` in your Flask configuration.
gotcha If your scheduled jobs need to interact with the Flask application context (e.g., accessing `current_app`, `Flask-SQLAlchemy`'s `db` object), you must explicitly wrap the context-dependent operations within `with scheduler.app.app_context():`.
Fix: Wrap Flask context-dependent code inside jobs with `with scheduler.app.app_context():`. Remember to commit database sessions if performing DB operations.

Install

pip install flask-apscheduler Install latest version

Imports

APScheduler

from flask_apscheduler import APScheduler

Quickstart

This quickstart demonstrates how to initialize Flask-APScheduler with a Flask application and define a recurring task using a decorator. It includes a basic configuration and ensures the scheduler starts with the application. Note the `use_reloader=False` for development to avoid multiple scheduler instances, which is a common issue.

from flask import Flask
from flask_apscheduler import APScheduler
import os

app = Flask(__name__)

class Config:
    SCHEDULER_API_ENABLED = True
    # Example job store - use an appropriate one for production
    # SCHEDULER_JOBSTORES = {
    #    'default': {'type': 'sqlalchemy', 'url': 'sqlite:///jobs.sqlite'}
    # }
    # Example job execution (APScheduler default is 'threadpool')
    # SCHEDULER_EXECUTORS = {
    #    'default': {'type': 'threadpool', 'max_workers': 20}
    # }

app.config.from_object(Config())

scheduler = APScheduler()
scheduler.init_app(app)
scheduler.start()

# Define a simple job using the decorator
@scheduler.task('interval', id='my_interval_job', seconds=5, misfire_grace_time=900)
def job_function():
    print(f"Hello from scheduled job! Time: {scheduler.app.config.get('SCHEDULER_API_ENABLED')}")

@app.route('/')
def index():
    return "Flask-APScheduler is running! Check console for job output."

if __name__ == '__main__':
    # In development, you might need to handle the reloader carefully.
    # For simple cases, `use_reloader=False` or specific deployment setup is needed.
    # For production, use a WSGI server (e.g., Gunicorn) and ensure only one worker starts the scheduler.
    app.run(debug=True, use_reloader=False)

view raw JSON →