빠른 시작

pip install pykorail

from datetime import datetime
from pykorail import Korail

with Korail.logged_in("me@example.com", "password") as korail:
    trains = korail.trains.search("서울", "부산", depart_after=datetime(2026, 4, 1, 9, 0))
    for train in trains:
        print(train)

[KTX 101]  04/01 09:00~12:30  서울~부산  특실 가능, 일반실 가능 (3시간 30분)
[KTX 103]  04/01 10:00~13:30  서울~부산  특실 매진, 일반실 가능 (3시간 30분)
[KTX 105]  04/01 11:00~14:35  서울~부산  특실 가능, 일반실 매진 (3시간 35분)

[!WARNING] 코레일과 아무 관련 없는 비공식 라이브러리입니다. 문서화되지 않은 앱 API 를 쓰기 때문에 코레일이 앱을 바꾸면 예고 없이 멈출 수 있습니다. 이용 약관과 관련 법령을 지키는 것은 사용자 책임이며, 과도한 자동 요청은 계정 제재로 이어질 수 있습니다.

할 수 있는 것

표 예매하고 결제하기

from pykorail import AdultPassenger, Card, ChildPassenger

trains = korail.trains.search(
    "서울",
    "부산",
    depart_after=datetime(2026, 4, 1, 9, 0),
    passengers=[AdultPassenger(2), ChildPassenger(1)],
)

reservation = korail.reservations.create(trains[0])
print(reservation)
# [KTX 101] … 119600원(3석), 구입기한 4월 1일 09:20

korail.reservations.pay(
    reservation,
    Card(number="1234567812345678", password="12", verify_number="900101", expire="2812"),
)

import time
from pykorail import NoResultsError, PastDepartureError

departure = datetime(2026, 4, 1, 9, 0)

while True:
    try:
        trains = korail.trains.search("서울", "부산", depart_after=departure)
    except NoResultsError:
        time.sleep(30)  # 서버에 부담 주지 않게 넉넉히 쉬세요
        continue
    except PastDepartureError:
        break  # 열차가 이미 떠났습니다 — 무한정 돌지 않도록

    korail.reservations.create(trains[0])
    break

trains = korail.trains.search("서울", "부산", include_waiting_list=True)
waitable = [t for t in trains if not t.has_seat() and t.has_waiting_list()]

reservation = korail.reservations.create(waitable[0])
assert reservation.is_waiting

for reservation in korail.reservations.all():
    print(reservation.train.dep_name, "→", reservation.train.arr_name, reservation.price)

for ticket in korail.tickets.all():
    print(ticket.ticket_no, ticket.car_no, ticket.seat_no)
    korail.tickets.refund(ticket)  # 환불

from pykorail.device import profile_by_id, random_profile

profile = profile_by_id(saved_id) or random_profile()
korail = Korail(device_profile=profile)

알아두면 좋은 것

from pykorail import KorailError, SoldOutError

try:
    korail.reservations.create(train)
except SoldOutError:
    ...  # 매진 — 다음 열차로
except KorailError as exc:
    print(exc.msg, exc.code)  # 코레일이 준 메시지와 코드

문서

자주 묻는 것

개발

파이썬 3.10 이상 (3.10 – 3.14 에서 테스트합니다).

uv sync --all-extras
uv run ruff format && uv run ruff check && uv run ty check && uv run pytest

네 개를 전부 통과해야 합니다. 커버리지 하한 90%, 현재 96%.

기여를 환영합니다 — CONTRIBUTING.md 부터 보세요. 새 엔드포인트는 공식 코레일톡+ APK 를 디컴파일해 경로와 폼 필드를 확인한 뒤에만 추가합니다.

릴리스

버전의 유일한 출처는 git 태그입니다. 파일을 손으로 고칠 필요가 없습니다.

git tag v0.2.0 && git push origin v0.2.0

태그를 밀면 전 버전 게이트 → 보안 스캔 → 빌드 → PyPI 업로드 → 릴리스 노트 생성이 자동으로 돕니다.