PyKrx

한국 증권시장(KRX, Naver)에서 주식·채권 데이터를 스크래핑하는 Python 라이브러리입니다.

☕ 후원하기

프로젝트가 도움이 되셨다면 개발자를 응원해주세요!

⚠️ 면책 및 주의사항

• 본 라이브러리는 KRX(한국거래소) 및 Naver의 데이터를 스크래핑하며, 데이터의 저작권은 각 제공처에 있습니다.
• 도의적으로 무분별한 API 호출을 자제해 주시기 바랍니다.
• 제공되는 데이터는 공식 데이터와 차이가 있을 수 있으며, 참고용으로만 사용해야 합니다.
• 투자 손실이나 법적 책임은 사용자에게 있으며, 상업적 용도 사용 시 데이터 제공처의 약관을 준수해야 합니다.
• 후원은 데이터에 대한 대가가 아니며, 오픈소스 유지보수를 위한 개발자 응원 목적으로만 사용됩니다.

1 환경설정

1.1 Installation

pykrx는 pip을 사용해서 쉽게 설치할 수 있습니다.

pip install pykrx

pykrx는 증권시장의 주식 정보를 스크래핑 합니다. 모듈의 사용은 import부터 시작합니다.

from pykrx import stock
from pykrx import bond

1.2 개발 환경 설정 (Development environment)

로컬 개발 및 테스트를 위한 권장 절차입니다. 프로젝트 루트에서 아래 명령을 실행하세요.

# 가상환경 생성 및 활성화
python3 -m venv .venv
source .venv/bin/activate  # macOS / Linux
.venv\Scripts\activate     # Windows (PowerShell)

# 개발 의존성 포함 설치
pip install -e .[dev]

# pre-commit 훅 설치
pre-commit install

# Ruff로 코드 자동수정(포맷/정리) - 선택사항
ruff check --fix .
ruff format .

# 전체 테스트 실행
pytest -v

설명:

• pip install -e .[dev] — 개발 모드 설치 + dev 의존성(pytest, ruff, pre-commit) 자동 설치
• 모든 설정은 pyproject.toml에서 관리됩니다
• VS Code 사용 시: ruff 익스텐션 설치하면 저장 시 자동 포맷 적용

1.3 환경변수 설정 (Required Environment Variables)

KRX 로그인이 필요한 API를 사용하려면 아래 두 환경변수를 반드시 설정해야 합니다.

변수명	필수 여부	설명
KRX_ID	필수	KRX(한국거래소) 회원 로그인 ID
KRX_PW	필수	KRX(한국거래소) 회원 로그인 비밀번호

환경변수가 설정되지 않으면 KRX 로그인이 실패하고 인증이 필요한 데이터를 조회할 수 없습니다.

# macOS / Linux
export KRX_ID="your_krx_id"
export KRX_PW="your_krx_password"

# Windows (PowerShell)
$env:KRX_ID="your_krx_id"
$env:KRX_PW="your_krx_password"

# Windows (Command Prompt)
set KRX_ID=your_krx_id
set KRX_PW=your_krx_password

참고: .env 파일을 사용하는 경우 python-dotenv 등을 활용해 로드하세요. .env 파일은 절대 버전 관리(git)에 포함하지 마세요.

지원 Python 버전

이 프로젝트는 다음 Python 버전을 지원합니다:

• 런타임 최소 요구: >=3.10 (pyproject.toml 기준)
• 권장 개발/사용 버전: 3.11 (테스트 및 CI의 메인스트림)
• CI에서 정기적으로 테스트하는 버전: 3.10, 3.11, 3.12, 3.13, 3.14 (Ubuntu 및 멀티OS 일부)

참고:

• 본 프로젝트는 Python 3.8/3.9의 유지 관리를 중단했습니다. 과거 환경을 지원해야 한다면 별도 브랜치나 포크에서 관리하세요.
• 일부 서드파티 패키지(예: tts 0.22.0)는 오래된 pandas 버전을 요구할 수 있습니다. 이런 경우 별도의 가상환경을 만들어 충돌을 회피하세요.
• Python 3.14에 도입된 multiprocessing 관련 최적화(PEP 649/749)를 활용하려면 CI에서 3.14 테스트가 통과해야 하며, 런타임 분기 처리가 필요할 수 있습니다.

2. API 설명

2.1 Stock 모듈

2.1.1 MarketData API

코스피 종목의 주가 관련 정보를 얻는 API 입니다.

2.1.1.1 Ticker 조회

