Skip to content

인증

Git 인증

uv는 Git에서 패키지를 설치할 수 있도록 지원하며, 비공개 저장소와의 인증을 위해 다음과 같은 방식을 제공한다.

SSH 사용:

  • git+ssh://git@<hostname>/... (예: git+ssh://git@github.com/astral-sh/uv)
  • git+ssh://git@<host>/... (예: git+ssh://git@github.com-key-2/astral-sh/uv)

SSH 설정 방법에 대한 자세한 내용은 GitHub SSH 문서를 참고한다.

비밀번호 또는 토큰 사용:

  • git+https://<user>:<token>@<hostname>/... (예: git+https://git:github_pat_asdf@github.com/astral-sh/uv)
  • git+https://<token>@<hostname>/... (예: git+https://github_pat_asdf@github.com/astral-sh/uv)
  • git+https://<user>@<hostname>/... (예: git+https://git@github.com/astral-sh/uv)

GitHub 개인 액세스 토큰을 사용할 때, 사용자 이름은 임의로 지정할 수 있다. GitHub는 직접 비밀번호로 로그인하는 것을 지원하지 않지만, 다른 호스트에서는 가능할 수 있다. 자격 증명 없이 사용자 이름만 제공하면, 자격 증명을 입력하라는 메시지가 표시된다.

URL에 자격 증명이 없고 인증이 필요한 경우, Git credential helper를 통해 쿼리한다.

HTTP 인증

uv는 패키지 레지스트리를 쿼리할 때 HTTP를 통해 인증 정보를 지원한다.

인증은 다음 소스에서 우선순위에 따라 제공될 수 있다:

  • URL, 예: https://<사용자>:<비밀번호>@<호스트명>/...
  • .netrc 설정 파일
  • keyring 프로바이더 (옵트인 필요)

단일 네트워크 위치(스키마, 호스트, 포트)에 대한 인증 정보가 발견되면, 해당 커맨드 실행 동안 캐시되고 동일한 네트워크 위치에 대한 다른 쿼리에서 사용된다. 인증은 uv 실행 간에 캐시되지 않는다.

.netrc 인증은 기본적으로 활성화되며, NETRC 환경 변수가 정의되어 있으면 이를 존중하고, 정의되지 않은 경우 ~/.netrc로 대체된다.

keyring 기반 인증을 활성화하려면 uv에 --keyring-provider subprocess 커맨드라인 인자를 전달하거나 UV_KEYRING_PROVIDER=subprocess를 설정한다.

인증은 다음 컨텍스트에서 지정된 호스트에 사용될 수 있다:

  • index-url
  • extra-index-url
  • find-links
  • package @ https://...

pip와의 차이점에 대한 자세한 내용은 pip 호환성 가이드를 참고한다.

커스텀 CA 인증서

기본적으로 uv는 webpki-roots 크레이트에 포함된 인증서를 로드한다. webpki-roots는 Mozilla에서 제공하는 신뢰할 수 있는 루트 인증서 집합이다. 이를 uv에 포함하면 이식성과 성능이 향상된다(특히 macOS에서는 시스템 신뢰 저장소를 읽는 데 상당한 지연이 발생한다).

하지만 경우에 따라 플랫폼의 기본 인증서 저장소를 사용해야 할 때가 있다. 특히 회사 신뢰 루트(예: 필수 프록시용)가 시스템 인증서 저장소에 포함된 경우가 그렇다. uv가 시스템의 신뢰 저장소를 사용하도록 하려면 --native-tls 커맨드라인 플래그를 사용해 uv를 실행하거나 UV_NATIVE_TLS 환경 변수를 true로 설정한다.

인증서에 직접 접근해야 하는 경우(예: CI 환경), SSL_CERT_FILE 환경 변수를 인증서 번들의 경로로 설정해 시스템 신뢰 저장소 대신 해당 파일을 사용하도록 uv에 지시한다.

클라이언트 인증서 인증(mTLS)이 필요한 경우, SSL_CLIENT_CERT 환경 변수를 인증서와 개인 키가 포함된 PEM 형식 파일의 경로로 설정한다.

마지막으로, 자체 서명된 인증서를 신뢰하거나 인증서 검증을 비활성화하려는 설정을 사용한다면, allow-insecure-host 설정 옵션을 통해 특정 호스트에 대한 비보안 연결을 허용하도록 uv에 지시할 수 있다. 예를 들어, pyproject.toml에 다음을 추가하면 example.com에 대한 비보안 연결이 허용된다:

[tool.uv]
allow-insecure-host = ["example.com"]

allow-insecure-host는 호스트명(예: localhost) 또는 호스트명-포트 쌍(예: localhost:8080)을 받는다. 이 옵션은 HTTPS 연결에만 적용되며, HTTP 연결은 기본적으로 보안이 적용되지 않는다.

allow-insecure-host는 신뢰할 수 있는 환경에서만 주의해서 사용한다. 인증서 검증이 없기 때문에 보안 위험에 노출될 수 있다.

다른 패키지 인덱스와의 인증

인기 있는 다른 Python 패키지 인덱스와의 인증에 대한 자세한 내용은 다른 인덱스 통합 가이드를 참고한다.