APScheduler is an MIT-licensed Python library that provides task scheduling and job queuing, scaling from a single-process script to multi-node deployments that share a persistent data store.
What it is
Advanced Python Scheduler is a task scheduler and task queue system written in Python and published under the name apscheduler. It comes in both synchronous and asynchronous flavors, which makes it usable in traditional thread-based applications and in asynchronous applications built on asyncio or Trio. It can also be used purely as a job queuing system when scheduling is not required at all. Documentation and examples cover integration with WSGI and ASGI compatible web applications, and the project's documentation lives at https://apscheduler.readthedocs.io/.
The problem it solves is the scheduling code every Python application otherwise writes for itself, together with the separate plumbing needed to run jobs on a timer outside the process. APScheduler supplies the scheduling mechanisms directly, with cron-style, interval-based, calendar-based, and one-off triggers, and it persists schedules and jobs so that they survive process and node restarts. Because that persistent store can be shared, multiple schedulers and workers can be deployed against it to provide a degree of high availability and horizontal scaling, rather than each instance holding its own private, unshared timer state.
Key capabilities
- Built-in triggers cover cron-style scheduling, interval-based scheduling, calendar-based scheduling that runs on intervals of X years, months, weeks, or days always at the same time of day, and one-off scheduling at a specific date and time.
- Combining triggers allow different scheduling mechanisms to be combined, and custom trigger classes can be written and treated no differently from the built-in ones.
- Persistent storage of schedules and jobs uses PostgreSQL, MySQL and derivatives, SQLite, or MongoDB, so schedules survive process and node restarts and can be shared among scheduler and worker instances.
- Event brokers for scenarios with multiple schedulers or workers are PostgreSQL, Redis, and MQTT.
- For a given task (function), the maximum number of simultaneous jobs can be limited, and the amount of time a job is allowed to start late can be limited.
- Jitter adds adjustable, random delays to the run time of each scheduled job.
- The library can be used solely as a job queuing system with no task scheduling at all.
Who uses it and how
- Trivial, single-process cases run the scheduler inside one application process with no shared infrastructure.
- Large deployments spanning multiple nodes run several schedulers and workers against one shared data store for high availability and horizontal scaling.
- Traditional, thread-based Python applications use the synchronous flavor, while asyncio or Trio applications use the asynchronous flavor.
- Teams embedding scheduling in web applications use the documented WSGI or ASGI integration examples.
Getting started
Installation, configuration, and examples are documented at https://apscheduler.readthedocs.io/, with the distribution published as apscheduler. The facts list no Docker image, Compose file, or hosted option, so deployment is as a Python package inside the application.
How it compares
No list of paid products replaced by this project is provided, and the facts name no comparable scheduling tools. Within this registry it stands alone in the Business Software / Scheduling & Event Management category.
When to use it — and when not to
A self-hoster who wants persistent, shareable schedules must operate a database such as PostgreSQL, MySQL, SQLite, or MongoDB, and multi-scheduler or multi-worker deployments additionally require an event broker such as PostgreSQL, Redis, or MQTT. Anyone evaluating the v4.0 series should note the README's explicit warning that it is a pre-release which may change in a backwards incompatible fashion with no migration pathway, and that it must not be used in production. The licence is MIT, which is unambiguous, but the pre-release status is the clearest reason to be cautious.
project readme (upstream, from github) — read inline
.. image:: https://github.com/agronholm/apscheduler/actions/workflows/test.yml/badge.svg
:target: https://github.com/agronholm/apscheduler/actions/workflows/test.yml
:alt: Build Status
.. image:: https://coveralls.io/repos/github/agronholm/apscheduler/badge.svg?branch=master
:target: https://coveralls.io/github/agronholm/apscheduler?branch=master
:alt: Code Coverage
.. image:: https://readthedocs.org/projects/apscheduler/badge/?version=latest
:target: https://apscheduler.readthedocs.io/en/master/?badge=latest
:alt: Documentation
.. warning:: The v4.0 series is provided as a pre-release and may change in a
backwards incompatible fashion without any migration pathway, so do NOT use this
release in production!
Advanced Python Scheduler (APScheduler) is a task scheduler and task queue system for
Python. It can be used solely as a job queuing system if you have no need for task
scheduling. It scales both up and down, and is suitable for both trivial, single-process
use cases as well as large deployments spanning multiple nodes. Multiple schedulers and
workers can be deployed to use a shared data store to provide both a degree of high
availability and horizontal scaling.
APScheduler comes in both synchronous and asynchronous flavors, making it a good fit for
both traditional, thread-based applications, and asynchronous (asyncio or Trio_)
applications. Documentation and examples are provided for integrating with either WSGI_
or ASGI_ compatible web applications.
Support is provided for persistent storage of schedules and jobs. This means that they
can be shared among multiple scheduler/worker instances and will survive process and
node restarts.
The built-in persistent data store back-ends are:
- PostgreSQL
- MySQL and derivatives
- SQLite
- MongoDB
The built-in event brokers (needed in scenarios with multiple schedulers and/or
workers):
The built-in scheduling mechanisms (triggers) are:
- Cron-style scheduling
- Interval-based scheduling (runs tasks on even intervals)
- Calendar-based scheduling (runs tasks on intervals of X years/months/weeks/days,
always at the same time of day)
- One-off scheduling (runs a task once, at a specific date/time)
Different scheduling mechanisms can even be combined with so-called combining triggers
(see the documentation_ for details).
You can also implement your custom scheduling logic by building your own trigger class.
These will be treated no differently than the built-in ones.
Other notable features include:
- You can limit the maximum number of simultaneous jobs for a given task (function)
- You can limit the amount of time a job is allowed to start late
- Jitter (adjustable, random delays added to the run time of each scheduled job)
.. _Trio: https://pypi.org/project/trio/
.. _WSGI: https://wsgi.readthedocs.io/en/latest/what.html
.. _ASGI: https://asgi.readthedocs.io/en/latest/index.html
.. _documentation: https://apscheduler.readthedocs.io/en/master/
Documentation
Documentation can be found
here _.
Source
The source can be browsed at Github _.
Reporting bugs
A bug tracker _ is provided by
GitHub.
Getting help
If you have problems or other questions, you can either:
- Ask in the
apscheduler _ room on Gitter
- Post a question on
GitHub discussions_, or
- Post a question on StackOverflow_ and add the
apscheduler tag
.. _GitHub discussions: https://github.com/agronholm/apscheduler/discussions/categories/q-a
.. _StackOverflow: http://stackoverflow.com/questions/tagged/apscheduler