파이썬: uv - 패키지 관리 도구

🚀 uv란 무엇인가?

파이썬 패키지를 설치하고 관리하기 위한 만능 패키지 관리 도구.
Rust로 구현되어 있으며, 기존 pip보다 훨씬 빠른 설치 속도와
더 안전한 의존성 관리를 목표로 개발됨.

uv는 pip, pip-tools, pipenv를 모두 대체할 수 있도록 설계된 패키지 매니저이다.

최근에는 MCP(Model Context Protocol) 개발 등에 많이 활용되면서 큰 관심을 받고 있다.

❓ 왜 uv를 사용할까?

기존엔 파이썬 프로젝트를 관리할 때는 보통 다음 과정을 거쳤다.

python -m venv venv
source venv/Scripts/activate
pip install pandas

• python -m venv로 가상환경을 만들고,
• source로 가상환경을 활성화한 뒤,
• pip로 필요한 패키지를 설치하는 방식이다.

하지만 이 방법은 관리가 번거롭고, 패키지를 설치할 때마다 시간이 오래 걸리는 문제가 있었다.

또한, pip만으로는 의존성 충돌 관리나 lockfile 생성을 자동화하기 어렵고, poetry 같은 도구는 설정이 복잡하고 무겁게 느껴질 수 있다.

하지만, uv를 사용하면 상황이 완전히 달라진다.

uv를 사용하면, pip나 poetry 대비 10배에서 최대 100배까지 빠르게 패키지를 설치할 수 있다. Rust 기반 최적화 덕분이다.

또한, 프로젝트 관리 역시 훨씬 간단해진다.

uv init
uv add pandas

• uv init으로 프로젝트를 초기화하고,
• uv add 명령어로 필요한 패키지를 간편하게 추가할 수 있다.

추가로, uv는 가상환경을 직접 관리하기 때문에 python -m venv나 pyenv, virtualenv같은 명령어를 따로 신경 쓸 필요가 없다.

모든 패키지 의존성은 uv.lock 파일로 명확하게 기록되기 때문에, 다른 환경에서도 동일한 설치 결과를 재현할 수 있다.

✨ uv의 특징

항목	설명
🚀 설치 속도	Rust 기반, 기존 pip 대비 압도적으로 빠른 설치
🛠️ 의존성 관리	lockfile을 사용해 설치 환경을 완벽히 재현
🔗 CLI 통합	pip, pip-tools, pipenv 기능을 하나로 통합
🔄 호환성	기존 파이썬 프로젝트와 호환성 유지
⚡ 로컬 캐싱	설치한 패키지 캐싱으로 재설치 시 속도 최적화

🛠️ uv 설치 방법

Linux 및 macOS에서 uv는 다음과 같이 간단하게 설치할 수 있다. 설치 방법 참고

# curl 사용하기
curl -LsSf https://astral.sh/uv/install.sh | sh
# wget 사용하기
wget -qO- https://astral.sh/uv/install.sh | sh
# 특정 버전 설치하기
curl -LsSf https://astral.sh/uv/0.6.14/install.sh | sh

혹은 기존 패키지 관리 도구로 설치 가능하다.

pip install uv

설치가 완료되었으면, 다음 명령어로 설치 여부를 확인할 수 있다.

uv --version

🧪 uv 사용해보기

🏗️ 프로젝트 생성

uv init test
cd test

uv init 명령어를 사용하면,
현재 디렉토리를 uv 프로젝트로 초기화하거나,
새로운 프로젝트 폴더를 생성할 수 있다.

위 예시에서는 test라는 이름의 uv 프로젝트를 생성하였다.

생성된 test 폴더의 구조는 다음과 같다.

test/
├── .git
├── .gitignore
├── .python-version
├── README.md
├── main.py
└── pyproject.toml

• .python-version을 통해 파이썬 버전이 고정된다.
• pyproject.toml은 의존성 및 프로젝트 메타데이터를 정의하는 핵심 파일이다.
• .venv 폴더는 의존성을 관리하기 위한 폴더이다.

.venv 폴더는 실제로 패키지를 설치하거나 uv sync를 실행할 때 생성된다.

➕ 패키지 추가

패키지를 추가하는 것도 매우 간단하다.

uv add pandas

• uv add 명령어를 사용하면 패키지를 설치하고,
• pyproject.toml과 uv.lock에 의존성이 자동으로 기록된다.

추가적으로 로컬 캐시를 활용하여, 설치 속도가 pip에 비해 월등히 빠르다.

📋 설치된 패키지 확인

현재 설치된 패키지 목록을 확인하려면

uv pip list

또는,

uv pip freeze

를 사용할 수 있다.
pip 명령어처럼 사용할 수 있다는 점이 매우 직관적이다.

🔄 의존성 동기화

만약 다른 개발자가 이 프로젝트를 클론했다면, 다음 명령어 하나로 모든 환경을 재현할 수 있다.

uv sync

• uv.lock 파일을 기준으로 정확히 동일한 패키지 버전이 설치된다.
• 프로젝트 환경 복원이 완벽하게 보장된다.

▶️ 실행 테스트

초기화 시 생성된 main.py 파일을 실행해보자.

uv run main.py

기본적으로 Hello, world!가 출력된다.

필요에 따라 main.py에 코드를 추가해서 본격적인 개발을 진행하면 된다.

---

uv는 빠르고 직관적이며, 가상환경과 의존성 관리를 통합한 덕분에 파이썬 프로젝트를 훨씬 효율적으로 관리할 수 있다.

아마 이제 아나콘다처럼 무겁고 복잡한 환경은 점점 필요 없어지지 않을까 싶다.

📚 References

uv 공식 문서 - Getting Started