APScheduler

Common errors

• ModuleNotFoundError: No module named 'apscheduler.schedulers'; 'apscheduler' is not a package

  cause This error occurs when a script named 'apscheduler.py' in the project directory shadows the APScheduler package, causing import conflicts.
  fix Rename or remove the 'apscheduler.py' file in your project directory to avoid naming conflicts with the APScheduler package.

• AttributeError: 'BackgroundScheduler' object has no attribute 'add_cron_job'

  cause The 'add_cron_job' method was removed in APScheduler 3.x; the correct method to add cron jobs is 'add_job' with 'trigger='cron''.
  fix Replace 'add_cron_job' with 'add_job' and specify 'trigger='cron'' in your code.

• ImportError: No module named 'apscheduler'

  cause This error indicates that the APScheduler package is not installed in the Python environment.
  fix Install APScheduler using 'pip install apscheduler'.

• AttributeError: module 'apscheduler' has no attribute 'Scheduler'

  cause Users are attempting to import the `Scheduler` class directly from the `apscheduler` module, which was a pattern in APScheduler 2.x but is incorrect for the 3.x series. In APScheduler 3.x, scheduler classes are located in specific submodules.
  fix Import the specific scheduler class from its correct submodule, such as `from apscheduler.schedulers.background import BackgroundScheduler` or `from apscheduler.schedulers.blocking import BlockingScheduler`.

• TypeError: func must be callable

  cause The function intended to be scheduled is being called immediately when passed to `add_job` (e.g., `my_function()`) instead of passing a reference to the function itself (`my_function`). This results in the return value of `my_function()` being passed, which is likely not a callable object.
  fix Pass the function reference without parentheses: `scheduler.add_job(my_function, 'interval', seconds=5)`.

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
  wrong:

  # 4.x API (pre-release, NOT installed by pip install APScheduler):
  from apscheduler import Scheduler  # ImportError on 3.x install
  with Scheduler() as scheduler:
      scheduler.add_schedule(my_function, IntervalTrigger(seconds=30))
      scheduler.run_until_stopped()

  correct:

  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()