Developjik Blog

CTRL K

uv는 Rust로 작성된 초고속 Python 패키지 설치 및 가상 환경 관리 도구입니다. 기존 pip 및 pip-tools의 대체품으로, 10배 이상 빠른 속도와 현대적인 사용자 경험을 제공합니다.

이 가이드를 읽으면 uv를 사용하여 Python 프로젝트의 의존성을 효율적으로 관리하고, 가상 환경을 빠르게 생성 및 관리하는 방법을 배울 수 있습니다.

개요

배경

왜 uv가 필요한가?

Python 생태계에서 패키지 관리는 오랫동안 다음과 같은 문제를 겪어왔습니다:

느린 설치 속도: pip는 Python으로 작성되어 대규모 프로젝트에서 설치가 느림
복잡한 의존성 해결: 의존성 충돌 해결이 비효율적
일관성 문제: 동일한 환경 재현이 어려움
도구 분산: venv, virtualenv, pip, pip-tools 등 여러 도구를 조합해서 사용

uv는 이러한 문제를 해결하기 위해 Astral 팀이 개발한 차세대 도구입니다.

등장 이전의 방식

기존에는 다음과 같은 도구 조합을 사용했습니다:


# 가상 환경 생성
python -m venv .venv
source .venv/bin/activate  # Windows: .venv\Scripts\activate
 
# 패키지 설치
pip install requests
pip install -r requirements.txt
 
# 의존성 잠금
pip freeze > requirements.txt

동작 원리

핵심 메커니즘

uv는 다음과 같은 방식으로 작동합니다:

Rust 기반 구현: 네이티브 바이너리로 컴파일되어 Python 인터프리터 없이 실행
병렬 다운로드: 여러 패키지를 동시에 다운로드하여 속도 향상
스마트 캐싱: 전역 캐시를 사용하여 중복 다운로드 방지
빠른 해석: Rust의 고성능 의존성 해석 알고리즘 사용

아키텍처


[uv CLI]
   ↓
[의존성 해석 엔진]
   ↓
[병렬 다운로드 시스템] ← [전역 캐시]
   ↓
[가상 환경 관리자]
   ↓
[Python 프로젝트]

설치

macOS / Linux


# Homebrew 사용
brew install uv
 
# 또는 curl 사용
curl -LsSf https://astral.sh/uv/install.sh | sh

Windows


# PowerShell 사용
powershell -c "irm https://astral.sh/uv/install.ps1 | iex"
 
# 또는 pip 사용
pip install uv

설치 확인


uv --version
# 출력 예시: uv 0.1.0

주요 기능

기능 1: 초고속 패키지 설치

uv는 pip보다 10-100배 빠른 패키지 설치 속도를 제공합니다.


# pip 방식 (느림)
pip install pandas numpy scikit-learn
# 소요 시간: ~45초
 
# uv 방식 (빠름)
uv pip install pandas numpy scikit-learn
# 소요 시간: ~3초

성능 비교:

100개 패키지 설치: pip (2분) vs uv (10초)
의존성 해석: pip (30초) vs uv (1초)

기능 2: 가상 환경 관리


# 가상 환경 생성
uv venv
 
# 특정 Python 버전 지정
uv venv --python 3.11
 
# 커스텀 경로 지정
uv venv .venv-custom

기능 3: 의존성 잠금

requirements.txt보다 강력한 의존성 잠금 파일을 생성합니다.


# 의존성 설치 및 잠금
uv pip compile requirements.in -o requirements.txt
 
# 잠금 파일로부터 설치
uv pip sync requirements.txt

실제 사용 사례

사례 1: 새 프로젝트 시작하기


# 1. 프로젝트 디렉토리 생성
mkdir my-project
cd my-project
 
# 2. 가상 환경 생성
uv venv
 
# 3. 가상 환경 활성화
source .venv/bin/activate  # Windows: .venv\Scripts\activate
 
# 4. 패키지 설치
uv pip install fastapi uvicorn
 
# 5. 의존성 파일 생성
uv pip freeze > requirements.txt

사례 2: 기존 프로젝트 복제 및 설정


# 1. 저장소 클론
git clone https://github.com/user/project.git
cd project
 
# 2. 가상 환경 생성
uv venv
 
# 3. 가상 환경 활성화
source .venv/bin/activate
 
# 4. 의존성 설치 (초고속)
uv pip install -r requirements.txt
# 100개 이상 패키지도 10초 이내 완료

