pip 대신에 uv 사용하기

Python
Package manager
Virtual environment
Data science
Tip
Author

Taeyoon Kim

Published

August 24, 2024

Modified

May 2, 2025

pip 는 파이썬 패키지 관리자로 유용하지만 아래와 같은 몇 가지 근본적인 문제가 있습니다. 특히 패키지 의존성과 환경 관리는 문제가 터지면 해결하기가 아주 어렵습니다.

1 pip이 가지는 문제

  1. 의존성 충돌 (Dependency Conflicts)

여러 패키지를 설치할 때 각 패키지가 서로 다른 버전의 동일한 종속성을 요구할 경우 의존성 충돌이 발생하며 프로젝트에서 예기치 않은 동작이나 오류를 발생시킬 수 있습니다.

  1. 글로벌 설치 문제

기본적으로 pip 는 전역 파이썬 환경에 패키지를 설치합니다. 이로 인해, 여러 프로젝트에서 동일한 패키지 버전을 공유하게 되어 프로젝트 간에 종속성 충돌이 발생할 수 있습니다. 특히, 프로젝트마다 요구되는 패키지 버전이 다른 경우에 문제가 됩니다.

  1. 환경 관리의 어려움

pip 는 파이썬 환경을 별도로 관리하지 않으므로 전역 환경에 설치된 패키지들이 서로 영향을 미칠 수 있습니다. 이로 인해, 동일한 시스템에서 여러 프로젝트를 작업할 때 각 프로젝트의 요구 사항을 일관되게 유지하기 어려워집니다. 이를 해결하기 위해 virtualenv 와 같은 도구를 사용해 가상 환경을 생성해야 합니다.

  1. 보안 문제

pip 는 기본적으로 모든 패키지를 신뢰합니다. 악의적인 사용자가 배포한 패키지가 PyPI 에 업로드되면, 이를 설치하는 과정에서 보안 문제가 발생할 수 있습니다.

  1. 복잡한 패키지 관리

복잡한 프로젝트에서는 수많은 패키지와 버전들을 관리해야 하는데, pip 는 기본적으로 이러한 복잡한 종속성 트리를 관리하는 데 최적화되어 있지 않습니다. 이는 특정 패키지 설치 시 종속성 문제가 발생할 때 수동으로 해결해야 하는 번거로움으로 이어질 수 있습니다. 이러한 문제들로 인해, 많은 개발자들이 pipenv 또는 poetry 같은 도구들을 사용하여 환경과 패키지 관리를 하고 있습니다.

2 uv 소개

uv(Unified Python packaging) 는 Rust 로 작성된 pip 워크플로우를 대체하는 매우 빠른 파이썬 패키지 설치 프로그램입니다. 캐싱 없이 pip 보다 8-10 배 빠르며, 캐시가 있을 때는 80-115 배 빠릅니다. 또한 전역 모듈 캐시를 사용하여 의존성을 다시 다운로드하거나 빌드하지 않고 디스크 공간 사용을 최소화합니다.

2.1 특징

  • ⚖️ 일반적인 pip, pip-tools, virtualenv 명령을 드롭인 방식으로 대체합니다.
  • ⚡️ pip 및 pip-tools(pip-compile 및 pip-sync) 보다 10-100배 빠르다. 
  • 💾 종속성 중복 제거를 위한 글로벌 캐시로 디스크 공간 효율을 높입니다.
  • 🐍 Rust 나 Python 없이 curl, pip, pipx 등을 통해 바이너리로 설치할 수 있습니다.
  • 🧪 상위 10,000 개의 PyPI 패키지를 대상으로 대규모 테스트 완료.
  • 🖥️ macOS, Linux, Windows 를 지원합니다.
  • 🧰 고급 기능인 종속성 버전 재정의 및 대체 해결 전략 등을 포함.
  • ⁉️ 현존하는 패키지 관리 중 가장 자세한 오류 메시지와 충돌 추적 해결사 제공.
  • 🤝 편집 가능한 설치, Git 종속성, 직접 URL 종속성, 로컬 종속성, 제약 조건, 소스 배포, HTML 및 JSON 인덱스 등을 포함한 광범위한 기능 지원.

3 설치 및 사용 방법

3.1 설치

uv를 설치하는 여러 가지 방법을 안내합니다. 자신의 환경에 맞는 방법을 선택하세요.

독립 실행형 설치 프로그램 사용

운영체제에 맞는 명령어를 터미널(명령 프롬프트)에 입력하여 설치합니다.

  • macOS 및 Linux: bash curl -LsSf https://astral.sh/uv/install.sh | sh
  • Windows: powershell powershell -c "irm https://astral.sh/uv/install.ps1 | iex"
  • 특정 버전 설치 (예: 0.2.29):
    • macOS 및 Linux: bash curl -LsSf https://astral.sh/uv/0.2.29/install.sh | sh
    • Windows: powershell powershell -c "irm https://astral.sh/uv/0.2.29/install.ps1 | iex"

** 기존 파이썬 패키지 관리자 사용**

이미 pip 또는 pipx, Homebrew를 사용하고 있다면 다음 명령어로 uv를 설치할 수 있습니다.

  • pip 사용: bash pip install uv
  • pipx 사용: bash pipx install uv
  • Homebrew 사용 (macOS): bash brew install uv

3.2 가상 환경 관리

프로젝트별로 독립된 환경을 만들어 패키지를 관리할 수 있습니다.

가상 환경 생성:

uv venv # 현재 폴더에 .venv라는 이름으로 가상 환경 생성

가상 환경 활성화:

