2026년 2월 1일·프로그래밍·

9장: uv - 차세대 Python 패키지 매니저

Rust로 작성된 차세대 Python 패키지 매니저 uv를 다룹니다. 설치, 프로젝트 관리, 가상 환경, Python 버전 관리, 스크립트 실행까지 실전 워크플로우를 안내합니다.

14분600자14개 섹션

python typescript performance devtools concurrency

python-trends9 / 13

1 2 3 4 5 6 7 8 9 10 11 12 13

이전8장: 실험적 JIT 컴파일러의 원리와 가능성 다음10장: Ruff와 ty - 차세대 린터, 포매터, 타입 체커

Python 패키지 관리의 파편화

Python 생태계의 오랜 과제 중 하나는 패키지 관리 도구의 파편화입니다. 하나의 프로젝트를 관리하기 위해 여러 도구를 조합해야 했습니다.

기존 도구의 파편화

text

Python 버전 관리:  pyenv
가상 환경 생성:    virtualenv / venv
패키지 설치:       pip
의존성 잠금:       pip-tools / pip-compile
프로젝트 관리:     poetry / pipenv / hatch / pdm
패키지 빌드:       setuptools / flit / hatch

각 도구는 자체적으로는 훌륭하지만, 도구 간의 상호작용이 매끄럽지 않고, 환경 설정이 복잡합니다. 특히 Python 자체의 버전 관리, 가상 환경 생성, 패키지 설치라는 세 단계가 각각 별도의 도구를 요구한다는 점이 초보자에게 큰 진입 장벽이었습니다.

uv란 무엇인가

uv는 Astral이 Rust로 개발한 통합 Python 패키지 매니저입니다. pip, pip-tools, virtualenv, pyenv의 기능을 하나의 바이너리에 통합했으며, 기존 도구 대비 10~100배 빠른 성능을 제공합니다.

uv가 대체하는 도구들

text

pyenv        -> uv python install/list
virtualenv   -> uv venv
pip          -> uv pip install
pip-tools    -> uv lock / uv sync
poetry/pdm   -> uv init / uv add / uv remove
npx          -> uv tool run (uvx)

설치

uv 설치

bash

# macOS / Linux
curl -LsSf https://astral.sh/uv/install.sh | sh
 
# Windows (PowerShell)
powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"
 
# Homebrew
brew install uv
 
# pip (권장하지 않음 - Python 의존성 발생)
pip install uv
 
# 버전 확인
uv --version

Python 버전 관리

uv는 pyenv를 대체하여 Python 자체의 버전을 관리합니다.

Python 버전 관리

bash

# 사용 가능한 Python 버전 목록
uv python list
 
# 특정 버전 설치
uv python install 3.12
uv python install 3.13
 
# free-threaded 빌드 설치
uv python install 3.13t
 
# 여러 버전 동시 설치
uv python install 3.11 3.12 3.13
 
# 설치된 버전 확인
uv python list --only-installed
 
# 특정 버전으로 실행
uv run --python 3.13 script.py

Info

uv는 python-build-standalone 프로젝트의 사전 빌드된 Python 바이너리를 사용합니다. 소스 컴파일 없이 빠르게 설치됩니다. 시스템에 설치된 Python과 별도로 관리되므로, 시스템 Python을 건드리지 않습니다.

프로젝트 관리

프로젝트 초기화

새 프로젝트 생성

bash

# 새 프로젝트 초기화
uv init my-project
cd my-project
 
# 생성되는 파일 구조
# my-project/
#   pyproject.toml    프로젝트 설정
#   .python-version   Python 버전 고정
#   hello.py          예제 파일
#   README.md         문서

생성된 pyproject.toml

toml

[project]
name = "my-project"
version = "0.1.0"
description = "Add your description here"
readme = "README.md"
requires-python = ">=3.12"
dependencies = []

의존성 관리

의존성 추가와 제거

bash

# 의존성 추가
uv add requests
uv add "fastapi>=0.100"
uv add sqlalchemy pydantic
 
# 개발 의존성 추가
uv add --dev pytest pytest-cov ruff mypy
 
# 선택적 의존성 그룹
uv add --group docs mkdocs mkdocs-material
 
# 의존성 제거
uv remove requests
 
# 현재 의존성 확인
uv tree

uv add를 실행하면 pyproject.toml이 업데이트되고, 잠금 파일(uv.lock)이 자동으로 생성/갱신됩니다. 가상 환경이 없으면 자동으로 생성합니다.