get_market_ticker_list 메서드는 지정한 일자(YYYYMMDD)의 코스피 시장에 상장된 ticker를 리스트로 반환합니다.

tickers = stock.get_market_ticker_list("20190225")
print(tickers)

['095570', '068400', '006840', '027410', '282330', ...]

날짜를 지정하지 않으면 내부적으로 최근 영업일을 계산해서 ticker 반환합니다. 최근 영업일을 조회하는 시간이 추가로 소모되지만 사용상의 차이점은 없습니다.

tickers = stock.get_market_ticker_list()
print(tickers)

['095570', '006840', '027410', '282330', '138930', ...]

market 옵션을 추가하면 조회 시장을 지정할 수 있습니다. KOSPI, KOSDAQ, KONEX 시장을 지정할 수 있으며, ALL은 모든 시장에서 티커를 조회합니다. 입력하지 않을 경우 KOSPI 시장을 조회합니다.

tickers = stock.get_market_ticker_list("20190225", market="KOSDAQ")
print(tickers)

['095570', '006840', '027410', '282330', '138930', ...]

get_market_ticker_name 함수에 티커를 입력하면 종목이름을 반환합니다.

for ticker in stock.get_market_ticker_list():
    종목 = stock.get_market_ticker_name(ticker)
    print(종목)

SK하이닉스
....

2.1.1.2 일자별 OHLCV 조회

get_market_ohlcv 함수는 시작일/종료일/티커 세 개의 파라미터를 입력받아 OHLCV를 일자별로 정렬하여 DataFrame으로 반환합니다.

df = stock.get_market_ohlcv("20220720", "20220810", "005930")
print(df.head(3))

과거 일자의 OHLCV가 위쪽에 위치하는 것을 확인할 수 있습니다.

               시가   고가    저가     종가     거래량         거래대금   등락률
날짜
2022-07-20  61800  62100  60500  60500  16782238  1025939109200 -0.66
2022-07-21  61100  61900  60700  61800  12291374   754854999650  2.15
2022-07-22  61800  62200  61200  61300  10261310   631872940300 -0.81

get_market_ohlcv() 함수에 frequency 파라미터(d/m/y)를 추가할 수 있습니다. d는 일자, m은 월, y는 연도를 의미합니다. 다음은 20200810부터 20201212까지의 삼성전자 월별 OHLCV 데이터를 출력합니다.

df = stock.get_market_ohlcv("20200810", "20201212", "005930", "m")
print(df.head(3))

              시가     고가   저가     종가      거래량
날짜
2020-08-31  57600  59900  54000  54000  303002023
2020-09-30  54100  61300  54100  58200  426302298
2020-10-31  57500  61500  56600  56600  327557687

get_market_ohlcv() 함수는 기본적으로 요청한 마지막 일을 기준으로 수정주가를 반영하여 정보를 가져옵니다. adjusted 파라미터를 사용해서 수정주가가 반영되지 않은 OHLCV 정보를 가져올 수도 있습니다.

df = stock.get_market_ohlcv("20180427", "20180504", "005930", adjusted=False)

                시가       고가      저가      종가     거래량         거래대금   등락률
날짜
2018-04-27  2669000  2682000  2622000  2650000    606216  1611240055340  1.65
2018-04-30        0        0        0  2650000         0              0  0.00
2018-05-02        0        0        0  2650000         0              0  0.00
2018-05-03        0        0        0  2650000         0              0  0.00
2018-05-04    53000    53900    51800    51900  39565391  2078017927600 -2.08

get_stock_ticker_list() 함수와 함께 사용하면 전종목의 OHLCV를 가져올 수 있습니다. 한 번에 너무 많은 정보를 요청하면 KRX 서버가 차단할 수 있으므로 time 모듈을 사용해서 1초 지연 후 요청하도록 코드를 작성했습니다.

import time

for ticker in stock.get_stock_ticker_list():
    df = stock.get_market_ohlcv("20181210", "20181212", ticker)
    print(df.head())
    time.sleep(1)

2.1.1.3 전체 종목 시세 조회

get_market_ohlcv 함수는 입력된 일자의 코스피 전종목 시세를 DataFrame으로 반환합니다.

df = stock.get_market_ohlcv("20210122")
print(df.head(3))

          시가    고가    저가    종가   거래량     거래대금     등락률
티커
095570    4190    4245    4160    4210   216835    910274405   0.839844
006840   25750   29550   25600   29100   727088  20462325950  12.570312
027410    5020    5250    4955    5220  1547629   7990770515   4.191406

This is the beginning of the README. Read the rest at the original. Read the full README ↗