uv로 파이썬 프로젝트를 빠르게 관리하기

파이썬으로 개발하다 보면 패키지 설치와 가상 환경 관리가 의외로 번거롭다는 걸 느끼게 되는데요. pip으로 패키지를 설치하고, venv로 가상 환경을 만들고, pyenv로 파이썬 버전을 바꾸고… 도구를 여러 개 써야 한다는 점이 특히 불편합니다.

uv는 이런 고민을 한 방에 해결해주는 도구입니다. Rust로 작성되어 pip보다 10~100배 빠르고 패키지 설치부터 가상 환경, 파이썬 버전 관리까지 하나의 도구로 전부 처리할 수 있습니다.

이번 글에서는 uv를 설치하고 실제 프로젝트에서 활용하는 방법을 하나씩 살펴보겠습니다.

uv 설치

uv는 독립 실행 바이너리라서 파이썬이 설치되어 있지 않아도 됩니다. Mac이나 Linux에서는 공식 설치 스크립트로 간단하게 설치할 수 있습니다.

curl -LsSf https://astral.sh/uv/install.sh | sh

Mac에서 Homebrew를 사용한다면 이 방법도 됩니다.

brew install uv

Windows에서는 PowerShell로 설치합니다.

powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"

설치가 끝나면 터미널을 새로 열고 버전을 확인해봅니다.

uv --version

프로젝트 생성

uv는 uv init 명령어로 프로젝트를 바로 만들 수 있습니다.

uv init my-project
cd my-project

이 명령어를 실행하면 다음과 같은 파일들이 생깁니다.

my-project/
├── .python-version
├── README.md
├── hello.py
└── pyproject.toml

pyproject.toml은 프로젝트의 메타 정보와 의존성을 관리하는 핵심 파일인데요. 기존에 requirements.txt나 setup.py로 관리하던 것들을 이 파일 하나로 통합할 수 있습니다.

[project]
name = "my-project"
version = "0.1.0"
description = "Add your description here"
readme = "README.md"
requires-python = ">=3.12"
dependencies = []

.python-version 파일에는 프로젝트에서 사용할 파이썬 버전이 적혀 있습니다. 팀원들이 동일한 파이썬 버전을 사용하도록 자연스럽게 맞춰주는 역할을 하죠.

이미 존재하는 디렉토리에서 프로젝트를 시작하고 싶다면 인자 없이 실행하면 됩니다.

mkdir my-project && cd my-project
uv init

패키지 추가와 제거

프로젝트에 패키지를 추가할 때는 uv add 명령어를 사용합니다.

uv add requests

이 명령어 하나로 가상 환경 생성과 패키지 설치, pyproject.toml 업데이트가 한꺼번에 이뤄집니다. 별도로 venv를 만들거나 pip install을 실행할 필요가 없어요.

프로젝트 디렉토리를 다시 살펴보면 .venv 디렉토리와 uv.lock 파일이 새로 생긴 것을 볼 수 있습니다.

my-project/
├── .python-version
├── .venv/
├── README.md
├── hello.py
├── pyproject.toml
└── uv.lock

uv.lock은 정확한 의존성 버전을 기록하는 락(lock) 파일입니다. 이 파일 덕분에 다른 컴퓨터에서도 완전히 동일한 패키지 버전을 재현할 수 있는데요. Git으로 꼭 커밋해두는 게 좋습니다.

pyproject.toml도 자동으로 업데이트됩니다.

[project]
name = "my-project"
version = "0.1.0"
description = "Add your description here"
readme = "README.md"
requires-python = ">=3.12"
dependencies = [
    "requests>=2.32.3",
]

특정 버전을 지정해서 설치하고 싶다면 버전 조건을 붙이면 됩니다.

uv add "requests>=2.31,<3"
uv add "flask==3.0.0"

개발 환경에서만 필요한 패키지는 --dev 플래그로 추가합니다. 테스트 프레임워크나 린터 같은 도구가 여기에 해당하죠.

uv add --dev pytest ruff

패키지를 제거할 때는 uv remove를 사용합니다.

uv remove requests

스크립트 실행

프로젝트 안에서 파이썬 스크립트를 실행할 때는 uv run 명령어를 사용합니다.

uv run hello.py

uv run은 프로젝트의 가상 환경을 자동으로 활성화한 상태에서 스크립트를 실행해줍니다. 가상 환경을 직접 활성화할 필요가 없어서 정말 편한데요. 가상 환경이 아직 없거나 의존성이 변경된 경우에는 실행 전에 알아서 동기화까지 해줘요.

