uv로 DartLab 설치와 첫 실행

무엇을 설치하나

DartLab 은 uv 와 Python 위에서 돌아간다. Python 이 없어도 괜찮다 — uv 가 자동으로 받아준다.

uv 가 뭔가: Rust 로 만든 Python 패키지 관리자. pip 보다 10~100 배 빠르고 Python 버전까지 관리한다. uv 만 설치하면 별도 Python 설치는 필요 없다.

---

0 단계 — 터미널 열기

Windows

Win + R → powershell 입력 → Enter. 또는 작업 표시줄 검색에 PowerShell 입력 → Windows PowerShell 클릭.

Command Prompt (cmd) 가 아니라 PowerShell 이어야 한다. 아래 설치 명령 일부가 cmd 에서 작동하지 않는다.

macOS

Cmd + Space → Spotlight 에 Terminal 입력 → Enter.

Linux

대부분의 배포판에서 Ctrl + Alt + T.

---

1 단계 — uv 설치

Windows (PowerShell)

powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"

설치 후 터미널을 닫고 다시 열어야 uv 명령이 인식된다.

macOS / Linux

curl -LsSf https://astral.sh/uv/install.sh | sh

설치 후 터미널을 다시 열거나 source ~/.bashrc (또는 ~/.zshrc) 를 실행한다.

설치 확인

uv --version

버전 번호가 찍히면 성공. uv: command not found 가 보이면 터미널을 다시 연다.

---

2 단계 — 프로젝트 만들기

uv init my-dart-analysis
cd my-dart-analysis

이 명령이 자동으로 처리한다:

• Python 3.12+ 감지 또는 자동 다운로드.
• pyproject.toml (프로젝트 설정) 생성.
• .venv/ 가상환경 생성.

Python 을 따로 설치할 필요는 없다.

---

3 단계 — DartLab 설치

uv add dartlab

의존성 (Polars, rich, alive-progress) 도 같이 설치된다.

---

4 단계 — 설치 검증

uv run python -X utf8 -c "import dartlab; c = dartlab.Company('005930'); print(c.corpName)"

삼성전자 가 출력되면 끝.

uv run 은 가상환경 안에서 실행한다. uv run python 을 쓰면 방금 설치한 dartlab 패키지가 보장된다. -X utf8 은 Windows 의 cp949 출력 깨짐을 막는다.

---

AI 옵션 (dartlab ai)

LLM 기반 회사 분석 웹 인터페이스를 쓰려면 AI 의존성을 추가한다.

uv add "dartlab[ai]"
uv run dartlab ai

브라우저가 http://localhost:8400 에서 열린다. Ollama 설치 (ollama.com/download) 후 ollama pull gemma3 으로 모델을 받아두면 바로 동작한다.

---

데이터 흐름

DartLab 은 DART 공시 원문을 파싱한 Parquet 파일을 사용한다. 직접 다운로드할 필요 없다 — dartlab.Company("005930") 호출 시 없으면 자동으로 받는다.

DART — 3 단계 파이프라인

import dartlab

c = dartlab.Company("005930")   # 로컬 없으면 자동 다운로드

1. 로컬 캐시 — 이미 받았으면 즉시.
2. HuggingFace — HuggingFace Datasets 미리 빌드된 Parquet (빠르고 전 종목 커버).
3. DART API — OpenDART 직접 수집 (느리고 API 키 필요).

신선도 자동 감지

3 계층 모델로 로컬 데이터의 최신 여부를 확인한다:

계층	방식	속도	감지 대상
L1	HuggingFace ETag (HTTP HEAD)	~0.5s	미리 빌드 데이터 갱신
L2	파일 나이 TTL (90 일)	즉시	오래된 로컬 파일
L3	DART API rcept_no diff	~1s	DART 신규 공시

L1 + L2 는 API 키 없이 동작. L3 는 DART API 키 필요 (dartlab setup dart-key).

새 공시가 감지되면 안내 메시지만 띄우고 자동 수집은 하지 않는다 (Company 생성 시점에는).

result = dartlab.checkFreshness("005930")
print(result.isFresh, result.missingCount)

c = dartlab.Company("005930")
c.update()  # 누락된 공시만 증분 수집

dartlab collect --check 005930          # 단일 종목 신선도
dartlab collect --check                 # 로컬 종목 전수 (7 일)
dartlab collect --incremental 005930    # 단일 종목 증분
dartlab collect --incremental           # 신규 공시 있는 모든 종목 증분

EDGAR — 실시간 가져오기

미국 종목은 SEC API 에서 처음 호출 시 가져온다.

c = dartlab.Company("AAPL")   # SEC API 호출

SEC 의 rate limit 때문에 첫 로드가 잠깐 걸릴 수 있다. 이후는 로컬 캐시.

---

Google Colab 으로 시도

로컬 설치 없이 바로 돌려보고 싶으면 Colab.

Colab 셀에서:

!pip install dartlab

import dartlab
c = dartlab.Company("005930")
c.show("BS")

---

트러블슈팅

uv: command not found

터미널을 닫고 다시 연다. 그래도 안 되면 설치 스크립트를 다시 실행.

Windows: irm 명령 인식 안 됨

PowerShell 이 아니라 cmd 에 있을 가능성. Win + R → powershell → Enter.

ModuleNotFoundError: No module named 'dartlab'

python 이 아니라 uv run python 을 써야 한다. 가상환경 밖의 시스템 Python 으로는 dartlab 을 못 찾는다.

데이터 다운로드가 느림

HuggingFace 에서 받기 때문에 네트워크 속도에 의존한다.

---

다음 단계

• start.dartlabSkillOs — Skill OS 첫 진입과 검색 절차.
• start.quickStart — 8 분 walkthrough (Company / sections / show / scan / ask).
• start.useSkillsCatalog — skills 카탈로그 사용법.
• Skills 카탈로그 (/skills) — 178 개 절차 검색.

요구 사양

패키지	최소 버전	비고
Python	3.12	uv 가 자동 설치
Polars	1.0.0	자동 설치
alive-progress	3.0.0	진행률 바
rich	13.0.0	터미널 출력