pip와의 호환성

uv는 일반적인 pip 및 pip-tools 워크플로의 대체품(drop-in replacement)으로 설계되었습니다. 기존 사용자가 큰 워크플로 변경 없이 uv로 전환할 수 있도록 하는 것이 목표지만, uv는 pip의 완전한 복제품은 아닙니다.

주요 차이점

설정 파일 및 환경 변수

uv는 pip.conf나 PIP_INDEX_URL 같은 pip 전용 설정 파일이나 환경 변수를 읽지 않습니다. 대신 uv는 환경 변수(예: UV_INDEX_URL)와 uv.toml 또는 pyproject.toml의 [tool.uv.pip] 섹션을 통해 자체 설정을 지원합니다.

사전 릴리스(pre-release) 호환성

uv는 다음 경우에만 사전 릴리스를 허용합니다.

1. 직접 의존성에 사전 릴리스 지정자가 명시된 경우 (예: flask>=2.0.0rc1)
2. 패키지의 모든 게시 버전이 사전 릴리스인 경우

이는 전이적 의존성의 사전 릴리스 식별자를 더 허용적으로 처리하는 pip와 다릅니다.

여러 패키지 인덱스

여러 인덱스에 패키지가 존재할 경우, uv는 일치하는 항목이 있는 첫 번째 인덱스에서 검색을 중단하여 의존성 혼동 공격(dependency confusion attack)을 방지합니다. --index-strategy 옵션에 first-index, unsafe-first-match, unsafe-best-match 값을 사용해 이 동작을 설정할 수 있습니다.

PEP 517 빌드 격리

uv는 기본적으로 PEP 517 빌드 격리를 사용합니다. 이를 우회하려면 빌드 의존성을 사전 설치하고 --no-build-isolation을 사용하세요.

전이적 URL 의존성

uv는 비URL 의존성이 URL 의존성을 도입하지 않는다고 가정합니다. 도입하면 uv가 해석(resolution) 중에 이를 거부합니다. 해결책은 URL 의존성을 직접 의존성으로 제공하는 것입니다.

기본적으로 가상환경 사용

uv는 비활성화 상태여도 기본적으로 가상환경을 찾아 설치합니다. pip처럼 시스템 Python에 설치하려면 --system을 사용하세요.

해석 전략

pip와 uv 모두 동일한 해석 결과를 보장하지 않습니다. 두 도구 모두 지정자(specifier)를 준수하는 유효하고 결정론적인 해결책을 보장하지만, 서로 다른 전략으로 인해 다른 유효한 결과가 나올 수 있습니다.

pip check

uv pip check는 다음 진단 항목을 보고합니다.

• 누락되거나 파싱할 수 없는 METADATA 파일
• 호환되지 않는 Python 버전 요구사항
• 누락된 의존성
• 버전 비호환성
• 여러 버전의 패키지 설치

사용자 설치 체계

uv는 --user 플래그를 지원하지 않습니다. 가상환경 사용을 권장합니다.

바이너리 배포 강제 적용

--only-binary: uv는 직접 URL 의존성에 이를 강제 적용(제한적 예외 있음)하지만, pip는 적용하지 않습니다.

--no-binary: uv는 캐시된 바이너리를 재사용하고 그로부터 메타데이터를 읽지만, pip는 그렇지 않습니다.

바이트코드 컴파일

uv는 기본적으로 바이트코드 컴파일을 건너뜁니다. --compile-bytecode 또는 UV_COMPILE_BYTECODE=1로 활성화할 수 있습니다.

엄격성

uv는 pip보다 엄격하여 사양을 위반하는 패키지(예: HTML 인덱스의 잘못된 URL 조각)를 거부합니다.

커맨드라인 옵션

uv는 --trusted-host, --user, 일부 키링(keyring) 인증 기능 등 모든 pip 옵션을 지원하지 않습니다. subprocess 키링 제공자만 지원되며, 키링 인증은 기본적으로 활성화되어 있지 않습니다.

레거시 형식

uv는 .egg 배포를 지원하지 않지만 .egg-info 및 .egg-link 형식은 부분적으로 지원합니다(새로 생성하지 않고 기존 설치를 존중).

빌드 제약

빌드 의존성에 제약을 적용하려면 --constraint 대신 --build-constraint를 사용하세요.

pip compile 기본값

• 출력 파일은 -o 또는 --output-file로 명시적으로 지정해야 합니다.
• extras는 기본적으로 제거됩니다 (유지하려면 --no-strip-extras 사용).
• 인덱스 URL은 기본적으로 출력에 포함되지 않습니다 (포함하려면 --emit-index-url 사용).

Python 버전 지정자

uv는 Python 버전을 주(major), 부(minor), 패치(patch) 구성요소로 잘라내어 requires-python: >=3.13을 Python 3.13.0b1을 허용하는 것으로 처리합니다.

패키지 우선순위

uv와 pip는 서로 다른 해석 우선순위를 사용하므로 uv는 요구사항 순서에 더 민감합니다. 설치 명령어나 입력 파일의 패키지 순서가 결과에 영향을 줄 수 있습니다.

휠(wheel) 검증

uv는 기본적으로 파일명과 메타데이터가 일치하지 않는 휠을 거부합니다. 재정의하려면 UV_SKIP_WHEEL_FILENAME_CHECK=1을 설정하세요.

패키지 이름 정규화

uv는 모든 출력에서 패키지 이름을 PEP 503 호환 형식으로 정규화하지만, pip는 레지스트리 이름을 그대로 보존합니다 (예: uv는 docstring-parser, pip는 docstring_parser를 표시).

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

원문(영어): https://docs.astral.sh/uv/pip/compatibility/