pip에서 uv 프로젝트로 마이그레이션

pip 워크플로우 이해하기

프로젝트 의존성

기존 pip은 명령형 설치 명령으로 환경에 패키지(package)를 추가합니다:

$ pip install fastapi

의존성(dependency) 충돌을 방지하기 위해 프로젝트마다 격리된 가상환경(virtual environment)을 만드는 것이 모범 사례입니다.

요구 사항 파일

프로젝트를 공유하기 위해 pip은 파일에 의존성을 선언하는 방식을 지원합니다. pip-tools 워크플로우는 목적에 따라 별도의 파일을 사용합니다:

• requirements.in: 선택적 버전 제약이 있는 직접 의존성을 지정
• requirements.txt: 모든 의존성(직접 및 전이적)의 잠긴 버전을 포함

requirements.in 예시:

fastapi
pydantic>2

이것은 정확한 버전이 있는 requirements.txt로 컴파일됩니다:

fastapi==0.115.11
pydantic==2.10.6
pydantic-core==2.27.2

개발 의존성

개발 전용 패키지는 별도 파일로 관리합니다:

# requirements-dev.in
-r requirements.in
-c requirements.txt

pytest

-r 플래그는 기본 요구 사항을 포함하고, -c는 기본 락파일(lockfile)과 일치하도록 버전을 제약합니다.

플랫폼별 의존성

pip-compile은 플랫폼별 출력을 생성하므로, 각 지원 OS마다 별도의 락파일이 필요합니다. 예를 들어, Windows에서 tqdm은 colorama를 의존성으로 포함하지만 Linux에서는 그렇지 않습니다.

uv 프로젝트로 마이그레이션

pyproject.toml

requirements.in 파일을 표준화된 pyproject.toml로 교체합니다:

[project]
name = "example"
version = "0.0.1"
dependencies = [
    "fastapi",
    "pydantic>2"
]

[dependency-groups]
dev = ["pytest"]

이를 통해 프로젝트 메타데이터(metadata)를 중앙화하고 임의의 의존성 그룹을 지원합니다.

uv 락파일

uv.lock 파일은 requirements.txt 파일을 uv의 고급 형식으로 대체합니다. 지원 사항:

• 단일 파일로 모든 플랫폼에 걸친 범용 해결(universal resolution)
• 여러 락파일 없이 의존성 그룹 지원
• 자동으로 추가되는 플랫폼별 마커

uv lock으로 명시적으로 생성하거나, 의존성을 수정할 때 자동으로 생성됩니다.

요구 사항 파일 가져오기

기본 가져오기:

$ uv init
$ uv add -r requirements.in

기존 버전 유지:

$ uv add -r requirements.in -c requirements.txt

제약(-c)을 사용하면 이전에 잠긴 의존성 버전을 유지할 수 있습니다.

플랫폼별 제약 가져오기

여러 플랫폼에 별도의 락파일이 있는 프로젝트의 경우, 먼저 환경 마커를 추가합니다:

$ uv pip compile requirements.in -o requirements-win.txt \
  --python-platform windows --no-strip-markers

이렇게 하면 colorama==0.4.6 ; sys_platform == 'win32'처럼 적절한 마커가 포함된 출력이 생성됩니다.

그런 다음 모든 플랫폼 제약을 함께 가져옵니다:

$ uv add -r requirements.in -c requirements-win.txt -c requirements-linux.txt

개발 의존성 파일 가져오기

--dev 플래그를 사용하세요:

$ uv add --dev -r requirements-dev.in -c requirements-dev.txt

requirements-dev.in이 -r로 기본 요구 사항을 포함하는 경우, 이를 제거하세요:

$ sed '/^-r /d' requirements-dev.in | uv add --dev -r - -c requirements-dev.txt

특수 목적을 위한 추가 그룹을 만들 수 있습니다:

$ uv add -r requirements-docs.in -c requirements-docs.txt --group docs

의존성 소스 가져오기

로컬 경로와 Git 의존성은 [tool.uv.sources]로 변환됩니다:

[project]
dependencies = [
    "path-dep",
    "editable-path-dep",
    "git-dep",
]

[tool.uv.sources]
path-dep = { path = "./path-dep" }
editable-path-dep = { path = "./editable-path-dep", editable = true }
git-dep = { git = "https://github.com/astral-sh/git-dep" }

프로젝트 환경

pip과 달리 uv는 프로젝트마다 전용 .venv 디렉터리를 자동으로 관리합니다. uv run으로 명령을 실행합니다:

$ uv run pytest

이 명령은 실행 전에 자동으로 락파일과 환경을 동기화합니다. uv sync으로 환경을 명시적으로 생성할 수도 있습니다.

uv는 기본적으로 활성 VIRTUAL_ENV 환경보다 프로젝트의 .venv 디렉터리를 선호합니다(--active로 재정의 가능).

다음 단계

uv 프로젝트 관리에 대한 자세한 내용은 프로젝트 개념 문서를 살펴보세요.

원문(영어): https://docs.astral.sh/uv/guides/migration/pip-to-project/ · 본 문서는 학습용 한국어 번역이며 원본의 권리는 원저작자(Astral)에게 있습니다.

원문(영어): https://docs.astral.sh/uv/guides/migration/pip-to-project/