Python uv 고급 실무: Python 버전·pip 인터페이스·도구 설치

요구 사항이 "돌기만 하면 돼"에서 "멀티 버전 테스트·기존 파이프라인 호환성·전역 도구 관리"로 바뀌어도 uv가 처리합니다. 이 글은 솔로 던전에서 레이드로 업그레이드입니다.

Python 버전 관리

uv에는 Python 다운로드와 관리 기능이 내장 — pyenv를 별도로 설치할 필요 없습니다.

# 여러 버전 설치
uv python install 3.10 3.11 3.12
 
# 프로젝트 버전 고정 (.python-version 생성)
uv python pin 3.11
 
# 특정 버전으로 venv 생성
uv venv --python 3.12
 
# 특정 버전으로 실행
uv run --python 3.10 pytest

버전을 처음 사용할 때는 자동으로 다운로드 — 이후에는 캐시에서 바로 사용합니다.

pip 호환 인터페이스

기존 CI·Docker·스크립트가 아직 pip을 사용하고 있나요? uv가 드롭인 대체제를 제공합니다:

# pip install -r requirements.txt 와 동일
uv pip install -r requirements.txt
 
# requirements 컴파일 (크로스 플랫폼, 재현 가능)
uv pip compile requirements.in --universal -o requirements.txt
 
# 환경 동기화 (잠금 파일에 엄격하게 따름)
uv pip sync requirements.txt
 
# venv 생성
uv venv

uv pip으로 전환하면 파라미터는 거의 동일하지만 속도가 한 차수 높아집니다 — 자전거에서 오토바이로 업그레이드하는 것처럼: 같은 길, 완전히 다른 경험. 큰 변경 없이 레거시 프로젝트를 업그레이드하고 싶다면? 먼저 uv pip으로만 바꿔도 무통으로 성능 향상됩니다.

전역 도구 설치 (uv tool)

자주 쓰는 도구를 매번 uvx로 실행하고 싶지 않다면? 전역 설치:

uv tool install ruff
uv tool install httpie
 
# 이후 직접 호출 가능
ruff check .
http https://httpbin.org/get

개별 도구 또는 전체 업그레이드:

uv tool upgrade ruff
uv tool upgrade --all

uv tool install은 독립 환경을 만들어 프로젝트 의존성과 충돌하지 않습니다. 프로젝트 내 버전 고정이 필요한 도구는 계속 uv add --dev 사용.

스크립트 잠금 파일과 shebang

단일 스크립트도 재현 가능하게 하고 싶다면? 의존성을 잠글 수 있습니다:

uv lock --script example.py

example.py.lock이 생성됩니다. uv run example.py 실행 시 이 잠금 파일을 사용합니다.

또는 실행 파일로 만들기:

#!/usr/bin/env -S uv run --script
# /// script
# dependencies = ["httpx"]
# ///
 
import httpx
print(httpx.get("https://example.com"))

chmod +x fetch
./fetch

다음 단계

고급 기능을 갖췄다면 지침으로 위험을 줄이세요: 👉 베스트 프랙티스