📌 uv 활용 & uv.lock 관리 가이드

✅ 1) 개발 단계(Development stage)

목적

• 최신 의존성 테스트 가능

• 로컬에서 기능 개발

• Dev 툴(lint/test 등) 포함 설치

권장 작업 흐름

작업	명령어	설명
의존성 추가	uv add --dev pytest	개발 dependency 그룹으로 관리
환경 동기화	uv sync	.venv에 의존성 설치
락 파일 업데이트	uv lock	pyproject.toml 변경 후 실행
락 파일 기반 설치 테스트	uv sync --locked	lock 파일만으로 동일 환경 재현 확인

개발자 로컬 환경

uv sync  # dev 포함 설치 OK

→ 개발자는 uv.lock을 자동 생성/갱신하여 커밋합니다 ✅

---

✅ 2) 패키징 단계(Build / Packaging stage)

목적

• artifacts(예: wheel, sdist) 생성

• 운영환경에 불필요한 Dev deps 제외

권장 작업 흐름

작업	명령어	설명
lock 파일 기반 설치 검증	uv sync --locked --no-dev	재현 가능한 production deps
패키지 빌드	uv build	wheel/SDist 생성
런타임 검사	uv run app:main	의존성 정상 반영 검증

예시 명령

uv sync --locked --no-dev
uv build

→ 배포되는 artifact는 dev deps 없이, lock 파일 기반 버전 확정

---

✅ 3) Repository 관리(협업 / Git 공유)

목적

• 모든 팀원이 동일한 패키지 버전 환경을 사용하도록 강제

Git에 반드시 포함해야 하는 것 ✅

파일	목적
pyproject.toml	의존성 요구 정의
uv.lock	의존성 정확 버전 고정

Git에 포함하지 않는 것 ❌

제외 파일	이유
.venv 폴더	개발 OS/환경마다 달라짐

.venv/

팀원이 클론 후 수행

uv sync --locked

→ 어디서든 완전히 동일한 환경 보장

---

✅ 4) CI/CD / 운영환경(Production stage)

목적

• dev deps 미포함

• 빌드 재현성 보장

• lock 불일치 시 실패 → 안정성 확보

명령어

uv sync --locked --no-dev

CI에서 다음처럼 검증 조건을 명확하게 설정:

조건	기준
dev dependency X	--no-dev
lock 불일치 시 오류	--locked
재현성 높은 빌드	동일 Python 버전, uv 버전

---

🚀 전체 Workflow 요약

단계	명령	dev deps	lock 기준	목적
Local 개발	uv sync	✅ 포함	X	개발 편의
협업(Repository)	uv sync --locked	✅ 포함	✅	환경 재현
빌드(Packaging)	uv sync --locked --no-dev	❌ 제외	✅	배포 안정성
운영(CI/Prod)	uv sync --locked --no-dev	❌ 제외	✅	동일 실행환경

✅ 핵심 한 줄 요약

개발 시엔 자유롭게 업데이트,
배포/운영 시엔 lock 파일로 완전 재현!

---

🔒 uv.lock 관리 원칙

✅ 커밋 필수
✅ 팀 전체 공유
❌ 수동 수정 금지
✅ 의존성 변경 시 uv lock 실행
✅ 운영에서는 “lock mismatch error”를 의도적으로 발생시키기

---

🔧 부가 팁

VSCode 자동 포맷팅 deps(dev 그룹)

uv add --dev ruff black isort

테스트 env 별도 그룹 운영

uv add --group test pytest pytest-cov
uv sync --group test  # 테스트 CI 에서만 설치

Node.js의 package-lock.json, Pipenv의 Pipfile.lock과 동일 개념

👉 하지만 uv는 속도가 훨씬 빠르고 modern toolchain