잠금과 동기화

의존성 잠금과 동기화

bash

# 잠금 파일 생성/갱신
uv lock
 
# 잠금 파일 기반으로 가상 환경 동기화
uv sync
 
# 개발 의존성 포함 동기화
uv sync --all-groups
 
# 특정 그룹만 동기화
uv sync --group docs
 
# 프로덕션 의존성만 (개발 의존성 제외)
uv sync --no-dev

가상 환경 관리

가상 환경

bash

# 가상 환경 생성 (uv init이나 uv add 시 자동 생성)
uv venv
 
# 특정 Python 버전으로 생성
uv venv --python 3.13
 
# 특정 경로에 생성
uv venv /path/to/venv
 
# 가상 환경 활성화 (기존 방식과 동일)
source .venv/bin/activate    # macOS/Linux
.venv\Scripts\activate       # Windows

Tip

uv run 명령어를 사용하면 가상 환경을 명시적으로 활성화하지 않아도 됩니다. uv run은 자동으로 프로젝트의 가상 환경을 감지하고, 해당 환경에서 명령을 실행합니다.

uv run: 실행 환경 자동 관리

uv run은 uv의 가장 편리한 기능 중 하나입니다. 가상 환경 활성화, 의존성 동기화, 실행을 한 번에 처리합니다.

uv run 사용법

bash

# Python 스크립트 실행
uv run python script.py
 
# 모듈 실행
uv run python -m pytest
uv run python -m mypy src/
 
# 설치된 도구 실행
uv run ruff check .
uv run ruff format .
 
# 특정 Python 버전으로 실행
uv run --python 3.12 python script.py
 
# 추가 의존성과 함께 실행 (임시)
uv run --with rich python -c "from rich import print; print('[bold]Hello[/bold]')"

uv tool: 글로벌 도구 관리

uv tool은 시스템 전체에서 사용하는 CLI 도구를 관리합니다. Node.js의 npx와 유사합니다.

글로벌 도구 관리

bash

# 도구 설치 (격리된 환경에 설치)
uv tool install ruff
uv tool install black
uv tool install httpie
 
# 도구 실행 (설치 없이 일회성 실행)
uvx ruff check .
uvx black --check .
uvx cowsay "Hello Python"
 
# 설치된 도구 목록
uv tool list
 
# 도구 업그레이드
uv tool upgrade ruff
uv tool upgrade --all
 
# 도구 제거
uv tool uninstall black

uvx는 uv tool run의 단축 명령입니다. 도구가 설치되어 있지 않으면 자동으로 다운로드하여 실행하고, 이미 설치되어 있으면 즉시 실행합니다.

pip 호환 인터페이스

기존 pip 사용자를 위해 uv는 pip 호환 인터페이스를 제공합니다.

pip 호환 명령어

bash

# pip install 대체
uv pip install requests
uv pip install -r requirements.txt
uv pip install -e .  # 개발 모드 설치
 
# pip freeze 대체
uv pip freeze
 
# pip list 대체
uv pip list
 
# pip uninstall 대체
uv pip uninstall requests
 
# pip compile 대체 (pip-tools)
uv pip compile requirements.in -o requirements.txt

이 인터페이스는 기존 프로젝트에서 uv로 전환할 때 유용합니다. 기존 requirements.txt 파일을 그대로 사용할 수 있습니다.

인라인 스크립트 의존성 (PEP 723)

Python 3.12에서 승인된 PEP 723은 스크립트 파일에 의존성을 인라인으로 선언하는 표준을 정의합니다. uv는 이 표준을 완전히 지원합니다.

인라인 의존성 선언

python

# /// script
# requires-python = ">=3.12"
# dependencies = [
#   "requests>=2.31",
#   "rich>=13.0",
# ]
# ///
 
import requests
from rich import print as rprint
 
response = requests.get("https://api.github.com")
rprint(response.json())

인라인 스크립트 실행

bash

# uv가 의존성을 자동으로 설치하고 실행
uv run script.py
 
# 스크립트에 의존성 메타데이터 추가
uv add --script script.py requests rich

이 기능은 단일 파일 스크립트를 공유할 때 특히 유용합니다. 별도의 requirements.txt나 pyproject.toml 없이, 스크립트 파일 하나만으로 의존성이 해결됩니다.

성능 비교

uv의 가장 큰 장점은 속도입니다.

성능 비교 (대략적)

text

패키지 설치 (캐시 미스):
  pip:   30.0s
  uv:     1.5s  (약 20배 빠름)
 
