uv를 활용한 Python 프로젝트 관리 핵심 가이드

카테고리

프로그래밍/소프트웨어 개발

서브카테고리

개발 툴

대상자

- Python 개발자 및 팀

- 프로젝트 관리, 의존성 처리, 가상 환경 설정이 필요한 중급 이상 개발자

- 난이도: 중급 (uv 기능 활용 및 환경 설정 경험 필요)

핵심 요약

• uv는 Python 버전, 의존성, 가상 환경을 통합 관리하는 도구로, uv.lock 파일을 통해 환경 재현 가능
• uv add 명령으로 의존성 추가 시 pyproject.toml 및 uv.lock 자동 업데이트
• uv run 명령으로 가상 환경 내 Python 실행, uv sync로 환경 일관성 유지

섹션별 세부 요약

1. **Lock 파일 기능**

• uv.lock 파일은 transitive dependency 버전, 크로스 플랫폼 지원, Git 관리 시 수작업 편집 금지
• 예시: pandas 의존성의 numpy, python-dateutil 등 트랜지티브 의존성 명시
• uv.lock은 pip + requirements.txt 대비 환경 재현 일관성 보장

2. **가상 환경 관리**

• uv는 venv 기반 가상 환경 사용 (직접 venv 활성화 가능하지만 uv run 권장)
• .python-version 파일에 지정된 Python 버전 사용 (예: 3.13.2)
• uv python install로 Python 설치 후 uv run 또는 uv venv로 가상 환경 생성

3. **프로젝트 초기화 및 Python 버전 관리**

• uv init 명령으로 pyproject.toml, .python-version, README.md 생성
• uv python list로 설치된 Python 버전 확인 (예: cpython-3.13.2-linux-x86_64-gnu)
• uv python pin으로 사용할 Python 버전 고정 (.python-version 파일 재작성)

4. **의존성 추가 및 제거**

• uv add 명령으로 의존성 추가 시 pyproject.toml 및 uv.lock 자동 업데이트
• 예: uv add requests 또는 uv add git+https://github.com/...
• 의존성 충돌 시 --frozen 플래그로 무시 가능 (단, 환경 일관성 위험 주의)
• uv remove 명령으로 의존성 제거 (예: uv remove requests)

5. **스크립트 실행 및 환경 동기화**

• uv run 명령으로 가상 환경 내 Python 실행 (예: uv run example.py)
• uv sync으로 uv.lock과 가상 환경 상태 동기화 (기본적으로 uv run으로 자동 처리)
• --python 옵션으로 특정 Python 버전 지정 (예: uv run --python 3.10 example.py)

결론

• uv는 pyenv + pip + venv 대비 간결한 환경 설정 및 의존성 관리 가능
• uv.lock 파일을 통해 환경 재현 일관성 확보, uv run을 통해 가상 환경 내 실행 추천
• 의존성 충돌 시 --frozen 플래그 사용 시, 환경 일관성 손실 가능성 주의하며 uv remove + 재추가 필요
• 공식 문서(https://docs.astral.sh/uv/) 참조하여 최신 기능 및 버전(v0.6.14) 확인 권장