Summary
uv는 패키지 설치, 가상환경, 파이썬 버전, 프로젝트 의존성 관리를 하나로 통합한 Rust 기반 프로젝트 관리 툴이다.pip+requirements.txt방식은 가상환경을 매번 수동으로 켜야 하고, 핵심 패키지와 하위 패키지가 뒤섞여 저장된다.uv는pyproject.toml로 핵심 패키지만 관리하고, 하위 패키지 버전은uv.lock이 통제한다.- Poetry와 비교하면 속도, 파이썬 버전 관리, 기존
pip생태계 호환성에서 앞선다.uv pip install로 설치한 패키지는 lock 파일에 기록되지 않아uv sync시 삭제된다.pull·clone이후uv sync한 줄이면 기존 작업자와 동일한 가상환경이 구성된다.
들어가며
Python 프로젝트 관리 도구의 표준이 다시 쓰이고 있다. 압도적인 퍼포먼스와 편의성으로 그 자리를 가져간 도구가 Astral이 만든 uv다.
이 글은 기존 수동 환경 관리 방식의 한계와 Poetry와의 비교를 거쳐, uv를 쓰는 이유와 사용법을 정리한다.
개요
uv
uv는 지금까지 따로 쓰던 네 가지 도구를 단 하나로 통합한 차세대 프로젝트 관리 툴이다.
| 기존 도구 | 담당 영역 |
|---|---|
pip | 파이썬 패키지 설치 |
venv | 가상환경 관리 |
pyenv | 파이썬 버전 관리 |
Poetry | 프로젝트 의존성 관리 |
가장 큰 특징은 내부가 C나 파이썬이 아닌 Rust 언어로 작성되었다는 점이다. 덕분에 패키지 설치와 의존성 계산 속도가 기존 도구 대비 수십 배에서 최대 100배 이상 빠르다. 무거운 CI/CD 파이프라인의 시간도 획기적으로 단축된다.
기존 수동 관리와의 차이점
과거의 표준이었던 pip + venv 방식에는 두 가지 뚜렷한 한계가 있다. 매번 손으로 가상환경을 켜야 하고, 의존성 목록이 뒤엉킨다. 수동 가상환경 설정 방식은 Python 설치 및 설정에 정리되어 있다.
- 번거로운 작업 흐름:
python -m venv .venv로 폴더를 만들고,source나activate스크립트로 매번 가상환경을 켜야만 작업이 가능하다. - 의존성 꼬임 현상:
requirements.txt에는 직접 설치한 ‘핵심 패키지’와 그 패키지가 작동하기 위해 몰래 따라온 ‘하위 패키지’가 뒤섞여 저장된다. 특정 패키지를 지워도 일부가 남아서 세팅 환경이 오염되기 쉽다.
uv의 해결책
uv는pyproject.toml을 통해 핵심 패키지만 명확히 관리한다.- 복잡한 하위 패키지 버전은
uv.lock파일이 보이지 않는 곳에서 안전하게 통제한다.uv run명령어를 통해 알아서 가상환경 위에서 코드를 실행해주므로, 수동으로 가상환경을 켜고 끌 필요가 없다.
Poetry 비교
현대 파이썬 관리 방법 중 Poetry와 uv를 비교한다. 두 도구 모두 pyproject.toml을 기반으로 한 모던한 관리 방식을 선택하고 있다.
| 비교 항목 | uv | Poetry |
|---|---|---|
| 특징 | 빠른 속도와 통합성 | 안정적이고 성숙한 생태계 |
| 속도 | 압도적으로 빠름(밀리초 단위) | 상대적으로 느림 |
| 파이썬 관리 | uv python install로 파이썬 자체도 다운로드 및 관리 | pyenv 등 외부 버전 관리 도구 별도 필요 |
| 호환성 | 기존 pip 생태계 및 requirements.txt와 100% 호환 | 자체 명령어와 생태계 사용 |
| 추천 대상 | 쾌적한 속도, CI/CD 비용 절감, All-in-one 툴을 원하는 팀 | 보수적이고 엄격한 환경 관리가 최우선인 팀 |
결론
과거에는 강력한 의존성 잠금을 위해 Poetry를 많이 썼지만, 최근
uv가 프로젝트 관리 기능을 완벽히 흡수하면서 신규 프로젝트는 `uv`로 시작하는 것이 압도적으로 유리하다.
설치와 기초 사용법
설치 방법
운영체제에 맞게 터미널에서 아래 명령어를 실행한다. 설치 후에는 환경변수(PATH) 적용을 위해 터미널을 껐다가 다시 켜야 한다.
운영체제별 설치 명령어
# macOS (Homebrew 추천)
brew install uv
# macOS / Linux (공식 설치 스크립트)
curl -LsSf https://astral.sh/uv/install.sh | sh
# Windows (PowerShell)
powershell -c "irm https://astral.sh/uv/install.ps1 | iex"기초 명령어
uv를 쓰면서 가장 자주 치게 되는 명령어는 네 개다. 아래 흐름과 상황별 사용법은 모두 이 네 개의 조합이다.
| 명령어 | 기능 |
|---|---|
uv init | pyproject.toml 생성 |
uv add <패키지명> | 패키지 설치 및 pyproject.toml에 등록 |
uv sync | 설계도 기반 가상환경 동기화 |
uv run python <파일> | 가상환경 활성화 없이 코드 실행 |
기초 실행 흐름
신규 프로젝트는 초기화, 패키지 추가, 실행 세 단계로 끝난다. 가상환경을 직접 켜는 단계는 없다.
신규 프로젝트 생성
# 1. 파이썬 버전을 지정하여 프로젝트 뼈대 생성 (pyproject.toml 생성)
uv init --python 3.12 my_project
cd my_project
# 2. 패키지 정식 추가 (이때 .venv 폴더와 uv.lock 파일이 자동 생성됨)
uv add fastapi
# 3. 가상환경 활성화 없이 바로 코드 실행
uv run python hello.pyuv init의 역할
uv init은 프로젝트 설계도(pyproject.toml)를 만드는 작업이다. 따라서venv를 따로 생성할 필요가 없다.- 이후
uv add로 패키지를 설치하거나uv sync를 치면,uv가 설계도를 보고 가상환경(.venv)을 알아서 생성한다.uv venv는 기존의python -m venv처럼 프로젝트 관리 없이 단순히 빈 가상환경 폴더만 만들고 싶을 때 쓰는 하위 호환용 명령어다.
상황별 실행 방법
기존 pip 습관 때문에 uv를 처음 쓸 때 가장 많이 헷갈리는 상황들을 정리한다.
파이썬 버전 변경
이미 uv init을 한 뒤 파이썬 버전을 바꾸려면 아래 uv python pin 명령이 가장 깔끔하다. pyproject.toml을 직접 수정해도 된다.
파이썬 버전 고정
uv python pin 3.12
uv sync.python-version파일이 생성/수정되며 프로젝트 버전이 고정된다.- 이후
uv sync를 치면 해당 버전에 맞춰 환경이 재구성된다. - 내 컴퓨터에 해당 파이썬 버전이 없다면
uv가 알아서 다운로드한다.
init 취소
실수로 엉뚱한 폴더(상위 폴더 등)에 uv init을 한 경우다. uv init은 단순히 초기 파일 몇 개를 생성하는 행위이므로 생성된 파일만 지워주면 원상복구된다. 탐색기에서 지우거나 터미널에서 아래 명령어를 실행한다.
생성 파일 삭제
# Windows (PowerShell)
rm pyproject.toml, .python-version, hello.py
# 패키지까지 설치했었다면 가상환경과 lock 파일도 삭제
rm -r .venv, uv.lock기존 프로젝트 마이그레이션
기존 requirements.txt 프로젝트를 uv로 옮기는 경우다. 기존 환경을 깨끗하게 밀고 마이그레이션한다.
requirements.txt 기반 마이그레이션
uv venv --clear # 기존 .venv 내부 찌꺼기 싹 비우기
uv init # 모던 프로젝트로 초기화
uv add -r requirements.txt # 기존 목록을 바탕으로 설치 및 lock 파일 생성
rm requirements.txt # 기존 패키지 목록 제거의존성 등록 방식 차이
uv add와 uv pip install은 패키지가 설치되는 위치는 같지만 기록되는 위치가 다르다. 이 차이가 uv sync 시점에 패키지의 생존 여부를 가른다.
uv pip install은 lock 파일에 기록되지 않는다
uv pip install로 설치한 패키지는 설계도(uv.lock)에 기록되지 않는다.- 이로 인해, 나중에 환경을 맞추려고
uv sync(동기화)를 실행하는 순간 “불법 패키지”로 간주되어 가상환경에서 삭제된다.- 따라서 프로젝트의 정식 의존성은 반드시 `uv add`를 사용한다.
| 구분 | uv add <package> | uv pip install <package> |
|---|---|---|
| 목적 | 프로젝트에 계속 사용할 핵심 패키지 설치 | 테스트 하고 지울 일회성 패키지 설치 |
| 동작 방식 | 가상환경(.venv)에 설치함과 동시에 설정 파일(pyproject.toml)에 등록 | 가상환경(.venv)에만 설치 |
| 기록 | pyproject.toml, uv.lock에 정식 기록 | 파일에 전혀 기록되지 않음 |
uv sync 실행 시 | 설계도 있으므로 안전하게 유지 | 설계도에 기록되지 않아서 삭제 |
협업 환경 동기화
GitLab(또는 GitHub)에서 pull을 받거나 clone을 해온 뒤 로컬 환경을 맞추는 데는 다음 명령어 단 한 줄이면 세팅이 끝난다.
전제는 하나다. Git에 pyproject.toml, uv.lock, .python-version 세 파일이 반드시 올라가 있어야 한다.
로컬 환경 동기화
uv syncuv가 uv.lock 파일을 분석하여 기존 작업자와 100% 동일한 가상환경(.venv)을 1초 만에 구성한다.
Reference