사례 3: 의존성 업데이트


# requirements.in 파일 생성
cat > requirements.in << EOF
fastapi>=0.100.0
uvicorn[standard]
sqlalchemy>=2.0.0
EOF
 
# 의존성 해석 및 잠금
uv pip compile requirements.in -o requirements.txt
 
# 잠금된 버전으로 설치
uv pip sync requirements.txt

주요 명령어

가상 환경 관련


# 가상 환경 생성
uv venv [경로]
 
# Python 버전 지정
uv venv --python 3.11
uv venv --python python3.12
 
# 시스템 패키지 접근 허용
uv venv --system-site-packages

패키지 설치


# 단일 패키지 설치
uv pip install requests
 
# 여러 패키지 설치
uv pip install requests pandas numpy
 
# 특정 버전 설치
uv pip install "django>=4.2,<5.0"
 
# requirements.txt로 설치
uv pip install -r requirements.txt
 
# 개발 의존성 설치
uv pip install -r requirements-dev.txt

패키지 관리


# 패키지 제거
uv pip uninstall requests
 
# 설치된 패키지 목록
uv pip list
 
# 패키지 정보 확인
uv pip show requests
 
# 의존성 트리
uv pip tree

의존성 잠금


# requirements.in → requirements.txt 생성
uv pip compile requirements.in
 
# 업그레이드 포함
uv pip compile requirements.in --upgrade
 
# 특정 패키지만 업그레이드
uv pip compile requirements.in --upgrade-package django
 
# 플랫폼별 잠금 파일
uv pip compile requirements.in --universal

장점과 한계

장점

✅ 극도로 빠른 속도: pip 대비 10-100배 빠름
✅ 현대적인 UX: 직관적이고 명확한 에러 메시지
✅ 정확한 의존성 해석: 충돌 사전 감지
✅ 전역 캐시: 디스크 공간 절약 및 재설치 최적화
✅ pip 호환성: 기존 pip 명령어와 거의 동일한 인터페이스
✅ 단일 바이너리: Python 설치 없이도 실행 가능

한계

⚠️ 새로운 도구: 생태계가 pip만큼 성숙하지 않음
⚠️ 일부 특수 케이스: 매우 복잡한 의존성에서 가끔 문제 발생
⚠️ Windows 지원: macOS/Linux보다 약간 덜 안정적 (개선 중)

트레이드오프

uv를 사용해야 하는 경우:

대규모 프로젝트 (100개 이상 의존성)
CI/CD 파이프라인 최적화 필요
팀 협업에서 일관된 환경 보장
빠른 개발 사이클 필요

pip을 고수해야 하는 경우:

매우 특수한 레거시 패키지 사용
완전히 검증된 도구만 사용 가능한 환경
Windows 환경에서 안정성 최우선

pip 대비 성능 비교

벤치마크 결과

작업	pip	uv	속도 향상
Django + 의존성 설치	30초	2초	15배
NumPy/Pandas 설치	45초	3초	15배
100개 패키지 설치	120초	10초	12배
의존성 해석	30초	1초	30배

실제 프로젝트 사례


# 대규모 데이터 과학 프로젝트
# requirements.txt: 150개 패키지
 
# pip 방식
time pip install -r requirements.txt
# real: 3m 45s
# user: 2m 30s
# sys: 0m 15s
 
# uv 방식
time uv pip install -r requirements.txt
# real: 0m 18s
# user: 0m 8s
# sys: 0m 4s
 
# 결과: 12.5배 빠름

pip-tools와의 비교

pip-tools 방식


# pip-tools 설치
pip install pip-tools
 
# 의존성 컴파일
pip-compile requirements.in
# 소요 시간: ~20초
 
# 설치
pip-sync requirements.txt
# 소요 시간: ~60초

uv 방식


# uv는 별도 설치 불필요 (단일 바이너리)
 
# 의존성 컴파일
uv pip compile requirements.in
# 소요 시간: ~1초
 
# 설치
uv pip sync requirements.txt
# 소요 시간: ~5초

주요 차이점:

속도: uv가 15-20배 빠름
설치: uv는 단일 바이너리, pip-tools는 Python 패키지
호환성: uv는 pip-tools 워크플로우와 완전 호환

실전 워크플로우

개발 환경 설정


# 1. 프로젝트 초기화
mkdir awesome-project
cd awesome-project
 
# 2. 가상 환경 생성
uv venv
 
# 3. 활성화
source .venv/bin/activate
 
