Python uv 베스트 프랙티스: 안정성과 협업 체크리스트

실제 운영에서 환경을 망가뜨리는 건 대부분 "uv가 충분히 강하지 않아서"가 아니라 프로세스와 습관 때문입니다. 아래 체크리스트는 일상 지침으로 바로 사용할 수 있습니다 — 함정 하나를 피할 때마다 정시 퇴근이 한 번 더 가능해집니다.

권장 사항

1) uv.lock은 반드시 커밋

잠금 파일은 재현성의 기반입니다. 커밋하지 않으면 각자·각 머신·각 CI 실행마다 다른 의존성이 설치될 수 있어 버그 재현이 지옥 난이도가 됩니다. 잠금 파일 없는 프로젝트는 신어보지 않은 새 신발과 같습니다 — 실전에서야 발이 아프다는 걸 알게 됩니다.

2) .venv는 커밋하지 않음

가상 환경은 로컬 산물 — .gitignore에 있어야 합니다. uv는 자동으로 .venv를 프로젝트 ignore에 추가합니다. 확인만 하면 됩니다.

3) 의존성은 가능하면 제약

pyproject.toml에서 그냥 requests라고 쓰는 건 피하고, requests>=2.31,<3 등 더 구체적으로. uv add는 기본적으로 합리적인 제약을 추가합니다. 수동 편집 시 범위를 너무 넓게 두지 마세요.

4) CI에서 uv sync 또는 uv pip sync 사용

# GitHub Actions 예시
- run: uv sync
- run: uv run pytest

먼저 동기화 후 실행 — 환경이 잠금 파일과 일치하도록 보장합니다. CI 안에서 uv add를 실행하지 마세요. 잠금 파일을 변경해서 예상치 못한 diff가 생길 수 있습니다.

5) 개발 도구는 optional / dev에 넣기

uv add --dev pytest ruff mypy

테스트·lint·타입 체크는 프로덕션 의존성에 영향을 주지 않고 wheel에도 패킹되지 않습니다. 프로덕션 이미지는 uv sync --no-dev만 필요합니다.

일반적인 함정

함정 1: pip과 uv add 혼용

같은 venv에서 pip install과 uv add를 모두 쓰지 마세요 — 잠금 파일이 맞지 않게 됩니다. 하나의 방법을 선택하고 끝까지 따르세요.

함정 2: uvx를 프로젝트 도구로 사용

버전 고정이 필요한 프로젝트 도구 (pytest, mypy 등) → uv add --dev + uv run 사용. 임시 사용·일회성 스크립트 → uvx 사용.

함정 3: pyproject.toml을 읽지 않고 수동 편집

의존성 변경은 uv add / uv remove를 사용해 형식 문제와 잠금 파일 업데이트 누락을 피하세요.

함정 4: CI에 uv 설치하지 않기

많은 CI가 이제 uv를 지원합니다 — 설치도 빠르고 실행은 더 빠릅니다. 공식 인스톨러나 pip install uv를 사용하세요. pip으로 의존성 해결하는 데 계속 고집 피우지 마세요.

함정 5: 프로젝트에 requires-python 없음

pyproject.toml에 requires-python = ">=3.12" 등을 명시해서 도구와 협업자에게 최소 버전을 알려주세요. "내 3.12에서는 되는데 네 3.8에서는 터진다"는 참사를 방지합니다.

이 체크리스트를 따른다고 무결고장을 보장하진 않지만 많은 우회로를 피할 수 있습니다. 막히면 공식 문서를 확인하세요 — 대부분의 함정은 이미 누군가가 밟아봤습니다. 개발이 순탄하기를, 의존성이 깔끔하게 설치되고, 테스트는 항상 초록불이고, CI가 당신을 영원히 기다리게 하지 않기를! 🦦 (참고로, uv를 쓰기 시작하면 알게 됩니다: pip 스피너를 기다리던 시간에 고양이를 세 번 쓰다듬을 수 있었다는 것을.)