Python 패키지 관리자 uv 소개 및 사용 방법

UV는 Rust로 작성된 매우 빠른 Python 패키지 및 프로젝트 관리자다.

의존성 설치 속도 비교

❓ UV를 왜 써야 할까?

Python 프로젝트를 할 때 흔히 겪는 문제들이 있다.

• `pip install` 이 느린 문제
• 가상환경을 만들고 관리해줘야 하는 문제
• 의존성 관리를 위해 `pip freeze > requirements.txt`
• `pipx`, `pyenv`, `venv` 등등 도구가 너무 많음

UV는 이 모든 걸 하나로 합쳐서 빠르게 해결해 준다.

 

✨ UV의 장점

• 🚀 올인원 도구: `pip`, `pip-tools`, `pipx`, `poetry`, `pyenv`, `twine`, `virtualenv` 등 여러 도구를 하나로 통합
• ⚡️최고 속도: 기존 `pip`보다 10~100배 빠름
• 🗂️ 프로젝트 관리: 잠금 파일(lockfile) 기반으로 종속성 일관성 보장
• ❇️ 스크립트 실행: 파일 내에 의존성을 정의하고 바로 실행 가능
• 🐍 Python 버전 관리: 다양한 Python 버전 설치 및 전환 가능
• 🛠️ CLI 도구 설치/실행: `pipx`처럼 도구를 설치하고 실행 가능
• 🔩 pip 호환 인터페이스: 기존 명령어 사용 그대로, 성능은 업그레이드
• 🏢 워크스페이스 지원: 대규모 프로젝트 구조(Cargo 스타일) 지원
• 💾 디스크 효율적: 전역 캐시를 활용해 의존성 중복 제거
• ⏬ 쉬운 설치: Rust나 Python 없이도 `curl`, `pip`로 간단 설치
• 🖥️ 크로스 플랫폼: macOS, Linux, Windows 모두 지원

라고 공식 Docs에 나와있지만 실제로 사용하여 얼마나 편리한지 알아보자.

 

🛰️ 설치

macOS, Linux

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

 

Windows

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

설치 후에 Docs에 나와있는 예제를 따라 해보며 명령어들을 익혀본다.

 

 

1. 프로젝트 초기화

example이라는 이름으로 새로운 python 프로젝트를 생성한다.

(pyproject.toml 파일이 만들어지고 기본 구조가 세팅됨)

uv init example

2. 프로젝트 폴더로 이동

cd example

3. 패키지 추가

코드 스타일 검사 도구인 `ruff` 를 설치한다.

uv add ruff

4. 코드 검사 실행

`ruff` 를 실행해서 현재 프로젝트 내 Python 코드의 스타일을 검사한다.

uv run ruff check

5. 의존성 잠금

현재 설치된 패키지 상태를 기준으로 `uv.lock` 파일을 생성한다.

협업이나 배포 시 같은 환경으로 재현하는 데 유용

uv lock

6. 의존성 동기화

`uv.lock` 파일을 기준으로 `.venv` 가상환경을 정확하게 재구성한다.

uv sync

이외에도 다양한 기능들을 제공하니 공식 문서를 참고해 주세요.

✳️ Pycharm 연동

우선 해당 프로젝트에 `.venv` 폴더가 생긴 것을 확인해야 한다. 없다면 `uv venv` 로 수동으로 만들 수 있다.

 

이후에 Pycharm에서 인터프리터 설정을 해줘야 한다.

1. File > Setting > Project:[프로젝트 이름] > Python Interpreter

 

2. Add Interpreter > Add Local Interpreter

 

3. Select Existing > 📁 > 경로 선택 > OK > Apply

 

 

 

<프로젝트 경로>/.venv/bin/pyhon

 

🐱 Github

Github에 프로젝트를 올려야 할 때는 `pyproject.html` 과 `uv.lock` 만 올리고 `.venv` 폴더는 올리면 안된다. `.gitignore` 에 `.venv` 추가가 필요하다. (경우에 따라 `.python-version` 파일도 올려도 됨.

`pyproject.toml` : 프로젝트의 의존성, 설정, 메타데이터가 정의

`uv.lock` : 정확한 패키지 버전 고정 → 다른 사람이 `uv sync` 로 똑같은 환경 재현 가능

프로젝트를 Clone 하여 쓸 때는 `uv sync` 만 입력하면 동일한 개발 환경이 세팅된다.

💫 ETC

uv add <패키지>

`uv add` 는 프로젝트에 정식으로 필요한 패키지 일 때 `pyproject.toml` 에 추가돼서 협업자도 `uv sync` 로 동일 환경을 만들 수 있다.

uv pip install <패키지>

`uv pip install` 은 의존성 파일에 남지 않아 잠깐 테스트를 하거나 임시로 써볼 때 사용하면 된다.

특정 패키지 삭제하고 싶을 때

`pyproject.toml` 에서 제거되고, `uv.lock` 에도 반영된다.

이후에 `uv sync` 로 실제 `.venv` 에서도 삭제.

uv remove <패키지명>

Python Version

Python을 설치하고 버전 간에 빠르게 전환도 가능하다.

uv python install 3.10 3.11 3.12
uv python pin 3.10

 

 

📄 참고 자료

https://docs.astral.sh/uv/