패키지 설치 (캐시 히트):
  pip:   12.0s
  uv:     0.3s  (약 40배 빠름)
 
의존성 해결:
  pip-compile: 15.0s
  uv lock:      0.5s  (약 30배 빠름)
 
가상 환경 생성:
  virtualenv:  2.0s
  uv venv:     0.1s  (약 20배 빠름)

이 성능 차이는 Rust로 작성된 의존성 해결기, 병렬 다운로드, 효율적인 캐시 시스템 덕분입니다.

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

requirements.txt에서 전환

requirements.txt 마이그레이션

bash

# 기존 프로젝트에서 uv 초기화
cd existing-project
uv init
 
# requirements.txt의 의존성 추가
# (수동으로 uv add를 하거나, 스크립트로 변환)
cat requirements.txt | while read line; do
    if [ -n "$line" ] && [ "$line" != "#"* ]; then
        uv add "$line"
    fi
done
 
# 또는 pip 호환 인터페이스 사용
uv pip install -r requirements.txt

Poetry에서 전환

Poetry 마이그레이션

bash

# Poetry 프로젝트에서 uv로 전환
# pyproject.toml의 [tool.poetry] 섹션을 [project]로 변환
# uv는 PEP 621 표준 메타데이터를 사용
 
# 의존성 재설치
uv lock
uv sync

CI/CD에서의 활용

GitHub Actions 예시

yaml

name: Test
on: [push, pull_request]
 
jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
 
      - name: Install uv
        uses: astral-sh/setup-uv@v4
 
      - name: Install dependencies
        run: uv sync --all-groups
 
      - name: Run tests
        run: uv run pytest
 
      - name: Run linting
        run: uv run ruff check .
 
      - name: Run type checking
        run: uv run mypy src/

Info

CI/CD에서 uv의 빠른 설치 속도는 빌드 시간을 크게 단축합니다. 캐시 설정을 추가하면 더욱 빠른 파이프라인을 구축할 수 있습니다. astral-sh/setup-uv 액션은 uv 캐시를 자동으로 관리합니다.

정리

uv는 Python 패키지 관리의 파편화를 해결하는 통합 도구입니다.

Python 버전 관리, 가상 환경, 패키지 설치, 의존성 잠금을 하나의 도구로 통합합니다
Rust로 작성되어 기존 도구 대비 10~100배 빠른 성능을 제공합니다
pip 호환 인터페이스로 기존 프로젝트에서 점진적 전환이 가능합니다
PEP 723 인라인 스크립트 의존성을 지원하여 단일 파일 스크립트 공유가 편리합니다
uv run으로 가상 환경 활성화 없이 명령을 실행할 수 있습니다

다음 장 미리보기

10장에서는 Astral 생태계의 나머지 도구인 Ruff(린터/포매터)와 ty(타입 체커)를 다룹니다. flake8, black, isort, mypy를 대체하는 이 도구들의 설정과 실전 활용법을 살펴봅니다.

이 글이 도움이 되셨나요?

10장: Ruff와 ty - 차세대 린터, 포매터, 타입 체커

Astral의 Ruff(린터/포매터)와 ty(타입 체커)를 다룹니다. 기존 도구 대체, 설정 방법, 규칙 커스터마이징, IDE 통합, 프로젝트 도입 전략을 안내합니다.

2026년 2월 3일·14분

프로그래밍

8장: 실험적 JIT 컴파일러의 원리와 가능성

Python 3.13에 도입된 실험적 JIT 컴파일러를 분석합니다. copy-and-patch 기법의 원리, Tier 2 최적화 파이프라인, 빌드와 활성화 방법, 성능 벤치마크를 다룹니다.

2026년 1월 30일·17분

프로그래밍

11장: typing 고급 기능 실전 활용

Python 3.12~3.13의 typing 모듈 고급 기능을 다룹니다. TypedDict, Protocol, override, dataclass_transform, TypeGuard, TypeIs 등 실전 타입 시스템을 안내합니다.

2026년 2월 5일·13분

2026년 2월 1일·프로그래밍·

9장: uv - 차세대 Python 패키지 매니저

14분600자14개 섹션

python typescript performance devtools concurrency

python-trends9 / 13

1 2 3 4 5 6 7 8 9 10 11 12 13

이전8장: 실험적 JIT 컴파일러의 원리와 가능성 다음10장: Ruff와 ty - 차세대 린터, 포매터, 타입 체커

