패키지 빌드 및 배포

프로젝트 준비

배포 전에 프로젝트가 배포 가능 상태인지 확인하세요. 프로젝트에는 pyproject.toml에 [build-system] 정의가 포함되어야 합니다. 이 정의가 없으면 uv는 프로젝트에서의 uv sync 작업 중에 빌드하지 않지만, uv build 중에는 레거시 setuptools 빌드 백엔드(build backend)로 폴백합니다. 빌드 시스템을 명시적으로 구성하는 것을 권장합니다.

패키지 빌드

다음 명령으로 빌드 프로세스를 실행합니다:

$ uv build

기본적으로 빌드 아티팩트는 dist/ 하위 디렉터리에 생성됩니다. uv build <SRC>로 소스 디렉터리를 지정하거나, uv build --package <PACKAGE>로 워크스페이스(workspace)의 특정 패키지를 대상으로 할 수 있습니다.

배포 준비 시 uv build --no-sources를 실행하여 tool.uv.sources 없이 패키지가 올바르게 빌드되는지 확인하세요. 이렇게 하면 다른 빌드 도구와의 호환성을 보장할 수 있습니다.

버전 업데이트

uv version 명령으로 배포 전에 패키지 버전을 업데이트합니다:

$ uv version 1.0.0
hello-world 0.7.0 => 1.0.0

--dry-run으로 변경 사항을 미리 볼 수 있습니다:

$ uv version 2.0.0 --dry-run
hello-world 1.0.0 => 2.0.0

--bump를 사용해 버전 구성 요소를 증가시킵니다(major, minor, patch, stable, alpha, beta, rc, post, dev):

$ uv version --bump minor
hello-world 1.2.3 => 1.3.0

여러 bump 옵션을 결합할 수 있습니다:

$ uv version --bump patch --bump dev=66463664
hello-world 0.0.1 => 0.0.2.dev66463664

프리릴리스 버전으로 이동하려면:

$ uv version --bump patch --bump beta
hello-world 1.3.0 => 1.3.1b1

stable을 사용해 프리릴리스 구성 요소를 제거합니다:

$ uv version --bump stable
hello-world 1.3.1b2 => 1.3.1

기본적으로 uv version은 잠금과 동기화를 모두 수행합니다. 둘 다 방지하려면 --frozen을, 동기화만 건너뛰려면 --no-sync를 사용하세요.

패키지 배포

다음 명령으로 배포합니다:

$ uv publish

다음 방법으로 자격 증명을 제공합니다: - --token 또는 UV_PUBLISH_TOKEN 환경 변수 - --username 및 --password 플래그 또는 UV_PUBLISH_USERNAME 및 UV_PUBLISH_PASSWORD 환경 변수

GitHub Actions 또는 Trusted Publishers를 사용하는 경우 자격 증명이 필요하지 않습니다 — PyPI 프로젝트에 신뢰할 수 있는 게시자를 추가하세요.

커스텀 인덱스(index)의 경우 pyproject.toml에서 구성합니다:

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

그런 다음 다음과 같이 배포합니다:

$ uv publish --index testpypi

배포가 부분적으로 실패한 경우 같은 명령을 다시 실행하세요. 다른 레지스트리(registry)의 경우 --check-url <index url>을 사용해 이미 업로드된 파일을 건너뛸 수 있습니다.

패키지와 함께 attestation 업로드

uv publish는 현재 attestation을 생성하지 않습니다. attestation은 배포 전에 별도로 생성해야 합니다. 그러나 uv는 업로드 중에 PEP 740 attestation을 자동으로 검색하고 매칭합니다:

$ ls dist/
hello_world-1.0.0-py3-none-any.whl
hello_world-1.0.0-py3-none-any.whl.publish.attestation
hello_world-1.0.0.tar.gz
hello_world-1.0.0.tar.gz.publish.attestation

일부 레지스트리는 attestation을 지원하지 않을 수 있습니다. 필요한 경우 --no-attestations 또는 UV_PUBLISH_NO_ATTESTATIONS를 사용해 이 동작을 비활성화하세요.

패키지 설치 확인

설치와 임포트를 테스트하려면:

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

--no-project 플래그는 로컬 프로젝트 디렉터리에서의 설치를 방지합니다. 최근 설치한 패키지의 캐시(cache)를 우회하려면 --refresh-package <PACKAGE>를 포함하세요.

다음 단계

패키지 빌드 및 배포에 관한 PyPA 가이드를 살펴보거나, uv와 다른 도구 및 플랫폼을 함께 사용하는 통합 가이드를 참조하세요.

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

원문(영어): https://docs.astral.sh/uv/guides/package/