APScheduler

Warnings

• breaking APScheduler 4.x (a complete rewrite) is in pre-release and has a completely different API. pip install APScheduler installs 3.x — NOT 4.x. 4.x docs and tutorials showing from apscheduler import Scheduler will raise ImportError on 3.x installs.
  Fix: For production: pip install APScheduler installs stable 3.x. For 4.x pre-release: pip install 'APScheduler>=4.0a1'. The 3.x and 4.x APIs are completely incompatible.
• gotcha scheduler.start() must be called explicitly. Creating a scheduler and adding jobs without calling start() does nothing — jobs never run.
  Fix: Always call scheduler.start() after adding jobs. For Flask/Django: call it in app startup, not module level.
• gotcha Jobs are lost on restart unless a persistent job store (SQLAlchemy, Redis, MongoDB) is configured. The default MemoryJobStore holds jobs only in RAM.
  Fix: Configure a persistent job store: scheduler = BackgroundScheduler(jobstores={'default': SQLAlchemyJobStore(url='sqlite:///jobs.sqlite')})
• gotcha Running multiple processes each with their own scheduler (e.g. gunicorn with multiple workers) causes duplicate job execution. APScheduler 3.x has no inter-process coordination.
  Fix: Run the scheduler in a single dedicated process. Use a persistent job store with coalesce=True and max_instances=1. Or use a task queue (Celery, RQ) for multi-process environments.
• gotcha BlockingScheduler blocks the main thread — use it only when the scheduler IS the application. BackgroundScheduler runs in a daemon thread and is suitable for running alongside a web app.
  Fix: Web apps: use BackgroundScheduler. Standalone scheduler scripts: use BlockingScheduler. Async apps: use AsyncIOScheduler.
• gotcha All times are naive (timezone-unaware) unless you configure a timezone. Scheduled jobs may run at wrong times during DST transitions.
  Fix: Always set timezone: BackgroundScheduler(timezone='UTC') or use pytz: BackgroundScheduler(timezone=pytz.timezone('America/New_York'))

Install

• pip install APScheduler Installs 3.x stable (NOT 4.x)
• pip install APScheduler[sqlalchemy] With SQLAlchemy persistent job store
• pip install APScheduler[redis] With Redis job store

Imports

• BackgroundScheduler

  from apscheduler.schedulers.background import BackgroundScheduler
  from apscheduler.triggers.cron import CronTrigger
  from apscheduler.triggers.interval import IntervalTrigger
  
  # 3.x API — the current stable API
  scheduler = BackgroundScheduler()
  
  # Add jobs
  scheduler.add_job(my_function, 'interval', seconds=30)
  scheduler.add_job(my_function, CronTrigger(hour=9, minute=0))  # 9am daily
  scheduler.add_job(my_function, 'cron', hour=9, minute=0)       # same
  
  # Must call start() explicitly
  scheduler.start()
  
  # Shutdown cleanly
  import atexit
  atexit.register(lambda: scheduler.shutdown())

  pip install APScheduler installs 3.x. The 4.x API (from apscheduler import Scheduler) requires a pre-release install. They are completely different — 4.x removed BackgroundScheduler, BlockingScheduler, AsyncIOScheduler in favor of a single Scheduler class.

Quickstart

3.x stable API. BackgroundScheduler runs in a thread. Always call start() and shutdown().

from apscheduler.schedulers.background import BackgroundScheduler
from datetime import datetime
import time

def job_function():
    print(f'Job ran at {datetime.now()}')

# BackgroundScheduler runs in a daemon thread
scheduler = BackgroundScheduler()

# Interval trigger
scheduler.add_job(job_function, 'interval', seconds=10, id='my_job')

# Cron trigger (every day at 9:30am)
scheduler.add_job(job_function, 'cron', hour=9, minute=30)

# Date trigger (one-off)
from datetime import timedelta
scheduler.add_job(
    job_function,
    'date',
    run_date=datetime.now() + timedelta(minutes=1)
)

# Must start explicitly
scheduler.start()
print('Scheduler started. Press Ctrl+C to exit.')

try:
    while True:
        time.sleep(1)
except KeyboardInterrupt:
    scheduler.shutdown()