⚡ uv

Core Hierarchy

📦 Project (pyproject.toml)
├── 🐍 Python Pin (.python-version)
├── 🛠️ Environment (.venv)
└── 🔒 Lockfile (uv.lock)

---

0. Concept

"패키지 설치(pip)와 가상환경(venv)을 하나로 합친 도구"

Rust로 작성된 초고속 파이썬 패키지 및 프로젝트 관리자입니다.
Existing tools (pip, pyenv, poetry)의 기능을 단일 바이너리로 통합하여 압도적인 속도를 제공합니다.

---

1. 파이썬 버전 관리 (Python Management)

# 📋 설치된 및 설치 가능한 파이썬 버전 확인
uv python list

# 📥 특정 파이썬 버전 설치
uv python install 3.11 3.12

# 📥 특정 파이썬 버전 제거
uv python uninstall 3.12

# 📌 현재 프로젝트 고정 버전 설정 (.python-version 생성)
uv python pin 3.11

---

2. 프로젝트 초기화 (Project Init)

# 🚀 새로운 프로젝트 생성
uv init [project_name] --python [python-version]

# 🚀 이미 프로젝트(폴더)를 생성하였을 경우
cd [project_name]
uv init --python [python-version]

uv init 생성 파일 명세:

파일명	설명
pyproject.toml	프로젝트 메타데이터 및 의존성 명세 (사용자의 의도)
.python-version	해당 프로젝트가 사용할 파이썬 버전 기록
.gitignore	파이썬/uv 프로젝트에 최적화된 git 제외 목록
hello.py	프로젝트 시작을 위한 간단한 샘플 코드

---

3. 의존성 관리: Lock vs Sync

구분	uv lock (계획 수립)	uv sync (실행 및 동기화)
역할	어떤 버전을 설치할지 계산하여 uv.lock 파일 저장	uv.lock대로 가상환경(.venv)에 실제 설치
특징	가상환경(.venv)에는 아무 변화 없음	lock 과정을 포함함 (알아서 계산 후 설치)
결론	배포 전 버전을 고정할 때 사용	평소 개발할 때 사용

---

4. 패키지 관리 (Add, Update & Remove)

# 📦 최신 버전 설치
uv add numpy

# 🎯 특정 버전 설치 (또는 해당 버전으로 변경)
uv add numpy==1.26.4

# ⬆️ 버전 조건 지정 (따옴표 권장)
uv add "numpy>=1.26"
uv add "pandas<2.0"

# 🛠️ 개발 전용 패키지 설치 (pytest, ruff 등)
uv add --dev ruff

# 🗑️ 패키지 삭제
uv remove pandas

---

5. 코드 실행 및 가상환경 (Run & Venv)

uv는 프로젝트의 의존성과 가상환경을 자동으로 동기화하므로, 사용자가 환경을 직접 관리하는 번거로움이 줄어듭니다.

Python 실행 방식

• Modern Way (uv run): 가상환경을 수동으로 활성화할 필요가 없습니다. 실행 전 pyproject.toml과 실제 환경을 대조하여 필요한 패키지를 자동으로 설치/업데이트한 후 격리된 환경에서 명령을 수행합니다.
• Standard Way (python): VS Code가 .venv 폴더를 인터프리터로 자동 인식하고 있는 경우 사용합니다. 별도의 체크 과정 없이 이미 구축된 환경에서 즉시 실행됩니다.

# 1. uv를 통한 자동 관리 및 실행 (권장)
uv run main.py

# 2. 이미 가상환경이 활성화된 환경(VS Code 등)에서 직접 실행
python main.py

Tip: 가상환경은 언제 생성되나요?
uv init은 설정 파일만 생성합니다. 실제 가상환경(.venv)은 uv add, uv sync, uv run 등의 명령어를 처음 실행할 때 uv가 자동으로 생성합니다.

수동 관리 (특수한 경우)
기존 방식처럼 가상환경을 직접 제어해야 하는 상황(쉘 스크립트 활용 등)에서만 사용합니다.

# 가상환경 수동 생성
uv venv

# 가상환경 수동 활성화
source .venv/bin/activate  # macOS/Linux
.venv\Scripts\activate     # Windows

---

6. 내보내기 및 호환성 (Export & Inspection)

패키지 목록 및 의존성 확인

기존 pip 명령어	uv 대응 명령어	용도
pip list	uv pip list	설치된 패키지 목록을 표 형태로 확인
pip freeze	uv pip freeze	requirements.txt 형식으로 출력
(없음)	uv tree	패키지 간의 의존성 계층 구조 시각화

의존성 내보내기

# 📤 requirements.txt 형식으로 내보내기
uv export --output-file requirements.txt

# 개발자용 의존성 포함 내보내기
uv export --dev --output-file requirements-dev.txt

# 📥 기존 requirements.txt로부터 설치
uv add -r requirements.txt

---

7. 💡 딥러닝 실무 Tips

CUDA 버전 호환 PyTorch 설치
--default-index : CUDA 전용 Wheel 저장소를 최우선으로 탐색합니다.
--index : PyTorch 외의 일반 패키지 설치를 위해 PyPI를 보조 저장소로 추가합니다.

# 예: CUDA 11.8 버전용 PyTorch 2.2.1 및 TorchVision 0.17.1 설치
uv add torch==2.2.1 torchvision==0.17.1 --default-index https://download.pytorch.org/whl/cu118 --index https://pypi.org/simple

🧪 실험 환경 복제 워크플로우 (Reproducibility)
동료나 서버로 프로젝트를 이동했을 때 동일한 환경을 1초 만에 구축합니다.

1. 소스 코드와 함께 pyproject.toml, uv.lock 파일 받기
2. 해당 폴더에서 동기화 실행

   uv sync

3. 즉시 학습 시작

   uv run train.py