# 4. requirements.in 작성
cat > requirements.in << 'EOF'
# 웹 프레임워크
fastapi>=0.100.0
uvicorn[standard]>=0.23.0
 
# 데이터베이스
sqlalchemy>=2.0.0
alembic>=1.11.0
 
# 유틸리티
pydantic>=2.0.0
python-dotenv>=1.0.0
EOF
 
# 5. 의존성 잠금
uv pip compile requirements.in -o requirements.txt
 
# 6. 설치
uv pip sync requirements.txt

CI/CD 파이프라인 통합

GitHub Actions 예시:


name: CI
 
on: [push, pull_request]
 
jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
 
      - name: Install uv
        run: curl -LsSf https://astral.sh/uv/install.sh | sh
 
      - name: Set up Python
        run: uv venv --python 3.11
 
      - name: Install dependencies
        run: |
          source .venv/bin/activate
          uv pip sync requirements.txt
 
      - name: Run tests
        run: |
          source .venv/bin/activate
          pytest

속도 개선:

Before (pip): CI 실행 시간 5분
After (uv): CI 실행 시간 2분
절감: 60%

멀티 프로젝트 관리


# 프로젝트 구조
workspace/
├── project-a/
│   ├── requirements.in
│   └── requirements.txt
├── project-b/
│   ├── requirements.in
│   └── requirements.txt
└── shared-venv/
 
# 공유 가상 환경 생성
cd workspace
uv venv shared-venv
 
# 프로젝트별 의존성 설치
source shared-venv/bin/activate
uv pip install -r project-a/requirements.txt
uv pip install -r project-b/requirements.txt

마이그레이션 가이드

pip에서 uv로 전환

1단계: uv 설치


# macOS/Linux
curl -LsSf https://astral.sh/uv/install.sh | sh
 
# Windows
powershell -c "irm https://astral.sh/uv/install.ps1 | iex"

2단계: 기존 명령어 변환

pip 명령어	uv 명령어
`pip install package`	`uv pip install package`
`pip install -r requirements.txt`	`uv pip install -r requirements.txt`
`pip freeze > requirements.txt`	`uv pip freeze > requirements.txt`
`pip list`	`uv pip list`
`pip show package`	`uv pip show package`
`pip uninstall package`	`uv pip uninstall package`

3단계: 의존성 잠금 개선


# 기존 requirements.txt가 있다면
# requirements.in 파일 생성 (주요 의존성만)
cat > requirements.in << 'EOF'
django>=4.2
djangorestframework>=3.14
celery>=5.3
EOF
 
# 정확한 버전 잠금
uv pip compile requirements.in -o requirements.txt
 
# 설치
uv pip sync requirements.txt

4단계: 스크립트 업데이트


# Before
pip install -r requirements.txt
 
# After
uv pip install -r requirements.txt
 
# 또는 alias 설정
echo 'alias pip="uv pip"' >> ~/.bashrc
source ~/.bashrc

문제 해결

문제 1: “uv: command not found”

원인: PATH에 uv가 추가되지 않음

해결:


# macOS/Linux
echo 'export PATH="$HOME/.cargo/bin:$PATH"' >> ~/.bashrc
source ~/.bashrc
 
# Windows PowerShell (관리자 권한)
[Environment]::SetEnvironmentVariable(
    "Path",
    [Environment]::GetEnvironmentVariable("Path", "User") + ";$HOME\.cargo\bin",
    "User"
)

문제 2: 특정 패키지 설치 실패

원인: 바이너리 패키지 호환성 문제

해결:


# --no-binary 옵션 사용
uv pip install package-name --no-binary :all:
 
# 또는 pip 폴백
pip install problematic-package
uv pip install other-packages

문제 3: 의존성 충돌

원인: 서로 호환되지 않는 버전 요구사항

해결:


# 자세한 오류 메시지 확인
uv pip install package-name --verbose
 
# 의존성 트리 확인
uv pip tree
 
# 충돌하는 패키지 버전 조정
# requirements.in에서 버전 범위 수정
uv pip compile requirements.in --upgrade-package conflicting-package

문제 4: 캐시 관련 문제

원인: 손상된 캐시 데이터

해결:


# 캐시 위치 확인
uv cache dir
 
# 캐시 정리
uv cache clean
 
# 특정 패키지 캐시만 삭제
uv cache clean package-name

고급 기능

1. 플랫폼 간 잠금 파일


# 여러 플랫폼을 위한 범용 잠금 파일
uv pip compile requirements.in --universal
 
