Uv(파이썬) 편집하기 (부분)

== 핵심 기능 ==

uv는 단순한 패키지 설치 도구를 넘어, 파이썬 개발 환경 전체를 관리하는 올인원 도구다. 아래에 각 기능을 상세히 설명한다.

=== 패키지 설치 (pip 인터페이스) ===

기존 pip 명령어에 `uv` 접두사를 붙이는 것만으로 사용 가능하다. 기존 워크플로우를 거의 바꾸지 않아도 된다.

<syntaxhighlight lang="bash">
# 패키지 설치
uv pip install requests

# requirements.txt로 설치
uv pip install -r requirements.txt

# 개발 의존성 포함 설치
uv pip install -e ".[dev]"

# 특정 인덱스에서 설치 (예: PyTorch CUDA)
uv pip install torch --index-url https://download.pytorch.org/whl/cu121

# 패키지 목록 확인
uv pip list

# 패키지 제거
uv pip uninstall requests

# 설치된 패키지를 requirements.txt 형식으로 출력
uv pip freeze > requirements.txt
</syntaxhighlight>

==== pip compile (pip-tools 대체) ====

<syntaxhighlight lang="bash">
# requirements.in → requirements.txt (버전 고정)
uv pip compile requirements.in -o requirements.txt

# 플랫폼 독립적 해결 (크로스 플랫폼 lockfile)
uv pip compile requirements.in --universal -o requirements.txt

# 특정 파이썬 버전 타겟
uv pip compile requirements.in --python-version 3.11 -o requirements.txt

# requirements.txt 동기화 (불필요한 패키지 자동 제거)
uv pip sync requirements.txt
</syntaxhighlight>

=== 가상환경 관리 ===

pip이 20~40초 걸리던 가상환경 생성을 uv는 '''약 0.5초''' 만에 처리한다.

<syntaxhighlight lang="bash">
# 기본 가상환경 생성
uv venv

# 특정 파이썬 버전으로 가상환경 생성
uv venv --python 3.12

# 특정 경로에 가상환경 생성
uv venv myenv

# 가상환경 활성화 (기존 방식과 동일)
source .venv/bin/activate        # Linux/macOS
.venv\Scripts\activate           # Windows
</syntaxhighlight>

[* uv run 명령어를 사용하면 수동으로 가상환경을 활성화할 필요조차 없다. uv가 알아서 관리해준다.]

=== 프로젝트 관리 (Poetry 대체) ===

Poetry와 유사한 방식으로 프로젝트 전체의 생명주기를 관리한다.

==== 프로젝트 초기화 ====

<syntaxhighlight lang="bash">
# 새 프로젝트 생성
uv init my-project
cd my-project

# 생성되는 파일 구조:
# my-project/
# ├── .git/
# ├── .venv/
# ├── .python-version
# ├── pyproject.toml
# ├── README.md
# └── src/
#     └── my_project/
#         └── __init__.py
</syntaxhighlight>

==== 의존성 추가/제거 ====

<syntaxhighlight lang="bash">
# 패키지 추가 (pyproject.toml에 자동 기록 + 설치)
uv add requests
uv add "fastapi>=0.100"
uv add "numpy>=1.24,<2.0"

# 개발 의존성 추가
uv add --dev pytest ruff mypy

# 특정 그룹에 추가
uv add --group lint ruff

# 패키지 제거
uv remove requests

# 의존성 업그레이드
uv add requests --upgrade
</syntaxhighlight>

==== Lock 파일 관리 ====

<syntaxhighlight lang="bash">
# uv.lock 생성/업데이트
uv lock

# lock 파일 기반으로 환경 동기화
uv sync

# 개발 의존성 포함 동기화
uv sync --all-extras

# 특정 그룹만 동기화
uv sync --group lint
</syntaxhighlight>

==== 프로젝트 실행 ====

<syntaxhighlight lang="bash">
# 가상환경 활성화 없이 바로 실행 (uv가 자동으로 처리)
uv run python main.py
uv run python -m pytest
uv run ruff check .

# 환경변수와 함께 실행
uv run --env-file .env python main.py
</syntaxhighlight>

`uv run`의 가장 큰 장점은 '''가상환경을 수동으로 활성화하지 않아도 된다'''는 점이다. uv가 알아서 `.venv`를 찾고 올바른 환경에서 실행시켜 준다.

