Home > python > APScheduler examples

APScheduler examples

Update (20190626): this post is deprecated! I wrote a new post that describes the new version of APScheduler (version 3). See the updated post here.

Advanced Python Scheduler (APScheduler) is a light but powerful in-process task scheduler that lets you schedule functions (or any other python callables) to be executed at times of your choosing.” (source)

The simplest way to schedule jobs using the built-in triggers is to use one of the shortcut methods provided by the scheduler:

Let’s see an example to each.

(1) simple date-based scheduling

The official doc. is here. “This is the simplest possible method of scheduling a job. It schedules a job to be executed once at the specified time. This is the in-process equivalent to the UNIX “at” command.

#!/usr/bin/env python

import sys
from time import sleep
from apscheduler.scheduler import Scheduler
sched = Scheduler()
sched.start()        # start the scheduler

# define the function that is to be executed
# it will be executed in a thread by the scheduler
def my_job(text):
    print text

def main():
    # job = sched.add_date_job(my_job, datetime(2013, 8, 5, 23, 47, 5), ['text'])
    job = sched.add_date_job(my_job, '2013-08-05 23:47:05', ['text'])
    while True:
        sys.stdout.write('.'); sys.stdout.flush()


if __name__ == "__main__":

Meaning: at the specified date and time, call the function my_job with the parameter “text“. The line with “sched.add_date_job” registers the task and the execution of the script goes on with the next line! If it were the last line, the script would terminate. Thus we need an infinite loop too. At the specified time, the registered function will be triggered and executed in a thread, but the infinite loop goes on parallelly.

(2) interval-based scheduling

The official doc. is here. “This method schedules jobs to be run on selected intervals. The execution of the job starts after the given delay, or on start_date if specified. After that, the job will be executed again after the specified delay.

The frame of the source code is the same as in the first example. Here I will only show the difference.

# from now on, execute my_job every minute
job = sched.add_interval_job(my_job, minutes=1, args=['text'])

# or:

# start at start_date (my_job is called) and then execute my_job every minute
job = sched.add_interval_job(my_job, minutes=1, start_date='2013-08-06 00:09:12', args=['text'])

In the first case: if you launch the script at 09:10:12 (hh:mm:ss), my_job will be called at 09:11:12 for the first time, then at 09:12:12, 09:13:12, etc.

In the second case: you specify when to call my_job for the first time (on August 6, 2013 at 00:09:12), then it will be executed again at 00:10:12, 00:11:12, etc.

(3) cron-style scheduling

The official doc. is here. “This is the most powerful scheduling method available in APScheduler. You can specify a variety of different expressions on each field, and when determining the next execution time, it finds the earliest possible time that satisfies the conditions in every field. This behavior resembles the “Cron” utility found in most UNIX-like operating systems.

The frame of the source code is the same as in the first example. Here I will only show the difference.

job = sched.add_cron_job(my_job, minute="*/15", args=['text'])

The syntax is similar to cron’s syntax. Here is a visual crontab utility called corntab.

The example above means: execute my_job in each hour at every 15 minutes. So, if you launch the script at Xh8 (8 minutes after X hour), it will be executed for the first time at Xh15, then at Xh30, Xh45, (X+1)h0, (X+1)h15, etc.


If you want to unregister a task, do this:


This is why we stored the returned values in a variable called “job“.

You can also print the scheduled jobs in a human-readable format. It also prints when the job is executed next time, so it’s great for debugging:

job = sched.add_...

Sample output:

Jobstore default:
    my_job (trigger: date[2013-08-06 23:47:05], next run at: 2013-08-06 23:47:05)
Categories: python Tags: , , ,
  1. December 20, 2013 at 13:56

    Can I schedule a python script ?
    Instead of using my_job I need to use test.py script and it will take input.txt as argument.

    will following line work?

    job = sched.add_interval_job(test.py, minutes=1, args=['input.txt'])
    • December 20, 2013 at 14:21

      The job should be the name of a function. However, you could do something like this:

      def my_job(fname):
          cmd = "./test.py {param}".format(param=fname)
      job = sched.add_interval_job(my_job, minutes=1, args=['input.txt'])

      From the scheduled function you make an external call. I didn’t try it but it should work :)

  2. September 11, 2014 at 06:44

    I have windows, I copy the files the librery Scheduler, but python don’t want to identify the files, Also I change for import schedulers because it’s the name of file.

  3. December 28, 2014 at 21:38

    Really nice discussion, but I think it’s a couple of versions back now. There’s only add_job now with different kinds of triggers. (No add_interval_job, add_cron_job, etc). Maybe you can update it?

    Also, the links at the top don’t work anymore.

    • December 28, 2014 at 21:42

      Thanks for the feedback. I haven’t used it since then so I wasn’t aware of the changes. When I find some time, I will try to update it.

  4. October 30, 2015 at 14:59

    What’s the point of the shcedulers if you must open Phyton to run the code?
    I need to autorefresh my pivot-tables every day, I make this code

    import schedule
    import time
    from win32com.client import Dispatch
    def job():
        xl = Dispatch('Excel.Application')  
        wb = xl.Workbooks.Open(r'C:\Users\VentsislavI\Desktop\proba.xlsx')  
    while True:

    but how to execute this without starting Python?

    • October 30, 2015 at 15:36

      It seems that you use Windows. I can only give you a tip under Linux since I don’t use Windows (except for gaming). If you need to run a script once a day, under Linux the best solution is to put it in your crontab file. If you put a scheduler in your Python code, then obviously the Python code must be running. What’s the point? For instance you want to execute different jobs, like do job A every 10 minutes, do job B every hour, and do job C every 20 minutes. With a Python script that uses a scheduler you can do it easily, but the script must be running.

  5. January 29, 2017 at 08:36

    Really nice example, scheduler is common feature needed for system. Thank’s a lot

  6. Leonard Gabrielson
    June 22, 2019 at 18:02

    Can you please make another article like this for APScheduler 3. This is very straight forward and easy to understand whereas I find the official documentation impossible to comprehend. Thanks very much

  1. June 26, 2019 at 13:01

Leave a Reply

Please log in using one of these methods to post your comment:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out /  Change )

Google photo

You are commenting using your Google account. Log Out /  Change )

Twitter picture

You are commenting using your Twitter account. Log Out /  Change )

Facebook photo

You are commenting using your Facebook account. Log Out /  Change )

Connecting to %s

%d bloggers like this: