pip이나 poetry로 프로젝트를 돌리다가 “uv로 파이썬 의존성 관리하기”가 요즘 자주 언급돼서 검색해 보셨다면, 결론부터 말씀드릴게요. uv는 pip·pip-tools·venv·pyenv·poetry가 각각 하던 일을 명령어 하나로 묶은 도구이고, 실제로 옮길 때 달라지는 건 속도보다 “파일 구조”와 “명령어 습관” 쪽입니다. requirements.txt나 poetry.lock에 익숙하다면 처음 며칠은 명령어를 새로 외워야 하지만, 프로젝트 구조 자체는 pyproject.toml 하나로 단순해집니다.
이 글은 uv를 처음 써보는 분이 pip 프로젝트, poetry 프로젝트 각각에서 실제로 어떤 절차를 거치는지, 그리고 옮겼을 때 불편해지는 지점까지 구체적으로 짚어 드립니다.
pip·poetry와 뭐가 다른가 — 파일 여러 개가 하나로 줄어듭니다
pip 기반 프로젝트는 보통 requirements.txt(때로 requirements-dev.txt까지), 가상환경 폴더, 그리고 pyenv 같은 별도 파이썬 버전 관리 도구까지 세 가지를 따로 운영합니다. poetry는 pyproject.toml과 poetry.lock으로 의존성은 정리되지만, 파이썬 버전 자체를 설치하는 기능은 없어서 pyenv를 여전히 같이 씁니다.
uv는 이 역할을 하나의 바이너리로 흡수합니다. uv python install로 파이썬 인터프리터 자체를 설치하고, uv venv로 가상환경을 만들고, uv add로 의존성을 추가하면 pyproject.toml과 uv.lock이 자동으로 갱신됩니다. 즉 “파이썬 버전 관리 + 가상환경 + 패키지 설치 + 잠금 파일”이 별도 도구 조합이 아니라 uv 하나의 서브커맨드로 처리된다는 점이 가장 큰 구조적 차이입니다.
속도 차이도 실제로 체감됩니다. uv는 Rust로 작성돼 있고, 전역 캐시에 내려받은 패키지를 하드링크로 재사용하기 때문에 같은 패키지를 여러 프로젝트에서 설치할 때 특히 빠릅니다. 다만 정확한 배수는 네트워크 환경과 패키지 구성에 따라 달라지므로, 이 글에서 임의의 수치를 단정하지는 않겠습니다.
설치와 프로젝트 생성, 명령어로 직접 확인해보세요
macOS·리눅스에서는 curl 스크립트로, 윈도우에서는 PowerShell 스크립트로 uv를 설치할 수 있고, 이미 파이썬이 있다면 pip install uv로도 설치가 됩니다. 설치 후 새 프로젝트를 만드는 흐름은 아래와 같습니다.
$ uv init demo-project
Initialized project `demo-project` at `/home/user/demo-project`
$ cd demo-project
$ uv add requests
Resolved 5 packages in 120ms
Prepared 5 packages in 340ms
Installed 5 packages in 15ms
+ certifi==2024.8.30
+ charset-normalizer==3.3.2
+ idna==3.8
+ requests==2.32.3
+ urllib3==2.2.3
$ uv run python -c "import requests; print(requests.__version__)"
2.32.3
uv add를 실행하는 순간 pyproject.toml에 requests가 의존성으로 기록되고, uv.lock에는 실제로 설치된 버전과 해시가 잠깁니다. uv run은 가상환경을 따로 activate하지 않아도 프로젝트 환경 안에서 명령을 실행해 주기 때문에, source .venv/bin/activate를 매번 치던 습관을 줄일 수 있습니다.
requirements.txt를 uv 프로젝트로 옮기는 3단계
기존 pip 프로젝트를 uv로 옮길 때는 굳이 전체 구조를 바꾸지 않고 점진적으로 진행할 수 있습니다.
- 프로젝트 루트에서
uv init --no-readme로 pyproject.toml만 먼저 만듭니다. 기존 파일은 건드리지 않습니다. uv add -r requirements.txt를 실행하면 requirements.txt에 적힌 패키지들이 pyproject.toml의 dependencies 항목으로 옮겨지고, 동시에 uv.lock이 생성됩니다.uv sync로 lock 파일 기준 가상환경을 맞춘 뒤, requirements.txt는 삭제하거나 CI 호환용으로uv export --format requirements-txt로 다시 뽑아 남겨둡니다.
pip 명령을 그대로 쓰고 싶은 팀이라면 굳이 pyproject.toml로 전환하지 않고 uv pip install -r requirements.txt, uv pip compile requirements.in -o requirements.txt처럼 pip 호환 인터페이스만 가져다 쓰는 방법도 있습니다. 이 경우는 프로젝트 구조를 바꾸지 않고 설치 속도만 개선하는 절충안입니다.
poetry에서 넘어올 때 실제로 걸리는 것들
poetry 프로젝트는 pyproject.toml에 [tool.poetry] 섹션으로 의존성을 씁니다. uv는 PEP 621 표준인 [project] 섹션을 기준으로 동작하기 때문에, 이 둘은 형식이 다릅니다. uv에는 poetry 설정을 자동으로 변환해 주는 공식 명령이 없어서, [tool.poetry.dependencies] 항목을 [project.dependencies]로 손으로 옮기거나 uv add 명령을 패키지별로 다시 실행해서 새로 구성해야 합니다.
poetry의 dependency group([tool.poetry.group.dev.dependencies]) 기능은 uv의 [dependency-groups]로 대응되지만 문법이 조금 다르고, poetry 플러그인(예: poetry-dynamic-versioning)을 쓰던 프로젝트라면 uv에서 동일한 기능을 대체할 방법을 따로 찾아야 합니다. 여기서 시간이 꽤 걸릴 수 있다는 점은 미리 감안하시는 게 좋습니다.
버전 문자열 표기도 차이가 있습니다. poetry는 ^1.2.3 같은 캐럿 표기를 기본으로 쓰지만, uv가 따르는 PEP 621 표준 의존성 명세는 >=1.2.3,<2.0.0 같은 PEP 440 방식 범위 표기가 기본입니다. 이 변환도 자동화 도구 없이 수동으로 점검하는 편이 안전합니다.
uv가 안 맞는 경우도 있을까요?
세 도구를 표로 정리하면 차이가 더 분명해집니다.
| 항목 | pip (+venv) | poetry | uv |
|---|---|---|---|
| 의존성 파일 | requirements.txt | pyproject.toml + poetry.lock | pyproject.toml + uv.lock |
| 파이썬 버전 설치 | 미지원 (pyenv 별도) | 미지원 (pyenv 별도) | uv python install 내장 |
| 잠금 파일 해시 검증 | pip-tools 별도 필요 | 기본 지원 | 기본 지원 |
| 가상환경 생성 | python -m venv |
자동 생성 | uv venv / 자동 생성 |
| CLI 도구 격리 실행 | pipx 별도 | 미지원 | uvx 내장 |
uv가 항상 정답은 아닙니다. conda로 CUDA·MKL 같은 비파이썬 바이너리 의존성까지 관리하던 과학계산·머신러닝 환경이라면, uv는 파이썬 패키지 영역만 다루기 때문에 conda를 완전히 대체하지 못합니다. 또 회사 CI 파이프라인이 poetry.lock 파일 형식이나 poetry 전용 사내 플러그인에 깊게 결합돼 있다면, 전환 작업량이 속도 이득보다 커질 수 있습니다. 이런 경우는 서두르지 말고 신규 프로젝트부터 uv로 시작하는 편이 현실적입니다.
오늘 사이드 프로젝트 하나만 먼저 옮겨보세요
지금까지 본 것처럼 uv로 파이썬 의존성 관리하기의 핵심은 속도보다 “파이썬 버전·가상환경·패키지·잠금 파일을 한 도구로 묶는다”는 구조 변화입니다. pip 프로젝트는 uv add -r requirements.txt 한 번으로 대부분 옮겨지고, poetry 프로젝트는 [tool.poetry]를 [project]로 수동 변환하는 작업이 필요합니다.
전체 서비스를 한 번에 옮기기보다는 운영 중이 아닌 사이드 프로젝트나 스크립트 하나부터 uv init으로 시작해 보시길 권합니다. 명령어 체계에 익숙해진 뒤 CI 설정과 팀 컨벤션까지 손볼 시점을 잡는 편이 안전합니다. 명령어와 옵션의 최신 목록은 uv 공식 문서에서 확인하실 수 있고, pyproject.toml 표준 명세 자체가 궁금하다면 PyPA의 pyproject.toml 규격 문서를, 가상환경의 기본 동작 원리는 파이썬 공식 문서의 venv 설명을 참고하시면 됩니다.
