Gaon12: 시작

2026-03-10T06:23:24Z

시작

새 문서

{{인용|'''"An extremely fast Python package and project manager, written in Rust."'''|uv 공식 슬로건}}

'''uv'''(유-브이)는 [[Rust]] 언어로 작성된 초고속 [[파이썬]](Python) 패키지 및 프로젝트 관리 도구이다. [[Astral]] 팀이 개발했으며, 기존의 [[pip]], [[virtualenv]], [[pip-tools]], [[pipx]], [[Poetry]], [[pyenv]], [[Rye]], [[twine]] 등 여러 도구들의 기능을 단 하나의 바이너리로 통합한 것이 특징이다. [[pip]]보다 '''10~100배''' 빠른 속도를 자랑하며, 2024년 2월에 처음 공개된 이래 파이썬 생태계에서 폭발적인 인기를 끌고 있다.

== 개요 ==

파이썬 개발자라면 누구나 한번쯤 겪어봤을 것이다. 새 프로젝트를 시작하면서 [[pip]]으로 패키지를 설치하는데 몇 분씩 걸리거나, 가상환경 만드는 데만 20~40초가 소요되거나, 의존성 충돌 때문에 밤새 씨름한 경험. uv는 이 모든 문제를 '''한 방에''' 해결하겠다는 야심찬 목표로 등장한 도구다.

[[Astral]]은 파이썬 생태계에서 이미 초고속 린터·포매터인 '''[[Ruff]]'''로 이름을 알린 팀이다.[* Ruff는 [[Flake8]]이나 [[Black]]보다 10~100배 빠른 속도로 유명하다.] 이 팀이 패키지 관리 분야에도 같은 철학을 적용해 만든 것이 바로 uv다.

uv의 핵심 철학은 간단하다:
* '''빠름''' — 기다리는 시간을 최소화해 개발 흐름을 끊지 않는다.
* '''통합''' — 여러 도구를 따로따로 관리하지 않아도 된다.
* '''호환성''' — 기존 pip 워크플로우를 그대로 유지하면서 마이그레이션한다.

== 역사 ==

=== 탄생 배경 ===

파이썬의 패키지 관리 생태계는 오랫동안 파편화 문제를 안고 있었다. 패키지를 설치할 때는 [[pip]], 가상환경을 만들 때는 [[venv]] 또는 [[virtualenv]], 의존성을 고정할 때는 [[pip-tools]], 파이썬 버전 관리는 [[pyenv]], CLI 도구 격리는 [[pipx]]... 이런 식으로 각각 다른 도구를 조합해야 했고, 이를 배우고 관리하는 비용이 만만찮았다.

또한 pip 자체의 속도 문제도 심각했다. pip은 [[파이썬]]으로 작성되어 있어 의존성 해결 자체에 파이썬 인터프리터가 필요하고, 패키지 메타데이터를 가져오기 위해 전체 wheel 파일을 다운로드하는 비효율도 존재했다.

=== 출시 및 성장 ===

{| class="wikitable"
|-
! 시기 !! 내용
|-
| 2024년 2월 || uv 최초 공개. pip/pip-tools의 드롭인 대체제로 출발
|-
| 2024년 중반 || 프로젝트 관리, Python 설치, 스크립트 실행 등 기능 대폭 확장
|-
| 2024년 하반기 || Poetry, Rye의 기능을 흡수하는 통합 도구로 발전. Rye 프로젝트 인수
|-
| 2025년 | | PyCharm 등 주요 IDE에서 공식 지원 시작. 프로덕션 환경에서의 채택 급증
|-
| 2026년 현재 || 파이썬 생태계의 사실상 표준 패키지 관리 도구로 자리매김 중
|}

=== Rye 인수 ===

흥미로운 에피소드로, [[Flask]]의 창시자인 [[Armin Ronacher]]가 개인 프로젝트로 만든 '''Rye'''라는 파이썬 패키지 관리 도구가 있었다. Astral 팀이 Ronacher와 협력해 Rye를 인수하고, uv를 "파이썬의 [[Cargo]]"로 발전시키기로 합의했다. Rye는 현재 uv 기반으로 마이그레이션되고 있다.

== 설치 방법 ==

=== 운영체제별 설치 ===

==== macOS / Linux ====

<syntaxhighlight lang="bash">
# 공식 설치 스크립트 사용 (권장)
curl -LsSf https://astral.sh/uv/install.sh | sh
</syntaxhighlight>

