Skip to content

패키지 빌드 및 배포

uv는 uv build 명령어를 통해 파이썬 패키지를 소스 및 바이너리 배포물로 빌드하고, uv publish 명령어를 사용해 레지스트리에 업로드하는 기능을 지원한다.

프로젝트 패키징 준비

프로젝트를 배포하기 전에 패키징할 준비가 되었는지 확인해야 한다.

pyproject.toml 파일에 [build-system] 정의가 포함되어 있지 않으면 uv는 기본적으로 프로젝트를 빌드하지 않는다. 이는 프로젝트가 배포할 준비가 되지 않았음을 의미한다. 빌드 시스템을 선언하는 효과에 대해 더 알고 싶다면 프로젝트 개념 문서를 참고한다.

참고

배포하고 싶지 않은 내부 패키지가 있다면 private로 표시할 수 있다:

[project]
classifiers = ["Private :: Do Not Upload"]

이 설정은 PyPI가 업로드된 패키지를 배포하지 못하도록 거부한다. 다른 레지스트리의 보안이나 개인정보 설정에는 영향을 미치지 않는다.

또한 프로젝트별 토큰만 생성하는 것을 권장한다: 프로젝트와 일치하는 PyPI 토큰이 없으면 실수로 배포되는 것을 방지할 수 있다.

패키지 빌드

uv build 명령어로 패키지를 빌드한다:

$ uv build

기본적으로 uv build는 현재 디렉토리의 프로젝트를 빌드하고, 빌드 결과물을 dist/ 하위 디렉토리에 저장한다.

또는 uv build <SRC>를 사용하면 지정한 디렉토리에서 패키지를 빌드할 수 있다. uv build --package <PACKAGE>는 현재 작업 공간 내에서 지정한 패키지를 빌드한다.

Info

기본적으로 uv build는 pyproject.toml의 build-system.requires 섹션에서 빌드 의존성을 확인할 때 tool.uv.sources를 고려한다. 패키지를 배포할 때는 tool.uv.sources가 비활성화된 상태에서도 올바르게 빌드되는지 확인하기 위해 uv build --no-sources를 실행하는 것을 권장한다. 이는 pypa/build와 같은 다른 빌드 도구를 사용할 때와 동일한 상황이다.

패키지 배포하기

uv publish 명령어를 사용해 패키지를 배포한다:

$ uv publish

--token 또는 UV_PUBLISH_TOKEN을 통해 PyPI 토큰을 설정하거나, --username 또는 UV_PUBLISH_USERNAME으로 사용자 이름을, --password 또는 UV_PUBLISH_PASSWORD로 비밀번호를 설정한다. GitHub Actions에서 PyPI로 배포할 경우, 별도의 인증 정보를 설정할 필요가 없다. 대신 PyPI 프로젝트에 신뢰할 수 있는 퍼블리셔를 추가하면 된다.

Note

PyPI는 더 이상 사용자 이름과 비밀번호를 통한 배포를 지원하지 않는다. 대신 토큰을 생성해야 한다. 토큰을 사용하는 것은 --username __token__을 설정하고 토큰을 비밀번호로 사용하는 것과 동일하다.

[[tool.uv.index]]를 통해 커스텀 인덱스를 사용하는 경우, publish-url을 추가하고 uv publish --index <name>을 사용한다. 예를 들어:

[[tool.uv.index]]
name = "testpypi"
url = "https://test.pypi.org/simple/"
publish-url = "https://test.pypi.org/legacy/"

Note

uv publish --index <name>을 사용할 때는 pyproject.toml 파일이 반드시 존재해야 한다. 즉, 배포 CI 작업에서 체크아웃 단계가 필요하다.

uv publish는 실패한 업로드를 재시도하지만, 배포가 중간에 실패하여 일부 파일만 업로드되고 나머지는 누락되는 경우가 발생할 수 있다. PyPI의 경우 동일한 명령어를 다시 실행하면 기존에 업로드된 동일한 파일은 무시된다. 다른 레지스트리를 사용할 때는 --check-url <index url>을 사용해 패키지가 속한 인덱스 URL(배포 URL이 아님)을 지정한다. --index를 사용할 경우, 인덱스 URL이 체크 URL로 사용된다. uv는 레지스트리에 이미 존재하는 동일한 파일의 업로드를 건너뛰고, 병렬 업로드 경합도 처리한다. 단, 기존 파일은 이전에 레지스트리에 업로드된 파일과 정확히 일치해야 한다. 이는 동일한 버전의 소스 배포판과 휠 파일이 서로 다른 내용으로 실수로 배포되는 것을 방지한다.

패키지 설치하기

uv run을 사용해 패키지를 설치하고 임포트할 수 있는지 테스트한다:

$ uv run --with <PACKAGE> --no-project -- python -c "import <PACKAGE>"

--no-project 플래그는 로컬 프로젝트 디렉토리에서 패키지를 설치하지 않도록 한다.

Tip

최근에 패키지를 설치했다면, 캐시된 버전을 사용하지 않도록 --refresh-package <PACKAGE> 옵션을 추가해야 할 수 있다.

다음 단계

패키지 배포에 대해 더 알아보려면 PyPA 가이드에서 빌드 및 배포 방법을 확인한다.

또는 가이드를 참고해 uv를 다른 소프트웨어와 통합하는 방법을 알아본다.