운영체제에 따라 다른 명령어를 사용합니다. 활성화되면 터미널 프롬프트 앞에 (.venv)와 같은 표시가 나타납니다.

  • macOS 및 Linux: bash source .venv/bin/activate
  • Windows: bash .venv\Scripts\activate

3.3 패키지 설치

활성화된 가상 환경에 필요한 파이썬 패키지를 설치합니다.

  • 최신 버전 설치: bash uv pip install flask # Flask 패키지의 최신 버전 설치
  • 특정 버전 설치: bash uv pip install flask==2.0.0 # Flask 패키지 2.0.0 버전 설치
  • requirements.txt 파일에서 설치: bash uv pip install -r requirements.txt # requirements.txt 파일에 명시된 패키지들을 설치
  • 현재 프로젝트를 편집 가능한 모드로 설치: bash uv pip install -e . # 개발 중인 프로젝트를 설치하여 코드 변경 사항이 즉시 반영되도록 함
  • 로컬 패키지 파일에서 설치: bash uv pip install "package @ ." # 현재 폴더에 있는 패키지 파일을 설치
  • 추가 의존성을 포함하여 설치: bash uv pip install "flask[dotenv]" # Flask와 함께 dotenv 의존성을 함께 설치

3.4 의존성 관리 파일 생성 및 동기화

프로젝트에 필요한 패키지 목록을 파일로 저장하고 관리합니다.

requirements.txt 파일 생성:

다양한 방법으로 현재 환경의 패키지 목록 또는 특정 설정 파일에서 requirements.txt 파일을 생성할 수 있습니다.

  • requirements.in 파일에서 생성: bash uv pip compile requirements.in -o requirements.txt
  • pyproject.toml 파일에서 생성: bash uv pip compile pyproject.toml -o requirements.txt
  • setup.py 파일에서 생성: bash uv pip compile setup.py -o requirements.txt
  • 터미널 입력에서 생성: bash echo flask | uv pip compile - -o requirements.txt
  • 현재 활성화된 환경의 패키지 목록 저장: bash uv pip freeze | uv pip compile - -o requirements.txt

** requirements.txt 파일로 패키지 설치:**

생성한 requirements.txt 파일에 명시된 패키지들을 가상 환경에 설치합니다.

uv pip sync requirements.txt

uv의 pip install 및 pip compile 명령어는 -r, -c, -e, --index-url과 같은 기존 pip 옵션들을 그대로 지원합니다.

3.5 uv 핵심 기능 활용

uv는 파이썬 버전 관리 프로젝트 초기화 의존성 관리 등 다양한 편리한 기능을 제공합니다.

3.5.1 Python 버전 관리

명령어 설명 예시
uv python install <버전> 지정한 Python 버전 설치 uv python install 3.12
uv python list 설치 가능한 Python 버전 목록 표시 uv python list
uv use <버전> 현재 디렉토리에 .python-version 파일 생성하여 기본 Python 버전 지정 uv use 3.11

3.5.2 프로젝트 초기화 및 구성

명령어 설명 생성되는 파일/디렉토리
uv init 기본 프로젝트 초기화 pyproject.toml .python-version
uv init --package 패키지 형태 프로젝트 생성 pyproject.toml .python-version src/
uv init --lib 배포용 라이브러리 프로젝트 생성 라이브러리 구조의 pyproject.toml 테스트 디렉토리 등

3.5.3 의존성 관리

명령어 설명 예시
uv add <패키지> 의존성 추가 uv add requests
uv add --dev <패키지> 개발용 의존성 추가 uv add --dev pytest black
uv remove <패키지> 의존성 제거 uv remove requests
uv lock 락파일 생성/갱신 uv lock

uv는 하드 링크를 통해 디스크 공간을 효율적으로 사용합니다. 여러 가상 환경에서 동일한 패키지를 사용하더라도 실제 파일은 한 번만 저장됩니다.

3.5.4 5.4. 다른 도구에서 마이그레이션

기존 프로젝트의 설정을 uv로 가져올 수 있습니다.

# 1. 프로젝트 폴더로 이동
cd existing-project

# 2. uv 프로젝트 초기화
uv init

# 3. requirements.txt 파일이 있는 경우 패키지 추가
cat requirements.txt | xargs uv add

# 4. 의존성 잠금 및 동기화
uv lock
uv sync

3.5.5 빌드 및 배포

uv를 사용하여 패키지를 빌드하고 PyPI에 배포할 수 있습니다.

# 패키지 빌드
uv build

# PyPI에 배포
uv publish

3.5.6 실사용 예시

아래는 데이터 과학 프로젝트를 시작하는 과정을 보여줍니다.

# 1. 프로젝트 폴더 생성
mkdir ds-project
cd ds-project

# 2. 프로젝트 초기화 및 Python 버전 설정
uv init --package
uv python install 3.11
uv use 3.11

# 3. 데이터 과학 관련 패키지 설치
uv add numpy pandas matplotlib scikit-learn

# 4. 개발 도구 설치
uv add --dev ipython jupyterlab black ruff

# 5. 의존성 잠금 및 동기화
uv lock
uv sync

# 6. Jupyter Lab 실행
uv run jupyter lab

4 마치며

또 새로운 파이썬 패키지 매니저가 나와서 더욱 혼란이 가중되는 것 같습니다. 그러나 uv 의 경이로운 속도를 겪어보니 생각이 또 바뀝니다. 파이썬 생태계가 더욱 일관되고 효율적으로 발전되길 바라면서 앞으로는 pip 는 사용하지 않고 uv 만을 써야겠습니다. uv 에 대하여 더 자세한 내용은 공식 repo 와 공식 문서 를 읽어보세요.