==== Windows (PowerShell) ====

<syntaxhighlight lang="powershell">
# PowerShell에서 실행
powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"
</syntaxhighlight>

==== pip으로 설치 ====

<syntaxhighlight lang="bash">
pip install uv
# 또는 pipx를 사용한 격리 설치 (권장)
pipx install uv
</syntaxhighlight>

==== Homebrew (macOS) ====

<syntaxhighlight lang="bash">
brew install uv
</syntaxhighlight>

==== 설치 확인 ====

<syntaxhighlight lang="bash">
uv --version
# 예시 출력: uv 0.x.x (...)
</syntaxhighlight>

=== 셸 자동완성 설정 ===

<syntaxhighlight lang="bash">
# bash
echo 'eval "$(uv generate-shell-completion bash)"' >> ~/.bashrc

# zsh
echo 'eval "$(uv generate-shell-completion zsh)"' >> ~/.zshrc

# fish
echo 'uv generate-shell-completion fish | source' >> ~/.config/fish/config.fish
</syntaxhighlight>

=== 자체 업데이트 ===

공식 설치 스크립트로 설치한 경우 uv 스스로 업데이트가 가능하다.

<syntaxhighlight lang="bash">
uv self update
</syntaxhighlight>

== 핵심 기능 ==

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>

== 속도의 비밀 ==

uv가 pip보다 10~100배 빠른 이유는 단순히 Rust로 만들어졌기 때문만이 아니다. 여러 영리한 엔지니어링 결정들이 복합적으로 작용한 결과다.

=== Rust 기반의 구현 ===

pip은 [[파이썬]]으로 작성되어 있다. 파이썬은 고수준 언어로 편리하지만, 파일 I/O나 복잡한 연산에서 오버헤드가 크다. 특히 파이썬의 '''GIL(Global Interpreter Lock)''' 때문에 진정한 멀티스레드 병렬 처리가 불가능하다.

반면 uv는 [[Rust]]로 작성되어 있다. Rust는:
* GIL 없이 네이티브 멀티스레드 지원
* 가비지 컬렉터 없는 메모리 관리로 런타임 오버헤드 최소화
* 단일 정적 바이너리 배포 → 인터프리터 시작 비용 없음
* `rkyv` 라이브러리를 이용한 제로카피 역직렬화

=== PubGrub 의존성 해결 알고리즘 ===

pip의 기존 의존성 해결 알고리즘은 버전을 하나씩 시도하고 실패하면 되돌아가는 단순한 백트래킹 방식이었다. 복잡한 의존성 트리에서 수분이 걸리기도 했다.

uv는 '''PubGrub''' 알고리즘을 사용한다. PubGrub은 원래 Dart의 pub 패키지 매니저에서 개발된 알고리즘으로, SAT 솔버의 '''CDCL(Conflict-Driven Clause Learning)''' 기법을 적용했다.

작동 방식을 쉽게 설명하면:
# 의존성 요구사항들을 논리 제약 조건으로 모델링한다
# 충돌이 발생하면 단순히 되돌아가는 게 아니라 '''왜 충돌이 발생했는지 학습'''한다
# 이 학습된 정보를 바탕으로 비슷한 실패 조합을 수백만 가지씩 한번에 건너뛴다

덕분에 복잡한 의존성 그래프에서도 매우 빠르게 해결책을 찾고, 실패 시에도 '''명확한 에러 메시지'''를 제공한다.

> 예: `"Failed to resolve: package-a requires requests<=2.28 but package-b requires requests>=2.29"`

=== 글로벌 캐시 + 하드링크 ===

pip은 패키지를 설치할 때마다 각 가상환경의 `site-packages` 폴더에 파일을 '''복사'''한다. 10개의 프로젝트에서 numpy를 쓴다면 numpy 파일이 10벌 복사된다. 낭비다.

uv는 다르다:
# 패키지를 처음 다운로드하면 '''글로벌 캐시''' (`~/.cache/uv/wheels/`)에 저장한다
# 이후 설치할 때는 파일을 복사하는 대신 '''하드링크(hardlink)''' 또는 '''Copy-on-Write(CoW)'''를 사용해 가상환경이 캐시를 가리키도록 한다

도서관에 비유하면: pip은 책을 빌릴 때마다 복사본을 만드는 방식이고, uv는 도서관에 원본을 두고 위치 표지만 나눠주는 방식이다.

