Python uv 101

Python uv 가이드: 빠르고 강력한 패키지 관리 도구

1. Python uv란?

uv는 Astral에서 개발한 Python 패키지 및 프로젝트 관리 도구로, 기존 pip와 venv를 대체하거나 보완할 수 있도록 설계되었습니다. Rust로 작성되어 초고속 성능을 자랑하며, 통합적인 환경 관리와 의존성 해결 기능을 제공합니다. 주요 용도는 다음과 같습니다:

• Python 패키지 설치 및 관리
• 가상 환경 생성 및 동기화
• 의존성 잠금 및 프로젝트 관리
• 기존 워크플로우 개선

주요 기능

• 초고속 성능: pip보다 10~100배 빠른 설치 속도
• 통합 도구: 패키지 설치, 가상 환경 생성, 의존성 잠금을 단일 명령어로 처리
• 글로벌 캐시: 동일한 의존성을 재사용해 디스크 공간 절약
• 호환성: 기존 pip 및 venv와의 높은 호환성

uv는 기존 Python 도구의 복잡성을 줄이고, 현대적인 개발 환경에 최적화된 대안을 제공합니다.

venv와의 비교

기능	venv	uv
속도	상대적으로 느림	80배 이상 빠름 (캐시 활용 시)
의존성 관리	pip와 별도로 사용해야 함	통합된 의존성 잠금 및 동기화
가상 환경 생성	기본 기능만 제공	고급 옵션(특정 Python 버전 등)
캐시 활용	없음	글로벌 캐시로 효율성 극대화
설치 복잡성	간단 (Python 내장)	추가 설치 필요

uv는 속도와 편의성을 중시하는 개발자에게 적합하며, venv는 가볍고 기본적인 환경에 유리합니다.

2. 지원하는 기능

• 패키지 관리: pip 대체 가능
• 가상 환경: venv 및 virtualenv 대체
• Python 버전 관리: 여러 Python 버전 설치 및 사용
• 의존성 잠금: poetry나 pipenv와 유사한 기능
• 프로젝트 초기화: uv init으로 쉽게 시작

별도 도구 설치 없이 uv 하나로 모든 작업을 처리할 수 있습니다.

3. 기본적인 설치 및 사용 방법

설치 명령어

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

# Windows (PowerShell)
$ irm https://astral.sh/uv/install.ps1 | iex

# pip를 통한 설치
$ pip install uv

설치 후 버전 확인:

$ uv --version

기본 예시 (프로젝트 초기화 및 패키지 설치)

# 새 프로젝트 초기화
$ uv init my_project
$ cd my_project

# 가상 환경 생성
$ uv venv

# 패키지 설치
$ uv pip install requests

# 스크립트 실행
$ uv run my_script.py

참고: uv는 .venv 폴더를 기본으로 사용하며, 기존 venv와 동일한 구조를 유지합니다.

4. 주요 명령어 사용법

프로젝트 초기화

uv init my_project

• 새 프로젝트 디렉토리와 기본 설정 파일(pyproject.toml)을 생성합니다.

가상 환경 생성

uv venv

• 특정 Python 버전 지정:

  uv venv --python 3.11
  

패키지 설치 및 추가

uv pip install pandas

• requirements.txt 사용:

  uv pip install -r requirements.txt
  

• 프로젝트에 의존성 추가:

  uv add numpy
  

  • pyproject.toml에 의존성을 기록하고 설치합니다.

의존성 잠금 및 동기화

uv lock

• 의존성을 고정된 버전으로 잠급니다 (uv.lock 파일 생성).

  uv sync
  

• 잠긴 의존성을 현재 환경에 동기화합니다.

requirements.txt 관리 및 생성

• 기존 requirements.txt에서 설치:

  uv pip install -r requirements.txt
  

• requirements.txt 생성 (두 가지 방법):
  1. uv pip compile: pyproject.toml 기반으로 생성.

     uv pip compile pyproject.toml -o requirements.txt
     

  2. uv export: uv.lock 파일을 기반으로 requirements.txt 내보내기.

     uv export -o requirements.txt
     

선택 방법

명령어	설명
uv init	새 프로젝트 초기화
uv venv	가상 환경 생성
uv pip install <package>	패키지 설치
uv add <package>	의존성 추가 및 기록
uv lock	의존성 잠금 파일 생성
uv sync	환경 동기화
uv pip compile	requirements.txt 생성
uv export	uv.lock 기반 requirements.txt 내보내기
uv run <script>	스크립트 실행

예시

# 프로젝트 초기화
$ uv init my_project
$ cd my_project

# 가상 환경 및 패키지 설정
$ uv venv
$ uv add numpy pandas

# 의존성 잠금
$ uv lock

# requirements.txt 생성
$ uv export -o requirements.txt

# 실행
$ uv run my_script.py

5. venv와의 공조 및 하위 호환성 유지

기존 venv 환경 활용

uv는 .venv 폴더를 자동으로 인식합니다:

source .venv/bin/activate
uv pip install requests

하위 호환성

• pip 인터페이스: uv pip은 pip와 동일한 옵션을 지원.
• requirements.txt: 기존 파일을 그대로 사용 가능:

  uv pip install -r requirements.txt
  

• pyproject.toml: uv는 pip와 달리 프로젝트 메타데이터를 통합 관리.

점진적 전환

• 기존 venv로 만든 환경에서 uv로 패키지만 관리.
• 새로운 프로젝트는 uv init으로 시작, 기존 프로젝트는 유지.

---

6. 동적 의존성 관리: uv sync

의존성이 변경될 때 동기화:

uv sync

주요 메서드

명령어	설명
uv lock	의존성 잠금 파일 생성
uv sync	잠긴 의존성을 환경에 적용
uv add	의존성 추가 및 동기화

예시

# 의존성 추가
$ uv add matplotlib
$ uv lock
$ uv sync

7. 추가 옵션 및 설정

Python 버전 관리

uv python install 3.12
uv venv --python 3.12

글로벌 캐시 비활성화

uv pip install --no-cache requests

8. 기타 유용한 기능

스크립트별 의존성 관리

uv add --script my_script.py requests
uv run my_script.py

도구 실행 (pipx 대체)

uvx black .

의존성 충돌 해결

최신 알고리즘(PubGrub)을 사용해 충돌 최소화.

9. uv와 기존 도구 연결

uv는 기존 Python 도구와 통합 가능합니다. 예를 들어, pip로 설치된 패키지를 uv로 관리하거나, venv 환경에서 uv 명령어를 사용할 수 있습니다.

예시

# 기존 venv 환경에서 uv 사용
$ python -m venv .venv
$ source .venv/bin/activate
$ uv add numpy
$ uv lock
$ uv export -o requirements.txt

---

uv는 Python 개발의 생산성을 높이는 강력한 도구입니다. uv init과 uv add로 프로젝트를 쉽게 시작하고, uv export나 uv pip compile로 requirements.txt를 생성해 기존 워크플로우와 연결할 수 있습니다. 기존 venv와의 호환성을 유지하면서도 속도와 편의성을 제공하니, 다음 프로젝트에서 도입을 추천합니다!