UV_GUIDE.md

uv 크로스 플랫폼 개발 가이드

이 문서는 Mac에서 개발하고 Windows 서버에서 실행하는 크로스 플랫폼 환경을 위한 uv 사용 가이드입니다.

---

현재 프로젝트 설정

항목	값
프로젝트명	trading-research-mcp
Python 버전	>= 3.12
패키지 수	128개 (lockfile 기준)

GitHub에 커밋된 파일

pyproject.toml      # 의존성 정의
uv.lock             # 크로스 플랫폼 lockfile (핵심!)
.python-version     # Python 버전 고정

.gitignore에 포함된 파일

.venv/              # 가상환경 (각 머신에서 자동 생성)

---

1. 초기 설치 (1회)

Mac

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

# 터미널 재시작 또는
source ~/.zshrc

# 설치 확인
uv --version

Windows

# uv 설치 (PowerShell 관리자 권한)
powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"

# 새 PowerShell 창 열기 (필수!)

# 설치 확인
uv --version

Windows에서 'uv' is not recognized 오류 시

# 1) uv 설치 위치 확인
dir $env:USERPROFILE\.local\bin\uv.exe

# 2) PATH에 영구 추가
$uvPath = "$env:USERPROFILE\.local\bin"
[Environment]::SetEnvironmentVariable("PATH", [Environment]::GetEnvironmentVariable("PATH", "User") + ";$uvPath", "User")

# 3) PowerShell 재시작 후 확인
uv --version

---

2. 프로젝트 환경 구성

Mac / Windows 공통

# 프로젝트 폴더로 이동
cd /path/to/portfolio_PoC

# 가상환경 생성 + 의존성 설치 (한 번에!)
uv sync

# 실행
uv run python main.py

uv sync는 다음을 자동으로 수행합니다:

1. .python-version에 지정된 Python 버전 확인/설치
2. .venv/ 가상환경 생성
3. uv.lock 기반으로 정확히 동일한 패키지 설치

---

3. 일상적인 워크플로우

Mac (개발 머신)

# 스크립트 실행
uv run python main.py

# 새 패키지 추가
uv add requests
uv add "pandas>=2.0.0"

# 패키지 제거
uv remove requests

# lockfile 갱신 (패키지 추가/제거 시 자동 실행됨)
uv lock

# 변경사항 커밋
git add pyproject.toml uv.lock
git commit -m "deps: 패키지 추가/수정"
git push

Windows (서버)

# 최신 코드 pull
git pull

# 환경 동기화 (항상 이것만!)
uv sync

# 실행
uv run python main.py

---

4. 명령어 요약

작업	명령어	설명
환경 동기화	uv sync	lockfile 기반 설치
스크립트 실행	uv run python main.py	가상환경에서 실행
패키지 추가	uv add 패키지명	pyproject.toml + lockfile 갱신
패키지 제거	uv remove 패키지명	pyproject.toml + lockfile 갱신
lockfile 갱신	uv lock	의존성 재계산
캐시 정리	uv cache clean	디스크 공간 확보

---

5. 문제 해결

Python 버전 불일치

# 현재 Python 버전 확인
uv python list

# 특정 버전 설치
uv python install 3.12

lockfile 충돌

# lockfile 재생성
uv lock --upgrade

캐시 문제

# 캐시 초기화 후 재설치
uv cache clean
uv sync

Windows PATH 문제

# 전체 경로로 직접 실행 테스트
& "$env:USERPROFILE\.local\bin\uv.exe" --version

# 되면 PATH 문제 → 위 "초기 설치" 섹션 참고

---

6. 왜 uv인가?

기존 방식	uv
pip install -r requirements.txt	uv sync
플랫폼별 버전 차이 발생	lockfile로 동일한 버전 보장
설치 시간 수 분	수 초 (10-100배 빠름)
의존성 충돌 빈번	엄격한 resolver

---

7. 참고 자료

• uv 공식 문서
• uv GitHub