이 덕분에:
* '''워크캐시 상태에서 가상환경 생성이 밀리초 수준'''으로 빠르다
* 동일 패키지를 여러 프로젝트에서 써도 디스크 공간을 낭비하지 않는다

=== 병렬 다운로드 및 설치 ===

pip은 패키지를 순차적으로 다운로드하고 설치하는 경향이 있다. uv는 Rust의 멀티스레드를 활용해 패키지들을 '''동시에''' 다운로드하고 설치한다.

여러 개의 무거운 패키지 (예: torch + numpy + pandas)를 한번에 추가할 때 차이가 확연히 드러난다.

=== HTTP Range Request로 메타데이터만 가져오기 ===

pip은 패키지의 메타데이터를 얻기 위해 wheel 파일 전체를 다운로드하는 경우가 있다. PyTorch 같은 수 GB짜리 패키지도 마찬가지다.

uv는 HTTP의 `Range` 헤더를 사용해 wheel 파일의 앞부분 메타데이터(수 KB)만 선택적으로 다운로드한다. 나머지 99%는 필요할 때만 받는다.

=== Python 없이 동작 ===

pip은 모든 작업에 파이썬 인터프리터가 필요하고, 레거시 패키지의 메타데이터를 얻으려면 빌드 백엔드를 서브프로세스로 실행한다.

uv는 TOML과 wheel 메타데이터를 Rust 코드로 네이티브 파싱하며, `setup.py`만 가진 레거시 패키지를 만날 때만 파이썬을 사용한다.

=== 성능 벤치마크 ===

공식 벤치마크 기준 (Trio 패키지의 의존성 설치):

{| class="wikitable"
|-
! 상태 !! pip !! uv !! 속도 차이
|-
| 콜드 캐시 (최초 설치) || ~수십 초 || 수 초 || 8~10배 빠름
|-
| 워크 캐시 (재설치) || 수십 초 || 수백 ms || 80~115배 빠름
|-
| 가상환경 생성 || 20~40초 || ~0.5초 || 약 60배 빠름
|-
| 의존성 해결 (복잡한 그래프) || 수분 가능 || 수 ms~초 || 수십~수백배
|}

[* 벤치마크 결과는 환경, 네트워크 상태, 패키지 복잡도에 따라 다를 수 있다.]

== 기존 도구와의 비교 ==

=== uv vs pip ===

{| class="wikitable"
|-
! 항목 !! pip !! uv
|-
| 속도 || 느림 || 10~100배 빠름
|-
| 가상환경 관리 || 별도 venv/virtualenv 필요 || 통합
|-
| 의존성 잠금(lockfile) || 별도 pip-tools 필요 || 내장 (uv.lock)
|-
| 파이썬 버전 관리 || 별도 pyenv 필요 || 내장
|-
| 메모리 사용량 || 상대적으로 많음 || 적음
|-
| 에러 메시지 || 불명확한 경우 많음 || 명확한 충돌 원인 표시
|-
| 기존 호환성 || 기준 || requirements.txt, PyPI 완전 호환
|}

=== uv vs Poetry ===

{| class="wikitable"
|-
! 항목 !! Poetry !! uv
|-
| 속도 || 느림 || 압도적으로 빠름
|-
| 기능 완성도 || 성숙함 || 빠르게 따라잡는 중
|-
| 러닝커브 || 중간 || pip에 익숙하면 낮음
|-
| 프로젝트 관리 || 강력 || 강력 (점점 강화)
|-
| 패키지 배포 || 강력 (semantic versioning 등) || 지원
|-
| 표준 준수 (PEP 621 등) || 일부 독자 포맷 || 표준 우선
|-
| 추천 상황 || 장기 라이브러리 개발 || 대부분의 신규 프로젝트
|}

=== uv vs Conda ===

{| class="wikitable"
|-
! 항목 !! Conda !! uv
|-
| 파이썬 외 시스템 패키지 || 지원 || 미지원
|-
| 데이터 과학 생태계 || 강력 (Anaconda 채널) || PyPI 기반
|-
| 속도 || 느림 || 압도적으로 빠름
|-
| 용량 || 무거움 (Anaconda 수 GB) || 단일 바이너리 (~10MB)
|-
| GPU 드라이버 관리 || 지원 || 미지원 (pip 인터페이스로 우회 가능)
|-
| 크로스 플랫폼 || 강력 || 강력
|}

[* GPU/CUDA 환경에서는 `uv pip install torch --index-url https://download.pytorch.org/whl/cu121` 형태로 사용 가능하다.]

=== uv vs pipx ===