Python 패키지 관리의 파편화

Python 생태계의 오랜 과제 중 하나는 패키지 관리 도구의 파편화입니다. 하나의 프로젝트를 관리하기 위해 여러 도구를 조합해야 했습니다.

기존 도구의 파편화

text

Python 버전 관리:  pyenv
가상 환경 생성:    virtualenv / venv
패키지 설치:       pip
의존성 잠금:       pip-tools / pip-compile
프로젝트 관리:     poetry / pipenv / hatch / pdm
패키지 빌드:       setuptools / flit / hatch

uv란 무엇인가

uv가 대체하는 도구들

text

pyenv        -> uv python install/list
virtualenv   -> uv venv
pip          -> uv pip install
pip-tools    -> uv lock / uv sync
poetry/pdm   -> uv init / uv add / uv remove
npx          -> uv tool run (uvx)

설치

uv 설치

bash

# macOS / Linux
curl -LsSf https://astral.sh/uv/install.sh | sh
 
# Windows (PowerShell)
powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"
 
# Homebrew
brew install uv
 
# pip (권장하지 않음 - Python 의존성 발생)
pip install uv
 
# 버전 확인
uv --version

Python 버전 관리

uv는 pyenv를 대체하여 Python 자체의 버전을 관리합니다.

Python 버전 관리

bash

# 사용 가능한 Python 버전 목록
uv python list
 
# 특정 버전 설치
uv python install 3.12
uv python install 3.13
 
# free-threaded 빌드 설치
uv python install 3.13t
 
# 여러 버전 동시 설치
uv python install 3.11 3.12 3.13
 
# 설치된 버전 확인
uv python list --only-installed
 
# 특정 버전으로 실행
uv run --python 3.13 script.py

Info

프로젝트 관리

프로젝트 초기화

새 프로젝트 생성

bash

# 새 프로젝트 초기화
uv init my-project
cd my-project
 
# 생성되는 파일 구조
# my-project/
#   pyproject.toml    프로젝트 설정
#   .python-version   Python 버전 고정
#   hello.py          예제 파일
#   README.md         문서

생성된 pyproject.toml

toml

[project]
name = "my-project"
version = "0.1.0"
description = "Add your description here"
readme = "README.md"
requires-python = ">=3.12"
dependencies = []

의존성 관리

의존성 추가와 제거

bash

# 의존성 추가
uv add requests
uv add "fastapi>=0.100"
uv add sqlalchemy pydantic
 
# 개발 의존성 추가
uv add --dev pytest pytest-cov ruff mypy
 
# 선택적 의존성 그룹
uv add --group docs mkdocs mkdocs-material
 
# 의존성 제거
uv remove requests
 
# 현재 의존성 확인
uv tree

uv add를 실행하면 pyproject.toml이 업데이트되고, 잠금 파일(uv.lock)이 자동으로 생성/갱신됩니다. 가상 환경이 없으면 자동으로 생성합니다.

잠금과 동기화

의존성 잠금과 동기화

bash

# 잠금 파일 생성/갱신
uv lock
 
# 잠금 파일 기반으로 가상 환경 동기화
uv sync
 
# 개발 의존성 포함 동기화
uv sync --all-groups
 
# 특정 그룹만 동기화
uv sync --group docs
 
# 프로덕션 의존성만 (개발 의존성 제외)
uv sync --no-dev

가상 환경 관리

가상 환경

bash

# 가상 환경 생성 (uv init이나 uv add 시 자동 생성)
uv venv
 
# 특정 Python 버전으로 생성
uv venv --python 3.13
 
# 특정 경로에 생성
uv venv /path/to/venv
 
# 가상 환경 활성화 (기존 방식과 동일)
source .venv/bin/activate    # macOS/Linux
.venv\Scripts\activate       # Windows

Tip

uv run: 실행 환경 자동 관리

uv run은 uv의 가장 편리한 기능 중 하나입니다. 가상 환경 활성화, 의존성 동기화, 실행을 한 번에 처리합니다.

uv run 사용법

bash

# Python 스크립트 실행
uv run python script.py
 
# 모듈 실행
uv run python -m pytest
uv run python -m mypy src/
 
# 설치된 도구 실행
uv run ruff check .
uv run ruff format .
 
# 특정 Python 버전으로 실행
uv run --python 3.12 python script.py
 
# 추가 의존성과 함께 실행 (임시)
uv run --with rich python -c "from rich import print; print('[bold]Hello[/bold]')"

uv tool: 글로벌 도구 관리

