☀️ haejun

uv 프로젝트 관리 가이드

3 min read

요약

  • uv는 패키지 설치, 가상환경, 파이썬 버전, 의존성 관리를 하나로 통합한 Rust 기반 초고속 프로젝트 관리 툴
  • pyproject.toml과 uv.lock 파일로 의존성 꼬임 문제를 해결
  • uv sync 한 줄로 팀원 모두가 동일한 가상환경 구축 가능

1. uv 란?

uv는 pip, venv, pyenv, Poetry를 하나로 통합한 차세대 프로젝트 관리 툴

기존 방식의 한계

  • 번거로운 작업 흐름: 매번 수동으로 가상환경 켜고/끄기
  • 의존성 꼬임: requirements.txt에 핵심/하위 패키지가 뒤섞임

Poetry와 비교

비교 항목uvPoetry
속도압도적으로 빠름상대적으로 느림
파이썬 관리파이썬 자체도 다운로드 및 관리외부 도구 별도 필요
호환성pip 생태계 100% 호환자체 명령어 사용

결론: 신규 프로젝트는 uv로 시작하는 것이 압도적으로 유리

2. 설치

# macOS (Homebrew 추천)
brew install uv
 
# Windows
powershell -c "irm https://astral.sh/uv/install.ps1 | iex"

3. 기초 명령어

명령어기능
uv initpyproject.toml 생성
uv add <패키지명>패키지 설치 및 pyproject.toml에 등록
uv sync설계도 기반 가상환경 동기화
uv run python <파일>가상환경 활성화 없이 코드 실행

uv pip install vs uv add

  • uv pip install: pyproject.toml에 기록 안 됨 → uv sync 시 삭제
  • uv add: 정식 등록 → 동기화 시 유지

4. 기초 실행 흐름

# 1. 프로젝트 생성
uv init --python 3.12 my_project
cd my_project
 
# 2. 패키지 추가
uv add fastapi
 
# 3. 가상환경 활성화 없이 실행
uv run python hello.py

5. 상황별 사용법

파이썬 버전 변경

uv python pin 3.12
uv sync

기존 requirements.txt 마이그레이션

uv init --python <version>
uv add -r requirements.txt
rm requirements.txt

협업 시 환경 동기화 (Git Pull 후)

uv sync  # 단 한 줄로 동일한 환경 구축

Git에 반드시 올려야 할 파일

pyproject.toml, uv.lock, .python-version

Reference

Graph View