Python UV를 활용한 효율적이고 빠른 패키지 관리 방법

🔹 1. UV란?

UV 공식 문서

• Rust로 작성된 고성능 Python 패키지 및 프로젝트 관리 도구로 pip, virtualenv, poetry 등을 대체할 수 있는 빠르고 효율적인 패키지 관리 도구입니다.

• 흔히 사용되는 pip이나 poetry 같은 다른 도구들에 비해 패키지 설치가 엄청나게 빠른 것이 특징입니다.
  

• uv init만으로 가상환경이 자동으로 구성되어, 별도의 Python 가상환경 설치 없이 즉시 개발을 시작할 수 있습니다.

• pyproject.toml, uv.lock 파일을 활용해 의존성 명시 및 재현 가능한 환경 구성 보장합니다.
  

🔹 2. UV 설치 및 초기 설정

1) 설치

• pip 설치가 되어 있지 않은 경우

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

# Windows (PowerShell)
powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"

• pip 설치가 되어 있는 경우

pip install uv

• 설치 확인

uv --version

uv 0.7.14 (e7f596711 2025-06-23)

2) 작업 디렉토리 초기 설정

Git에서 git init 명령어를 통해 디렉토리를 Git으로 관리하겠다고 선언하듯, uv 역시 uv init 명령어를 통해 작업 디렉토리를 초기화해야 uv 기능을 사용할 수 있습니다.
즉, uv를 사용하기 위해서는 최초에 uv init 명령어로 해당 디렉토리를 설정해주는 과정이 필요합니다.

# 작업 디렉토리 설정 초기화
uv init

# 디렉토리 생성 + 초기화
uv init my-project

• .python-version: 프로젝트에서 사용할 Python 버전이 명시된 파일입니다.
• main.py: 실행 또는 테스트를 위한 기본 Python 스크립트 파일입니다.
• pyproject.toml: 프로젝트의 메타데이터와 빌드 설정, 의존성 등을 정의하는 표준 구성 파일입니다.
• README.md: 프로젝트의 목적과 사용법 등을 설명하는 문서 파일입니다.

🔹 3. 패키지 관리 및 실행

1) 패키지 설치 & 삭제

• 기존에 pip install 명령어를 통해 설치했던 파이썬 라이브러리들 역시 uv에서는 uv 문법에 맞게 설치 및 삭제를 진행해주어야 합니다.

# 패키지 추가
uv add [패키지 명]
uv add requests pandas faker

# 패키지 제거
uv remove [패키지 명]

• requirements.txt 파일에 정리된 라이브러리들을 한 번에 설치하고자 한다면 아래 명령어로 가능합니다.

uv pip install -r requirements.txt

• 추가된 패키지는 pyproject.toml 파일의 dependencies 항목에 저장되며, 삭제시엔 해당 항목에서 사라집니다.
  

2) python 파일 실행

• uv로 패키지 관리가 되는 디렉토리의 python 파일을 실행할 경우 uv run 명령어를 활용하는 것이 가장 좋습니다.
• 물론 python 명령어를 통해 실행하는 것도 가능하지만 터미널에서 가상환경을 따로 활성화시킨 후 실행을 해야합니다.

실행 방식	가상환경 적용	권장 여부
uv run main.py	✅ 자동 적용	✅ 추천
source .venv/bin/activate && python main.py	✅ 수동 적용	⭕ 가능하나 불편
python main.py	❌ 기본 환경 사용	❌ 권장하지 않음

uv를 통한 실행

python을 통한 실행 (가상환경 활성화 + 실행)

• uv로 생성한 가상환경 활성화시 uv init 때 명시한 작업 디렉토리 이름으로 가상환경이 활성화됩니다.
  

🔹 4. Python 버전 변경

• pip을 사용하는 경우, 중간에 가상환경의 Python 버전을 변경하려면 기존 가상환경 삭제 → 새로운 버전의 가상환경 생성 → 라이브러리 설치 → python 파일 실행 이 순서로 작업이 진행되어야 합니다.
• 특히 기존 가상환경이 무겁거나 복잡하게 구성된 경우, 삭제하거나 새로 설정하는 데 시간이 오래 걸려 Python 버전 변경 작업이 매우 번거롭고 귀찮게 느껴질 수 있습니다.
• 하지만 uv를 사용하는 경우, 작업 디렉토리 내의 .python-version과 pyproject.toml 파일만 수정하면, 기존 디렉토리를 그대로 유지한 채 가상환경의 Python 버전만 간편하게 변경할 수 있습니다.

.python-version

pyproject.toml

• 위 두 파일에서 Python 버전 변경 후 uv run main.py 명령어를 치게되면 아래의 과정을 자동으로 수행하게 됩니다.
  • 기존 가상환경 제거 → 새로운 가상환경 생성 → 패키지 설치 → 실행

🔹 5. pip vs uv

🔹 6. OUTRO

• 기존에는 대부분의 Python 프로젝트에서 pip과 venv 조합을 사용했고, 지금도 많이 사용되고 있습니다. 하지만 느린 속도, Python 버전 변경의 어려움 등 pip이 가지는 명확한 한계점이 있었습니다.
• uv는 이를 보완하고 Python의 패키지 관리를 더욱 효율적이고 빠르게 할 수 있도록 개발된 도구입니다. 특히 Python 버전 관리나 가상환경 설정, 의존성 설치 속도 등에서 uv는 매우 강력한 이점을 제공합니다.
• uv는 독자적인 디렉토리 구조를 가지고 있지만 기존 pip로 설치된 디렉토리와도 높은 호환성을 유지해, 기존 프로젝트를 완전히 갈아엎지 않아도 자연스럽게 도입할 수 있습니다. 이처럼 부담 없이 도입이 가능하면서도 더 나은 개발 환경을 제공한다는 점에서 매우 매력적입니다.
• 최근에는 MCP를 비롯해 다양한 오픈소스 프로젝트와 팀들이 uv를 표준 툴로 채택해가고 있는 추세입니다.
• 이제 Python 프로젝트를 시작하거나 기존 환경을 개선할 계획이 있다면, uv를 적극 고려해보세요. 빠르고 가벼우며, 무엇보다 개발자의 귀찮음을 줄여주는 도구입니다.