1 Python 패키지 배포 형태

Python 패키지는 두 가지 형태로 배포된다.

형식	확장자	설명	설치 시 빌드 필요
sdist (소스 배포)	`.tar.gz`	소스코드 압축본	필요
wheel (빌드 배포)	`.whl`	이미 빌드된 결과물	불필요 (빠름)

poetry build
# 생성 결과:
# dist/my_project-0.1.0.tar.gz      ← sdist
# dist/my_project-0.1.0-py3-none-any.whl  ← wheel

힌트

wheel 파일이 있으면 사용자 환경에 빌드 도구가 없어도 설치 가능하다. 순수 Python 패키지는 py3-none-any.whl로 모든 환경에서 동작한다.

2 패키지 빌드: poetry build

# sdist + wheel 모두 생성 (기본)
poetry build

# sdist만 생성
poetry build --format sdist

# wheel만 생성
poetry build --format wheel

빌드 결과는 dist/ 디렉토리에 저장된다.

my_project/
├── dist/
│   ├── my_project-0.1.0.tar.gz
│   └── my_project-0.1.0-py3-none-any.whl
├── pyproject.toml
└── src/

2.1 빌드 전 확인사항

pyproject.toml의 name, version, description 확인
packages 설정이 올바른지 확인
README.md 파일이 존재하는지 확인

3 PyPI 배포: poetry publish

3.1 PyPI 계정 및 토큰 설정

PyPI 계정 생성
Account Settings → API tokens → Add API token
토큰을 Poetry에 등록:

poetry config pypi-token.pypi pypi-XXXXXXXXXXXXXX

3.2 배포 실행

# 빌드 + 배포
poetry publish --build

# 이미 빌드된 패키지 배포
poetry publish

3.3 Test PyPI에 먼저 테스트

실제 PyPI에 배포하기 전에 Test PyPI에서 먼저 확인하는 것을 권장한다.

# Test PyPI 저장소 설정
poetry config repositories.testpypi https://test.pypi.org/legacy/
poetry config pypi-token.testpypi pypi-XXXXXXXXXXXXXX

# Test PyPI에 배포
poetry publish --build --repository testpypi

# Test PyPI에서 설치 확인
pip install --index-url https://test.pypi.org/simple/ my-project

4 사설 PyPI 저장소 설정

조직 내부 패키지를 사설 저장소에서 관리할 때 사용한다.

4.1 저장소 추가

# 사설 저장소 등록
poetry config repositories.private https://pypi.company.com/simple/

# 인증 설정
poetry config http-basic.private username password
# 또는 토큰 사용
poetry config pypi-token.private your-token

4.2 pyproject.toml에 소스 추가

[[tool.poetry.source]]
name = "private"
url = "https://pypi.company.com/simple/"
priority = "supplemental"  # PyPI 우선, 없으면 사설에서 검색

소스 우선순위:

priority	동작
`default`	이 소스만 사용 (PyPI 대체)
`primary`	PyPI와 동일 우선순위
`supplemental`	PyPI에 없는 패키지만 여기서 검색
`explicit`	명시적으로 지정된 패키지만 여기서 설치

4.3 사설 저장소에 배포

poetry publish --build --repository private

5 requirements.txt 내보내기

Poetry로 관리하면서도 requirements.txt가 필요한 경우 (Docker, 레거시 시스템 등):

# 기본 내보내기
poetry export -f requirements.txt -o requirements.txt

# 해시 제외 (Docker에서 유용)
poetry export -f requirements.txt --without-hashes -o requirements.txt

# 개발 의존성 제외
poetry export -f requirements.txt --without dev -o requirements.txt

5.1 Docker에서 활용

# 방법 1: poetry export 사용 (가벼움)
FROM python:3.11-slim
COPY requirements.txt .
RUN pip install -r requirements.txt
COPY src/ src/

# 방법 2: Poetry 직접 사용
FROM python:3.11-slim
RUN pip install poetry
COPY pyproject.toml poetry.lock ./
RUN poetry config virtualenvs.create false && \
    poetry install --only main --no-interaction
COPY src/ src/

6 버전 관리

6.1 수동 버전 업데이트

pyproject.toml에서 직접 수정:

[tool.poetry]
version = "0.2.0"  # 0.1.0 → 0.2.0

6.2 poetry version 명령

# 현재 버전 확인
poetry version

# 버전 범프
poetry version patch   # 0.1.0 → 0.1.1
poetry version minor   # 0.1.0 → 0.2.0
poetry version major   # 0.1.0 → 1.0.0

# 특정 버전으로 설정
poetry version 2.0.0

# 프리릴리스 버전
poetry version prepatch   # 0.1.0 → 0.1.1-alpha.0
poetry version preminor   # 0.1.0 → 0.2.0-alpha.0

7 배포 체크리스트

1. [ ] pyproject.toml 메타데이터 확인 (name, version, description)
2. [ ] README.md 작성
3. [ ] LICENSE 파일 추가
4. [ ] 테스트 통과 확인: poetry run pytest
5. [ ] 버전 업데이트: poetry version <patch|minor|major>
6. [ ] 빌드: poetry build
7. [ ] Test PyPI 배포 및 확인 (선택)
8. [ ] PyPI 배포: poetry publish
9. [ ] Git 태그: git tag v0.1.0 && git push --tags

8 요약

명령어	역할
`poetry build`	sdist + wheel 생성
`poetry publish`	PyPI에 배포
`poetry publish --build`	빌드 + 배포 동시
`poetry version patch`	패치 버전 업데이트
`poetry export -f requirements.txt`	requirements.txt 내보내기
`poetry config repositories.name url`	사설 저장소 등록
`poetry config pypi-token.pypi token`	PyPI 토큰 설정