=== 파이썬 버전 관리 (pyenv 대체) ===

별도의 pyenv 없이 uv 하나로 여러 파이썬 버전을 관리할 수 있다.

<syntaxhighlight lang="bash">
# 파이썬 설치
uv python install 3.12
uv python install 3.11 3.12 3.13   # 여러 버전 동시 설치

# 설치된 파이썬 목록 확인
uv python list

# 사용 가능한 파이썬 버전 조회
uv python list --all-versions

# 특정 프로젝트에 파이썬 버전 고정
uv python pin 3.12   # .python-version 파일 생성

# PyPy 설치 및 사용
uv python install pypy@3.10
uv run --python pypy@3.10 python --version
</syntaxhighlight>

pyenv와의 차이점은, pyenv는 시스템 전역의 파이썬 버전을 바꾸는 방식이지만, uv는 '''프로젝트별로''' 파이썬 버전을 관리한다는 점이다. 프로젝트마다 다른 버전을 쓰는 게 훨씬 자연스럽다.

=== 도구 관리 (pipx 대체) ===

==== uvx - 일회성 도구 실행 ====

설치 없이 파이썬 패키지가 제공하는 CLI 도구를 즉시 실행할 수 있다. npm의 `npx`와 유사한 개념이다.

<syntaxhighlight lang="bash">
# 임시 환경에서 바로 실행 (설치 불필요)
uvx ruff check .
uvx black .
uvx httpie https://httpbin.org/get
uvx cowsay "Hello, uv!"

# 특정 버전으로 실행
uvx ruff@0.3.0 check .

# uv tool run도 같은 명령
uv tool run ruff check .
</syntaxhighlight>

==== 도구 영구 설치 ====

<syntaxhighlight lang="bash">
# 도구를 시스템에 영구 설치 (격리 환경에서)
uv tool install ruff
uv tool install black
uv tool install httpie

# 설치된 도구 목록
uv tool list

# 도구 업그레이드
uv tool upgrade ruff

# 도구 제거
uv tool uninstall ruff
</syntaxhighlight>

=== 단일 파일 스크립트 실행 ===

이것이 uv의 매우 독특하고 혁신적인 기능 중 하나다. [[PEP 723]]에 기반한 '''인라인 의존성 메타데이터'''를 스크립트 파일 안에 직접 선언할 수 있다.

<syntaxhighlight lang="python">
# example.py
# /// script
# requires-python = ">=3.12"
# dependencies = [
#   "requests",
#   "beautifulsoup4",
# ]
# ///

import requests
from bs4 import BeautifulSoup

resp = requests.get("https://example.com")
soup = BeautifulSoup(resp.text, "html.parser")
print(soup.title.string)
</syntaxhighlight>

<syntaxhighlight lang="bash">
# 별도의 venv나 pip install 없이 그냥 실행
uv run example.py

# 출력 예시:
# Reading inline script metadata from: example.py
# Installed 5 packages in 12ms
# Example Domain
</syntaxhighlight>

이 기능의 의의는 엄청나다. 파이썬 스크립트 하나를 공유할 때 requirements.txt나 별도의 설치 안내 없이 '''파일 하나만으로 완전한 재현성'''을 확보할 수 있다. uv만 설치되어 있으면 누구든 즉시 실행 가능하다.

=== 빌드 및 배포 ===

<syntaxhighlight lang="bash">
# 패키지 빌드 (wheel, sdist 생성)
uv build

# PyPI에 배포
uv publish

# Test PyPI에 배포
uv publish --publish-url https://test.pypi.org/legacy/

# 토큰 인증
uv publish --token $PYPI_TOKEN
</syntaxhighlight>

=== 4.8. 워크스페이스 (모노레포 지원) ===

[[Cargo]]의 워크스페이스 개념을 차용한 기능으로, 여러 파이썬 패키지를 하나의 저장소에서 관리할 때 유용하다.

<syntaxhighlight lang="toml">
# 루트 pyproject.toml
[tool.uv.workspace]
members = [
    "packages/core",
    "packages/api",
    "packages/cli",
]
</syntaxhighlight>

<syntaxhighlight lang="bash">
# 워크스페이스 전체 sync
uv sync --all-packages

# 특정 패키지만 실행
uv run --package api python -m uvicorn app:app
</syntaxhighlight>