pytest 같은 도구도 uv run으로 바로 실행할 수 있습니다.

uv run pytest
uv run ruff check .

의존성 동기화

팀 프로젝트에서 다른 사람이 패키지를 추가하고 커밋했다면 uv sync 명령어로 내 환경을 맞출 수 있습니다.

git pull
uv sync

uv sync는 uv.lock 파일을 기준으로 가상 환경의 패키지를 정확히 일치시켜 줍니다. npm의 npm install이나 bun의 bun install과 비슷한 역할이라고 생각하면 됩니다.

파이썬 버전 관리

uv가 특히 매력적인 부분은 파이썬 자체의 설치와 버전 관리도 해준다는 점입니다. 예전에는 pyenv를 따로 설치해야 했던 작업을 uv 하나로 할 수 있죠.

원하는 파이썬 버전을 설치할 때는 uv python install 명령어를 사용합니다.

uv python install 3.12
uv python install 3.11

설치된 파이썬 버전 목록은 uv python list로 확인할 수 있습니다.

uv python list

프로젝트에서 사용할 파이썬 버전을 고정하려면 uv python pin을 사용합니다. 이 명령어는 .python-version 파일을 업데이트해서 프로젝트의 파이썬 버전을 지정합니다.

uv python pin 3.12

pip 호환 인터페이스

기존에 pip와 requirements.txt를 사용하는 프로젝트에서 바로 uv를 활용할 수도 있습니다. uv pip 명령어는 pip과 거의 동일한 인터페이스를 제공하면서 속도만 훨씬 빠릅니다.

uv pip install requests
uv pip install -r requirements.txt
uv pip freeze
uv pip list

기존 프로젝트를 당장 pyproject.toml 기반으로 전환하기 어렵다면, 이 방식으로 먼저 속도 개선 효과를 누릴 수 있습니다.

일회성 도구 실행

프로젝트에 설치하지 않고 도구를 한 번만 실행하고 싶을 때가 있는데요. uvx 명령어가 바로 그 역할을 합니다. Node.js 생태계의 npx나 bunx와 같은 개념이에요.

uvx ruff check .
uvx black my_script.py
uvx httpie https://httpbin.org/get

uvx는 임시 환경에서 도구를 실행하고 나서 깔끔하게 정리해주기 때문에 글로벌 환경을 오염시키지 않습니다.

pip에서 uv로 전환

이미 requirements.txt를 사용하고 있는 프로젝트라면 uv로 자연스럽게 전환할 수 있습니다.

먼저 프로젝트 디렉토리에서 uv init을 실행합니다.

cd my-existing-project
uv init

기존 requirements.txt의 패키지들을 한꺼번에 추가합니다.

uv add $(cat requirements.txt)

이렇게 하면 pyproject.toml에 의존성이 기록되고 uv.lock 파일이 생성됩니다. 이후부터는 uv add와 uv remove로 패키지를 관리하면 되고, requirements.txt는 더 이상 필요하지 않습니다.

pip 대비 장점

uv가 기존 pip 생태계와 비교해서 어떤 점이 좋은지 정리해보겠습니다.

속도 차이가 압도적입니다. Rust로 작성된 uv는 패키지 해석(resolution)과 설치를 병렬로 처리하고 글로벌 캐시까지 활용하기 때문에 pip보다 체감상 10배 이상 빠릅니다.

pip + venv + pyenv처럼 여러 도구를 조합할 필요도 없어집니다. 파이썬 버전 설치부터 가상 환경, 패키지 관리까지 uv 하나로 전부 되니까 도구 고르느라 고민할 일이 줄어들죠.

uv.lock 락 파일 덕분에 모든 환경에서 동일한 의존성을 재현할 수 있다는 것도 큰 장점인데요. pip freeze로 생성한 requirements.txt와 달리 간접 의존성 버전까지 정확하게 고정해줍니다.

마치며

uv는 파이썬의 패키지 관리를 훨씬 편하게 만들어주는 도구입니다. pip, venv, pyenv를 각각 써야 했던 번거로움이 사라지고 속도까지 빨라서 한 번 쓰면 돌아가기 어렵습니다.

새로운 파이썬 프로젝트를 시작할 때는 uv init부터 해보시는 걸 추천드립니다. 기존 프로젝트도 uv pip 호환 인터페이스를 통해 점진적으로 전환할 수 있으니, 부담 없이 시도해보시면 좋겠습니다.

uv에 대해 더 자세한 내용은 uv 공식 문서를 참고하세요.