s-canvas/UV_GUIDE.md

uv 사용 가이드 — S-CANVAS

피드백 반영 (#5): pip 대신 uv 권장. uv = Rust로 작성된 ultra-fast Python 패키지 매니저. pip의 10~100배 빠름.

1. uv 설치 (Windows)

PowerShell:

irm https://astral.sh/uv/install.ps1 | iex

또는 (winget이 가능한 경우):

winget install --id=astral-sh.uv -e

또는 pip로:

pip install uv

설치 후 새 PowerShell 열고 확인:

uv --version

2. 프로젝트 초기화

S-CANVAS 디렉토리에서:

cd D:\2026\PROGRAM\1_S-CANVAS

# 기본 (Py3.9~3.12) 환경 만들기
uv venv .venv --python 3.11
.\.venv\Scripts\activate
uv pip install -e .

# 또는 Python 3.13 환경
uv venv .venv313 --python 3.13
.\.venv313\Scripts\activate
uv pip install -e ".[py313]"

# 개발 도구 함께 설치
uv pip install -e ".[py313,dev]"

3. uv lock — 재현 가능 환경

uv lock           # uv.lock 생성/갱신 (의존성 트리 freeze)
uv sync           # uv.lock 기준으로 환경 동기화 (== install)
uv sync --frozen  # lock 변경 없이만 동기화 (CI 권장)

uv.lock은 git에 커밋 (다른 머신에서 동일 환경 재현).

4. 자주 쓰는 명령

작업	uv 명령	pip 등가
패키지 추가	uv pip install foo	pip install foo
dev 패키지 추가	uv pip install -e ".[dev]"	pip install -e ".[dev]"
환경 동기화	uv sync	pip install -r requirements.txt
패키지 제거	uv pip uninstall foo	pip uninstall foo
의존성 트리 보기	uv pip tree	pip list (트리는 pipdeptree)
캐시 비우기	uv cache clean	(없음)

5. 기존 pip 환경에서 마이그레이션

기존 venv313/을 두고 새 .venv313/을 만들어 비교:

uv venv .venv313 --python 3.13
.\.venv313\Scripts\activate
uv pip install -e ".[py313,dev]"

# import smoke test
python -c "import scanvas_maker; print('OK')"

문제 없으면 기존 venv313/ 삭제. uv 환경이 더 빠르게 만들어짐 (수 초 vs 수 분).

6. CI/CD에서 uv 사용

Gitea Actions / GitHub Actions:

- uses: astral-sh/setup-uv@v3
- run: uv sync --frozen --extra dev
- run: uv run pytest
- run: uv run ruff check

7. 기존 requirements.txt / requirements-py313.txt 호환

pyproject.toml이 정식 dependency 선언. 기존 requirements 파일들은:

• requirements.txt: 빌드 머신 핀 보존용 (PyInstaller .exe 재현)
• requirements-py313.txt: iter=3에서 만든 호환 핀 (현재는 [py313] extras에 흡수됨)

새 작업은 모두 pyproject.toml 수정. requirements.txt는 deprecated.

8. 트러블슈팅

uv pip install -e . 실패: "build backend 'hatchling' not found"

uv pip install hatchling
uv pip install -e .

Python 3.13 wheel 못 찾음

일부 패키지(예: rasterio)는 3.13 wheel이 늦게 나올 수 있음. [py313] extras로 핀 완화.

기존 venv 충돌

# 새 디렉토리로 venv 만들기
uv venv .venv-fresh --python 3.13

9. 사용자가 자주 하는 작업 (cheat sheet)

# 처음 받은 직후
cd D:\2026\PROGRAM\1_S-CANVAS
uv venv .venv313 --python 3.13
.\.venv313\Scripts\activate
uv pip install -e ".[py313,dev]"

# 새 패키지 추가 시
uv pip install <package>
# pyproject.toml의 dependencies에도 수동 추가 후
uv lock

# 코드 작업 후 검사
ruff check
pytest

# 다른 머신에서 동일 환경 재현
git pull
uv sync --frozen