uv tool은 시스템 전체에서 사용하는 CLI 도구를 관리합니다. Node.js의 npx와 유사합니다.

글로벌 도구 관리

bash

# 도구 설치 (격리된 환경에 설치)
uv tool install ruff
uv tool install black
uv tool install httpie
 
# 도구 실행 (설치 없이 일회성 실행)
uvx ruff check .
uvx black --check .
uvx cowsay "Hello Python"
 
# 설치된 도구 목록
uv tool list
 
# 도구 업그레이드
uv tool upgrade ruff
uv tool upgrade --all
 
# 도구 제거
uv tool uninstall black

uvx는 uv tool run의 단축 명령입니다. 도구가 설치되어 있지 않으면 자동으로 다운로드하여 실행하고, 이미 설치되어 있으면 즉시 실행합니다.

pip 호환 인터페이스

기존 pip 사용자를 위해 uv는 pip 호환 인터페이스를 제공합니다.

pip 호환 명령어

bash

# pip install 대체
uv pip install requests
uv pip install -r requirements.txt
uv pip install -e .  # 개발 모드 설치
 
# pip freeze 대체
uv pip freeze
 
# pip list 대체
uv pip list
 
# pip uninstall 대체
uv pip uninstall requests
 
# pip compile 대체 (pip-tools)
uv pip compile requirements.in -o requirements.txt

이 인터페이스는 기존 프로젝트에서 uv로 전환할 때 유용합니다. 기존 requirements.txt 파일을 그대로 사용할 수 있습니다.

인라인 스크립트 의존성 (PEP 723)

Python 3.12에서 승인된 PEP 723은 스크립트 파일에 의존성을 인라인으로 선언하는 표준을 정의합니다. uv는 이 표준을 완전히 지원합니다.

인라인 의존성 선언

python

# /// script
# requires-python = ">=3.12"
# dependencies = [
#   "requests>=2.31",
#   "rich>=13.0",
# ]
# ///
 
import requests
from rich import print as rprint
 
response = requests.get("https://api.github.com")
rprint(response.json())

인라인 스크립트 실행

bash

# uv가 의존성을 자동으로 설치하고 실행
uv run script.py
 
# 스크립트에 의존성 메타데이터 추가
uv add --script script.py requests rich

이 기능은 단일 파일 스크립트를 공유할 때 특히 유용합니다. 별도의 requirements.txt나 pyproject.toml 없이, 스크립트 파일 하나만으로 의존성이 해결됩니다.

성능 비교

uv의 가장 큰 장점은 속도입니다.

성능 비교 (대략적)

text

패키지 설치 (캐시 미스):
  pip:   30.0s
  uv:     1.5s  (약 20배 빠름)
 
패키지 설치 (캐시 히트):
  pip:   12.0s
  uv:     0.3s  (약 40배 빠름)
 
의존성 해결:
  pip-compile: 15.0s
  uv lock:      0.5s  (약 30배 빠름)
 
가상 환경 생성:
  virtualenv:  2.0s
  uv venv:     0.1s  (약 20배 빠름)

이 성능 차이는 Rust로 작성된 의존성 해결기, 병렬 다운로드, 효율적인 캐시 시스템 덕분입니다.

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

requirements.txt에서 전환

requirements.txt 마이그레이션

bash

# 기존 프로젝트에서 uv 초기화
cd existing-project
uv init
 
# requirements.txt의 의존성 추가
# (수동으로 uv add를 하거나, 스크립트로 변환)
cat requirements.txt | while read line; do
    if [ -n "$line" ] && [ "$line" != "#"* ]; then
        uv add "$line"
    fi
done
 
# 또는 pip 호환 인터페이스 사용
uv pip install -r requirements.txt

Poetry에서 전환

Poetry 마이그레이션

bash

# Poetry 프로젝트에서 uv로 전환
# pyproject.toml의 [tool.poetry] 섹션을 [project]로 변환
# uv는 PEP 621 표준 메타데이터를 사용
 
# 의존성 재설치
uv lock
uv sync

CI/CD에서의 활용

GitHub Actions 예시

yaml

name: Test
on: [push, pull_request]
 
jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
 
      - name: Install uv
        uses: astral-sh/setup-uv@v4
 
      - name: Install dependencies
        run: uv sync --all-groups
 
      - name: Run tests
        run: uv run pytest
 
      - name: Run linting
        run: uv run ruff check .
 
      - name: Run type checking
        run: uv run mypy src/