{"id":5934,"library":"flask-apscheduler","title":"Flask-APScheduler","description":"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.","status":"active","version":"1.13.1","language":"python","source_language":"en","source_url":"https://github.com/viniciuschiele/flask-apscheduler","tags":["flask","scheduler","cron","background tasks","job scheduling"],"install":[{"cmd":"pip install flask-apscheduler","lang":"bash","label":"Install latest version"}],"dependencies":[{"reason":"Requires Python 3.8 or higher.","package":"Python","optional":false},{"reason":"Requires Flask 2.2.5 or higher.","package":"Flask","optional":false},{"reason":"Explicitly pinned to version 3.x due to potential breaking changes in APScheduler 4.x.","package":"APScheduler","optional":false}],"imports":[{"symbol":"APScheduler","correct":"from flask_apscheduler import APScheduler"}],"quickstart":{"code":"from flask import Flask\nfrom flask_apscheduler import APScheduler\nimport os\n\napp = Flask(__name__)\n\nclass Config:\n    SCHEDULER_API_ENABLED = True\n    # Example job store - use an appropriate one for production\n    # SCHEDULER_JOBSTORES = {\n    #    'default': {'type': 'sqlalchemy', 'url': 'sqlite:///jobs.sqlite'}\n    # }\n    # Example job execution (APScheduler default is 'threadpool')\n    # SCHEDULER_EXECUTORS = {\n    #    'default': {'type': 'threadpool', 'max_workers': 20}\n    # }\n\napp.config.from_object(Config())\n\nscheduler = APScheduler()\nscheduler.init_app(app)\nscheduler.start()\n\n# Define a simple job using the decorator\n@scheduler.task('interval', id='my_interval_job', seconds=5, misfire_grace_time=900)\ndef job_function():\n    print(f\"Hello from scheduled job! Time: {scheduler.app.config.get('SCHEDULER_API_ENABLED')}\")\n\n@app.route('/')\ndef index():\n    return \"Flask-APScheduler is running! Check console for job output.\"\n\nif __name__ == '__main__':\n    # In development, you might need to handle the reloader carefully.\n    # For simple cases, `use_reloader=False` or specific deployment setup is needed.\n    # For production, use a WSGI server (e.g., Gunicorn) and ensure only one worker starts the scheduler.\n    app.run(debug=True, use_reloader=False)\n","lang":"python","description":"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."},"warnings":[{"fix":"Upgrade to Flask-APScheduler 1.13.1 or newer for Flask 3.x compatibility. Ensure Flask >= 2.2.5 is installed.","message":"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.","severity":"breaking","affected_versions":"<1.13.1"},{"fix":"Ensure your Python environment is 3.8 or newer. Review your code for deprecated methods if upgrading from a significantly older version.","message":"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.","severity":"breaking","affected_versions":"<1.13.0"},{"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.","message":"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.","severity":"gotcha","affected_versions":"All versions that pin APScheduler to 3.x"},{"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).","message":"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.","severity":"gotcha","affected_versions":"All versions using APScheduler 3.x"},{"fix":"Register persistent jobs only through decorators or `add_job` calls, not via `SCHEDULER_JOBS` in your Flask configuration.","message":"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.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Wrap Flask context-dependent code inside jobs with `with scheduler.app.app_context():`. Remember to commit database sessions if performing DB operations.","message":"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():`.","severity":"gotcha","affected_versions":"All versions"}],"env_vars":null,"search_vec":"'activ':49 'api':36,45 'applic':21 'apschedul':3,6,14 'authent':42 'background':67 'configur':25 'cron':66 'definit':28 'enabl':16 'extens':10 'flask':2,5,9,20,30,60,64 'flask-apschedul':1,4 'includ':54 'integr':12 'job':27,39,69 'librari':15,47 'load':23 'maintain':50 'manag':38 'newer':59 'provid':33 'python':62 'recent':55 'regular':52 'releas':56 'rest':35 'schedul':17,24,65,70 'set':32 'support':41,58 'task':18,68 'updat':53 'version':63 'within':19","created_at":"2026-04-14T18:34:46.799218+00:00","updated_at":"2026-04-16T15:06:13.620174+00:00","problems":[{"fix":"Ensure the package is installed in the correct environment: `pip install Flask-APScheduler`","cause":"The `flask_apscheduler` package is not installed in the Python environment being used by your Flask application, or there's a virtual environment mismatch.","error":"ModuleNotFoundError: No module named 'flask_apscheduler'"},{"fix":"Ensure you are using a recent version of `flask-apscheduler` (1.11.0 or newer for the `@task` decorator) and that the scheduler has been initialized with `scheduler.init_app(app)` and started with `scheduler.start()`. If issues persist, consider using `scheduler.add_job()` instead of the decorator.","cause":"This error typically occurs when trying to use the `@scheduler.task` decorator for defining jobs with an older version of `flask-apscheduler` or when the scheduler object has not been properly initialized or started.","error":"AttributeError: 'APScheduler' object has no attribute 'task'"},{"fix":"Wrap your job's logic that requires the Flask application context within `with scheduler.app.app_context():` to manually push the application context.","cause":"Scheduled jobs execute in a separate thread/process outside of Flask's request context, meaning Flask-specific objects like `current_app`, `g`, or database connections managed by Flask extensions are not available by default.","error":"RuntimeError: Working outside of application context"},{"fix":"For development, ensure `FLASK_DEBUG` is not set or handle it explicitly. For production with WSGI servers like Gunicorn, ensure threads are enabled (`gunicorn --worker-class gthread --threads 4 ...` or `--enable-threads` for uWSGI). Alternatively, configure an environment variable or flag to explicitly control scheduler startup in multi-process environments.","cause":"Flask-APScheduler, by default, avoids starting the scheduler when Flask's reloader is active (`FLASK_DEBUG=True`) or in certain multi-process WSGI server configurations (like Gunicorn without `--enable-threads`), to prevent duplicate job execution.","error":"Scheduler not starting/jobs not running (e.g., with Gunicorn or FLASK_DEBUG=True and reloader)"},{"fix":"Ensure scheduled functions are module-level (not nested or lambdas) and that any arguments passed to jobs are picklable. Refactor code to avoid passing Flask-specific context objects directly as job arguments when using persistent job stores. Instead, access necessary resources by pushing an application context within the job as described in the 'Working outside of application context' fix.","cause":"This error occurs when using persistent job stores (e.g., SQLAlchemyJobStore) and a job function or its arguments contain unpicklable objects, such as `_thread.local` objects or non-module-level functions/lambdas, which cannot be serialized for storage.","error":"TypeError: can't pickle _thread._local objects"}],"ecosystem":"pypi","meta_description":null,"install_score":null,"quickstart_score":null,"quickstart_tag":null,"pypi_latest":"1.13.1","cli_name":"","cli_version":null,"type":"library","homepage":null,"github":"https://github.com/viniciuschiele/flask-apscheduler","docs":null,"changelog":null,"pypi":"https://pypi.org/project/flask-apscheduler/","npm":null,"openapi_spec":null,"status_page":null,"smithery":null,"categories":["web-framework","workflow","auth-security"],"base_url":null,"auth_type":null,"provenance":{"verified_status":"passing","verified_at":"2026-06-28","last_verified":"2026-06-28","next_check":"2026-07-28","install_tag":null}}