Python 패키지 관리 도구 uv 완벽 정리

Python 패키지 관리 도구 uv 완벽 정리 빠른 속도와 간결한 워크플로우로 주목받고 있는 uv는 최근 많은 개발자들 사이에서 pip·poetry·pip-tools를 대체할 수 있는 새로운 패키지 관리 도구로 자리 잡아가고 있습니다. Rust로 구현된 덕분에 압도적으로 빠르고, 패키지 관리와 가상환경 관리까지 모두 한 번에 처리할 수 있다는 장점이 있습니다. 이번 글에서는 uv의 핵심 명령어 요약, uv가 생성하는 주요 파일들의 의미, 마지막으로 uv에서 가장 중요한 기능 중 하나인 uv sync의 동작 원리를 자세히 정리해 보겠습니다. 🧩 uv 핵심 명령어 요약 1. 프로젝트 초기화 uv init 새로운 Python 프로젝트 스캐폴딩 생성 pyproject.toml 자동 생성 패키지 선언, 가상환경 설정을 위한 기본 틀 준비 2. 패키지 설치 uv add 패키지명 기능: 패키지 설치 pyproject.toml에 자동 반영 uv.lock 파일 업데이트 설치된 패키지는 자동으로 가상환경에 반영됨 예: uv add requests 3. 패키지 제거 uv remove 패키지명 pyproject.toml과 uv.lock에서 해당 패키지 삭제 가상환경에서 패키지 제거 4. 가상환경 실행 uv venv uv run python main.py 기능: 자체 가상환경 생성 가상환경 activate 없이 바로 명령 실행 가능 5. 모든 패키지 설치 / 환경 재구성 uv sync (아래에서 상세 설명) 6. 패키지 업데이트 uv update 최신 버전으로 전체 혹은 특정 패키지를 업데이트 lock 파일 재생성 🗂 uv 관련 주요 파일 설명 📌 1. pyproject.toml Python 에코시스템에서 권고하는 프로젝트 설정 파일. uv에서는 아래 역할 수행: 패키지 의존성 선언 (dependencies) 개발환경 의존성 선언 (dev-dependencies) 프로젝트 메타데이터 (name, version 등) build system 정의 uv 설정 포함 가능 예시: [project] name = "my-app" version = "0.1.0" dependencies = [ "requests" ] 📌 2. uv.lock uv가 실제로 설치한 패키지 버전 및 해시 정보를 모두 기록한 잠금 파일(lock file). 특징: "정확히 이 버전"이 설치되어 재현 가능한 환경 구성 팀 내 여러 개발자가 동일한 환경 유지 가능 CI/CD 환경에서 필수적인 파일 다른 생태계의 lock 파일과의 비교: npm → package-lock.json poetry → poetry.lock 즉, uv.lock은 패키지 설치의 진실의 근원(Single Source of Truth) 역할을 합니다. 📌 3. .venv 디렉터리 uv가 자동 생성하는 가상환경 Python 인터프리터 + site-packages 포함 .gitignore 처리 권장 물리적으로는 일반 venv와 동일하지만 uv가 자동 관리하기 때문에 activate 작업이 거의 필요 없습니다. 🚀 uv sync: uv의 핵심 기능 완전 이해하기 uv sync는 uv 생태계에서 가장 중요한 명령입니다. 딱 한 줄로 정의하자면: uv sync는 pyproject.toml과 uv.lock을 기준으로 프로젝트 가상환경을 완전히 동기화하는 명령이다. 조금 더 깊게 보면 3가지 핵심 기능을 포함합니다. 1. 가상환경 생성 프로젝트에 .venv가 없다면 자동 생성합니다. .venv/ 2. pyproject.toml + uv.lock 비교 uv sync는 다음 과정을 수행합니다. pyproject.toml의 desired dependencies (원하는 패키지 상태) uv.lock의 locked dependencies (동일 환경을 위한 고정된 버전) 이 둘을 비교한 뒤, 필요하면 lock 파일을 사용해 패키지를 설치하고 가상환경을 필요한 상태로 업데이트합니다. 3. 패키지 설치 일관성 유지 uv sync는 패키지를 “해결(resolve)”하지 않습니다. 해결은 이미 uv add 또는 uv update가 수행한 상태입니다. 즉: 작업 역할 uv add 의존성 해결(resolve) + 락 파일 갱신 uv update 전체 또는 특정 패키지 해결+업데이트 uv sync 그냥 현재 uv.lock을 기반으로 동일한 환경 설치 Poetry와 비교하면: poetry install ≈ uv sync poetry add ≈ uv add 🧠 uv sync를 사용하는 경우 1) 새로운 개발자가 프로젝트를 clone한 뒤: uv sync 끝. 2) CI/CD 환경에서 “환경 재현” uv sync --frozen uv.lock만 사용 pyproject.toml과 lock 파일 불일치 시 에러 발생 → 재현성 보장 npm의 npm ci와 같은 개념 3) 가상환경 삭제 후 재구성 rm -rf .venv uv sync 🎯 마무리 uv는 빠르고, 자동화가 잘 되어 있으며, modern Python workflow에 매우 적합한 도구입니다. 특히 uv sync는 프로젝트 환경을 일관되게 유지하는 핵심 명령으로, 팀 협업이나 CI/CD 과정에서 매우 큰 역할을 합니다. 정리하자면: pyproject.toml: 의존성 선언 uv.lock: 재현 가능한 설치 기록 uv sync: 이 두 파일 기반으로 가상환경 완전 동기화 앞으로 Python 프로젝트를 보다 깔끔하고 빠르게 관리하고 싶다면 uv를 도입해 보시길 적극 추천드립니다.