# 특정 플랫폼만
uv pip compile requirements.in --python-platform linux

2. 오프라인 설치


# 1. 패키지 다운로드 (온라인)
uv pip download -r requirements.txt -d ./packages
 
# 2. 오프라인 설치
uv pip install --no-index --find-links ./packages -r requirements.txt

3. 프라이빗 패키지 인덱스


# 환경 변수 설정
export UV_INDEX_URL="https://pypi.company.com/simple"
export UV_EXTRA_INDEX_URL="https://pypi.org/simple"
 
# 또는 명령어에 직접 지정
uv pip install package-name --index-url https://pypi.company.com/simple

4. 의존성 제약


# constraints.txt 사용
cat > constraints.txt << 'EOF'
numpy<2.0.0
pandas>=1.5.0,<2.0.0
EOF
 
# 제약 조건 적용
uv pip install -r requirements.txt -c constraints.txt

팀 협업 베스트 프랙티스

1. requirements.in과 requirements.txt 분리


project/
├── requirements.in          # 직접 명시한 의존성
├── requirements.txt         # 잠금 파일 (모든 의존성)
├── requirements-dev.in      # 개발 의존성
└── requirements-dev.txt     # 개발 의존성 잠금

2. 의존성 업데이트 워크플로우


# 주기적 업데이트 (월 1회)
uv pip compile requirements.in --upgrade -o requirements.txt
uv pip compile requirements-dev.in --upgrade -o requirements-dev.txt
 
# 변경사항 리뷰
git diff requirements.txt
 
# 테스트 후 커밋
pytest
git commit -am "deps: Update dependencies"

3. .gitignore 설정


# 가상 환경
.venv/
venv/
*.pyc
__pycache__/

# uv 캐시
.uv/

4. 문서화


# README.md
 
## 개발 환경 설정
 
1. uv 설치:
   ```bash
   curl -LsSf https://astral.sh/uv/install.sh | sh

가상 환경 생성 및 활성화:
```
uv venv
source .venv/bin/activate
```

의존성 설치:


uv pip sync requirements.txt
uv pip sync requirements-dev.txt  # 개발 환경



---

## 성능 최적화 팁

### 1. 전역 캐시 활용

```bash
# 캐시 통계 확인
uv cache dir
du -sh ~/.cache/uv  # macOS/Linux

# 여러 프로젝트에서 동일 패키지 재사용
# 자동으로 캐시 활용

2. 병렬 설치 최대화


# 기본적으로 병렬 다운로드 활성화
# 네트워크 대역폭 최대 활용
 
# 동시 다운로드 제한 (필요시)
export UV_CONCURRENT_DOWNLOADS=4
uv pip install -r requirements.txt

3. 의존성 사전 컴파일


# CI/CD에서 캐시 재사용
# GitHub Actions 예시
- name: Cache uv
  uses: actions/cache@v3
  with:
    path: ~/.cache/uv
    key: ${{ runner.os }}-uv-${{ hashFiles('requirements.txt') }}

다음 단계

추가 학습 자료

공식 문서: https://docs.astral.sh/uv/
GitHub: https://github.com/astral-sh/uv
릴리스 노트: https://github.com/astral-sh/uv/releases

실습 프로젝트

기존 프로젝트를 uv로 마이그레이션
CI/CD 파이프라인에 uv 통합
모노레포 환경에서 uv 활용

버전 정보

uv 버전: 0.4.x (2024년 기준)
Python 지원: 3.8 이상
플랫폼: macOS, Linux, Windows

요약

uv는 Rust로 작성된 초고속 Python 패키지 관리자로, pip 대비 10-100배 빠른 성능을 제공합니다. 기존 pip 워크플로우와 완벽하게 호환되면서도 더 나은 사용자 경험과 의존성 관리를 제공합니다.

핵심 장점:

⚡ 극도로 빠른 패키지 설치
🔒 정확한 의존성 잠금
💾 전역 캐시를 통한 디스크 절약
🔄 pip-tools와 호환되는 워크플로우
🚀 단일 바이너리로 간편한 배포

언제 사용하나요?

대규모 프로젝트의 빠른 환경 구성
CI/CD 파이프라인 최적화
팀 협업에서 일관된 환경 보장

uv를 도입하여 개발 생산성을 크게 향상시켜 보세요!

2025•developjik

All content is licensed under CC BY-NC-SA 4.0 unless otherwise noted.

개요

배경