{| class="wikitable"
|-
! 항목 !! pipx !! uv (uvx)
|-
| CLI 도구 격리 실행 || 지원 || 지원 (uvx)
|-
| 속도 || 느림 || 빠름
|-
| 일회성 실행 || npx 스타일 미지원 || uvx로 지원
|-
| 통합 도구 여부 || 단독 도구 || uv의 일부 기능
|}

== pyproject.toml 구성 ==

uv 프로젝트의 핵심 설정 파일인 `pyproject.toml`의 구조를 설명한다.

=== 기본 구조 ===

<syntaxhighlight lang="toml">
[project]
name = "my-project"
version = "0.1.0"
description = "My awesome project"
readme = "README.md"
requires-python = ">=3.12"
license = { file = "LICENSE" }
authors = [
{ name = "Your Name", email = "you@example.com" }
]

# 기본 의존성
dependencies = [
"requests>=2.28",
"fastapi>=0.100",
"pydantic>=2.0",
]

[project.optional-dependencies]
dev = ["pytest", "ruff", "mypy"]
docs = ["mkdocs", "mkdocs-material"]

[project.scripts]
my-cli = "my_project.cli:main"

[build-system]
requires = ["hatchling"]
build-backend = "hatchling.build"
</syntaxhighlight>

=== uv 전용 설정 ===

<syntaxhighlight lang="toml">
[tool.uv]
# 개발 의존성 (표준 optional-dependencies와 별개)
dev-dependencies = [
"pytest>=8.0",
"pytest-cov",
"ruff",
"mypy",
]

# 인덱스 소스 커스텀
[[tool.uv.index]]
name = "pytorch-cpu"
url = "https://download.pytorch.org/whl/cpu"
explicit = true

# 패키지별 소스 오버라이드 (개발 중인 로컬 패키지 등)
[tool.uv.sources]
my-lib = { path = "../my-lib", editable = true }
other-lib = { git = "https://github.com/user/other-lib", branch = "main" }
</syntaxhighlight>

=== 의존성 그룹 ===

<syntaxhighlight lang="toml">
[dependency-groups]
lint = ["ruff>=0.3"]
test = ["pytest>=8.0", "pytest-cov"]
docs = ["mkdocs-material"]
</syntaxhighlight>

<syntaxhighlight lang="bash">
# 특정 그룹만 설치
uv sync --group test

# lint 그룹 실행
uv run --group lint ruff check .
</syntaxhighlight>

== CI/CD 활용 ==

uv는 CI/CD 파이프라인에서 특히 빛난다. GitHub Actions, GitLab CI 등에서 설치 시간을 50~80% 단축시킬 수 있다.

=== GitHub Actions ===

<syntaxhighlight lang="yaml">
name: CI

on: [push, pull_request]

jobs:
test:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4

# uv 설치 (공식 액션)
- name: Install uv
uses: astral-sh/setup-uv@v4
with:
version: "latest"
enable-cache: true # GitHub 캐시 활성화

# 파이썬 설치
- name: Set up Python
run: uv python install 3.12

# 의존성 설치 (lock 파일 기반)
- name: Install dependencies
run: uv sync --frozen --all-extras

# 테스트 실행
- name: Run tests
run: uv run pytest

# 린트 검사
- name: Lint
run: uv run ruff check .
</syntaxhighlight>

=== Docker ===

<syntaxhighlight lang="dockerfile">
# Dockerfile
FROM python:3.12-slim

# uv 설치
COPY --from=ghcr.io/astral-sh/uv:latest /uv /uvx /bin/

WORKDIR /app

# 의존성 먼저 복사 (캐시 레이어 최적화)
COPY pyproject.toml uv.lock ./

# 의존성 설치 (가상환경 없이 시스템에 직접)
RUN uv sync --frozen --no-dev --system

# 소스 코드 복사
COPY . .

CMD ["uv", "run", "--system", "python", "-m", "myapp"]
</syntaxhighlight>

== 실전 사용 예시 ==

=== 데이터 과학 프로젝트 시작 ===

<syntaxhighlight lang="bash">
# 프로젝트 초기화
uv init data-analysis
cd data-analysis

# 파이썬 버전 고정
uv python pin 3.12

# 무거운 패키지들도 빠르게 설치
uv add numpy pandas matplotlib scikit-learn jupyter

# GPU 버전 PyTorch 추가
uv add torch --index-url https://download.pytorch.org/whl/cu121

