파이썬 schedule·APScheduler 사용법: 주기 작업과 배치 자동화

간단한 개인 자동화라면 schedule, 재시작 후에도 일정 보존·동시 실행 제어·실행 누락 정책이 필요한 서비스라면 APScheduler가 적합합니다. 두 도구 모두 파이썬 프로세스가 실행 중이어야 하며, 운영 환경에서는 스케줄 코드뿐 아니라 프로세스 재시작, 로그, 타임존과 중복 실행까지 함께 설계해야 합니다.

schedule 공식 문서 확인하기

schedule과 APScheduler, 무엇을 선택할까요?

schedule 공식 문서는 이 라이브러리가 단순한 스케줄링 문제를 위한 도구이며, 재시작 뒤 일정 보존, 정확한 초 단위 실행, 기본 동시 실행과 휴일 달력이 필요하면 다른 방식을 고려하라고 안내합니다. 작은 스크립트에서 시작하더라도 이러한 요구가 예상되면 APScheduler나 운영체제의 Cron·작업 스케줄러가 더 나을 수 있습니다.

schedule로 주기 작업 만들기

설치는 pip install schedule로 진행합니다. 아래 예시는 매일 오전 9시에 보고서를 만들고, 매분 실행 대상을 확인합니다. run_pending()은 놓친 작업을 자동으로 모두 재실행하는 기능이 아니므로 프로그램이 계속 살아 있어야 합니다.

import schedule
import time
from datetime import datetime

def make_report():
    print("보고서 생성", datetime.now())

schedule.every().day.at("09:00").do(make_report)

while True:
    schedule.run_pending()
    time.sleep(1)

요일 작업은 schedule.every().monday.at("10:30").do(job), 일정 간격은 schedule.every(10).minutes.do(job)처럼 표현합니다. 작업 함수에 인수를 넘길 수 있으며, 반환값으로 schedule.CancelJob을 돌려주면 한 번 실행한 뒤 취소할 수 있습니다.

작업 시간이 길면 다음 예정 시각과 겹칠 수 있습니다. schedule은 작업 소요 시간을 자동 보정하거나 병렬 실행하지 않으므로 큐나 별도 스레드를 쓰더라도 공유 파일과 데이터베이스의 동시 접근을 직접 보호해야 합니다.

APScheduler의 트리거와 실행 방식

APScheduler 공식 사용자 가이드에서 스케줄은 실행할 작업과 트리거를 결합한 객체이고, 실제 실행 요청은 job으로 구분됩니다. 최신 문서는 동기식 Scheduler와 비동기식 AsyncScheduler를 구분하며, asyncio 기반 프로그램에서는 비동기 스케줄러 사용을 권장합니다. 설치한 버전에 따라 import와 API가 달라질 수 있으므로 해당 버전 문서를 먼저 확인하세요.

from apscheduler import Scheduler
from apscheduler.triggers.interval import IntervalTrigger

def collect_data():
    print("데이터 수집")

with Scheduler() as scheduler:
    scheduler.add_schedule(
        collect_data,
        IntervalTrigger(minutes=30),
        id="collect-data",
    )
    scheduler.run_until_stopped()

특정 시각 1회 실행에는 날짜 트리거, 일정 간격에는 interval, 달력 규칙에는 cron 계열 트리거를 사용합니다. 운영 중인 버전이 APScheduler 3.x라면 BackgroundScheduler와 add_job() 예제가 더 익숙할 수 있습니다. 4.x 계열 문법을 3.x 설치 환경에 그대로 복사하지 마세요.

스케줄러만 실행하는 전용 프로세스라면 전경 실행이 단순합니다. 웹 서버처럼 다른 일을 동시에 해야 한다면 백그라운드 실행을 사용할 수 있지만, 웹 서버 워커마다 스케줄러를 시작하면 같은 작업이 여러 번 실행될 위험이 있습니다. 스케줄러 담당 프로세스를 하나로 분리하거나 분산 잠금 전략을 사용하세요.

운영 환경 배치는 이렇게 설계하세요

1. 실행 주체를 하나로 정합니다. 애플리케이션 워커와 배치 워커를 분리하면 중복 실행을 줄일 수 있습니다.
2. 타임존을 명시합니다. 서버의 UTC와 한국 시간 차이를 고려해 Asia/Seoul 기준을 명확히 합니다.
3. 일정 저장 방식을 결정합니다. 재시작 뒤에도 일정이 필요하면 영속 데이터 저장소를 사용합니다.
4. 누락 허용 범위를 정합니다. 서버 중단 뒤 늦게 실행해도 되는지, 기한을 넘으면 버릴지 구분합니다.
5. 종료 절차를 마련합니다. 배포나 재시작 시 진행 중 작업을 안전하게 마치고 스케줄러를 종료합니다.

APScheduler는 작업별 동시 실행 수와 시작 지연 허용 시간을 제어할 수 있습니다. 실행 시간이 긴 수집 작업은 다음 실행과 겹치지 않도록 제한하고, 오래 지난 작업이 뒤늦게 몰아서 실행되는 것이 위험하다면 허용 시간을 짧게 설정해야 합니다.

작업 실패와 중복 실행을 막는 방법

스케줄 함수 안에서 예외가 발생하면 실패 사실, 실행 시각과 작업 식별자를 로그로 남기세요. 무조건 재시도하면 외부 API 호출이나 이메일 발송이 중복될 수 있으므로 작업을 여러 번 실행해도 결과가 한 번만 반영되는 멱등성을 고려해야 합니다.

import logging

logger = logging.getLogger(__name__)

def safe_job():
    try:
        run_batch()
    except TemporaryError:
        logger.exception("일시 오류: 재시도 검토")
        raise
    except Exception:
        logger.exception("배치 작업 실패")
        raise

외부 API를 호출하는 배치라면 연결·타임아웃·HTTP 오류를 분리하고 반드시 제한 시간을 지정하세요. API 응답 전에 프로세스가 멈추면 스케줄러 전체가 영향을 받을 수 있습니다.

실수 방지 체크리스트

• 프로세스가 종료돼도 실행될 것이라고 오해하지 않았는지 확인합니다.
• 운영 서버와 코드의 타임존을 명시합니다.
• 웹 서버 다중 워커에서 스케줄러가 중복 시작되지 않게 합니다.
• 작업 시간이 실행 간격보다 길어질 가능성을 점검합니다.
• 실패 로그와 알림, 재시도 상한을 정합니다.
• 동일 작업의 중복 실행에도 결과가 망가지지 않게 설계합니다.
• 배포·재시작 후 일정 복구가 필요한지 확인합니다.

공식 출처

• schedule 공식 문서
• APScheduler 공식 사용자 가이드
• Python 표준 라이브러리 sched 문서

공식 문서 확인일: 2026년 8월 30일