# 개발 도구 추가
uv add --dev pytest ruff mypy

# Jupyter 실행
uv run jupyter lab
</syntaxhighlight>

=== 웹 API 개발 ===

<syntaxhighlight lang="bash">
uv init my-api
cd my-api

uv add fastapi "uvicorn[standard]" sqlalchemy pydantic-settings
uv add --dev pytest httpx pytest-asyncio

uv run uvicorn app.main:app --reload
</syntaxhighlight>

=== 간단한 일회성 스크립트 ===

<syntaxhighlight lang="python">
# web_scraper.py
# /// script
# requires-python = ">=3.11"
# dependencies = [
# "httpx",
# "beautifulsoup4",
# "rich",
# ]
# ///

import httpx
from bs4 import BeautifulSoup
from rich import print

resp = httpx.get("https://news.ycombinator.com")
soup = BeautifulSoup(resp.text, "html.parser")
titles = [a.text for a in soup.select(".titleline > a")[:10]]

for i, title in enumerate(titles, 1):
print(f"[cyan]{i}.[/cyan] {title}")
</syntaxhighlight>

<syntaxhighlight lang="bash">
# 위 스크립트를 공유받은 사람은 그냥 이렇게만 실행하면 끝
uv run web_scraper.py
</syntaxhighlight>

=== 기존 pip 프로젝트 마이그레이션 ===

<syntaxhighlight lang="bash">
# 기존 requirements.txt 기반 프로젝트
cd existing-project

# 방법 1: pip 인터페이스로 그대로 사용 (가장 쉬움)
uv pip install -r requirements.txt
uv pip sync requirements.txt

# 방법 2: 완전한 uv 프로젝트로 전환
uv init . # pyproject.toml 생성
uv add $(cat requirements.txt | grep -v "^#" | tr '\n' ' ')
uv lock # uv.lock 생성
</syntaxhighlight>

== 주요 명령어 요약 ==

=== 자주 쓰는 명령어 치트시트 ===

{| class="wikitable"
|-
! 작업 !! 명령어
|-
| 프로젝트 초기화 || `uv init <이름>`
|-
| 패키지 추가 || `uv add <패키지>`
|-
| 개발 의존성 추가 || `uv add --dev <패키지>`
|-
| 패키지 제거 || `uv remove <패키지>`
|-
| 의존성 동기화 || `uv sync`
|-
| Lock 파일 업데이트 || `uv lock`
|-
| 스크립트 실행 || `uv run <명령어>`
|-
| 파이썬 설치 || `uv python install <버전>`
|-
| 가상환경 생성 || `uv venv`
|-
| 도구 즉시 실행 || `uvx <도구명>`
|-
| 도구 영구 설치 || `uv tool install <도구명>`
|-
| pip 설치 || `uv pip install <패키지>`
|-
| requirements.txt 컴파일 || `uv pip compile requirements.in -o requirements.txt`
|-
| requirements.txt 동기화 || `uv pip sync requirements.txt`
|-
| 패키지 빌드 || `uv build`
|-
| PyPI 배포 || `uv publish`
|-
| 도움말 || `uv help` 또는 `uv <명령어> --help`
|}

== 주의사항 및 한계 ==

uv가 만능은 아니다. 아래와 같은 상황에서는 주의가 필요하다.

=== pip과의 차이점 ===

* uv는 `.egg` 형식을 지원하지 않는다. 레거시 패키지 중 일부는 문제가 생길 수 있다.
* `requires-python`의 상한 버전 제약 (예: `python<4.0`)을 무시한다. 의도적인 설계이나 간혹 예상과 다른 동작을 할 수 있다.
* 여러 패키지 인덱스가 있을 때 pip은 모두 확인하지만, uv는 패키지가 있는 '''첫 번째 인덱스에서 바로 선택'''한다.

=== Conda와의 비교에서 ===

* C/C++ 라이브러리 등 파이썬 외 시스템 의존성은 관리하지 못한다. CUDA 드라이버 자체를 설치하거나, HDF5 같은 시스템 라이브러리가 필요한 경우 별도 관리가 필요하다.
* 바이오인포매틱스 등 Bioconda 채널 특화 패키지는 Conda 쪽이 더 편할 수 있다.

=== 성숙도 ===

* 2024년 출시로 역사가 짧다. pip(2008), Poetry(2018) 등에 비해 엣지 케이스 지원이 부족할 수 있다.
* 다만 Astral 팀이 매우 빠른 속도로 개발하고 있어 빠르게 개선되는 중이다.

== 생태계 통합 ==

=== IDE 지원 ===

* '''PyCharm''' — 2024.3.2 버전부터 uv 공식 지원. 가상환경 생성 및 관리 통합. 2025년 버전에서는 uv가 기본 환경 관리자로 설정되었다.
* '''VS Code''' — Python 확장에서 uv 가상환경 자동 인식
* '''Cursor, Windsurf''' 등 AI 에디터들도 uv 환경 지원

=== 프레임워크 통합 ===

* [[FastAPI]], [[Django]], [[Flask]] 등 주요 웹 프레임워크 문서에서 uv를 권장 패키지 관리자로 소개하기 시작했다.
* [[Hatch]], [[PDM]] 등 다른 모던 패키지 관리자들과도 호환 가능한 `pyproject.toml` 포맷을 공유한다.

=== Claude Code와의 통합 ===

[[Anthropic]]의 Claude Code는 파이썬 프로젝트 설정 시 uv를 기본으로 추천하고 사용한다. AI 코딩 어시스턴트와의 자연스러운 통합이 이루어지는 추세다.

== 여담 ==

* uv의 이름은 특별한 의미 없이 짧고 기억하기 쉬운 이름을 선택한 것으로 알려져 있다. 공식 스타일 가이드에서는 '''반드시 소문자로 "uv"라고 표기'''하도록 명시하고 있다.[* UV, Uv 등으로 쓰지 말 것을 권장한다.]

* [[Rust]]로 파이썬 도구를 만드는 트렌드가 눈에 띈다. [[Ruff]](린터), uv(패키지 관리자), [[Rye]](프로젝트 관리)가 모두 Rust로 만들어졌다. 파이썬 생태계의 인프라 도구를 파이썬이 아닌 Rust로 만드는 아이러니가 재미있다는 반응도 있다.

* uv의 의존성 해결 알고리즘인 PubGrub은 원래 [[Dart]] 언어의 패키지 관리자 `pub`을 위해 설계되었고, 이후 [[Rust]] 크레이트(`pubgrub-rs`)로 포팅되었다. uv는 이 Rust 구현체를 활용한다.

* uv는 [[Cargo]](Rust), [[pnpm]](Node.js), [[Bun]](JavaScript), [[Orogene]](Node.js) 등 다른 언어 생태계의 패키지 관리자들에서 영감을 많이 받았다고 공식적으로 밝히고 있다.

* 일부 개발자들은 uv를 처음 사용하고 속도에 충격을 받아 "이게 진짜야?"라는 반응을 보이곤 한다. pip으로 수분이 걸리던 작업이 수초 만에 끝나는 경험이 매우 낯설게 느껴지기 때문이다.

* 가상환경 생성이 0.5초 수준이 되면서 "가상환경은 무겁다"는 기존 인식이 바뀌고 있다. 이제는 브랜치마다 별도 가상환경을 만드는 워크플로우도 현실적으로 가능해졌다.

== 관련 항목 ==

* [[pip]] — uv가 대체하는 기존 파이썬 패키지 관리자
* [[virtualenv]] / [[venv]] — uv가 통합한 가상환경 도구
* [[Poetry]] — uv와 경쟁하는 파이썬 프로젝트 관리 도구
* [[pyenv]] — uv가 대체 가능한 파이썬 버전 관리 도구
* [[pipx]] — uv(uvx)가 대체 가능한 CLI 도구 격리 실행 도구
* [[Ruff]] — 같은 Astral 팀이 만든 초고속 파이썬 린터/포매터
* [[Cargo]] — uv가 목표로 삼는 Rust의 패키지 관리자
* [[Rust (프로그래밍 언어)]] — uv의 구현 언어
* [[Astral]] — uv 개발사

== 외부 링크 ==

* [https://docs.astral.sh/uv/ uv 공식 문서]
* [https://github.com/astral-sh/uv uv GitHub 저장소]
* [https://astral.sh/blog/uv uv 최초 발표 블로그 포스트]
* [https://astral.sh/blog/uv-unified-python-packaging uv 통합 패키지 관리 발표 블로그]
* [https://pypi.org/project/uv/ uv PyPI 페이지]

[[분류:파이썬]]
[[분류:패키지 관리자]]
[[분류:개발 도구]]
[[분류:Rust로 작성된 소프트웨어]]
[[분류:오픈 소스 소프트웨어]]

Uv(파이썬) - 편집 역사

Gaon12: 시작