Table of Contents

PyPI 패키지 배포 가이드 — 가입부터 pip install 내 패키지까지

pip install requests를 실행하면 패키지가 어디서 다운로드될까요? 바로 PyPI(Python Package Index)입니다. 내가 만든 Python 코드도 여기에 올리면, 전 세계 누구나 pip install 내패키지로 설치할 수 있습니다.

이 글에서는 PyPI 패키지 배포의 전 과정을 다룹니다. PyPI가 뭔지, 어떻게 가입하고, 내 패키지를 어떻게 올리는지 — 순서대로 따라하면 됩니다.

PyPI란?

PyPI는 Python Package Index의 약자로, Python 패키지들이 모여있는 공식 저장소입니다. npm(Node.js)이나 RubyGems(Ruby)와 같은 역할입니다.

항목	내용
URL	https://pypi.org
등록 패키지 수	50만 개 이상
비용	무료
테스트 환경	https://test.pypi.org (연습용)

Step 1. PyPI 가입

pypi.org/account/register 접속
이름, 이메일, 비밀번호 입력 후 가입
이메일 인증 완료
2FA(이중 인증) 설정 — 2024년부터 필수! Account Settings → 2FA 활성화
API Token 발급 — Account Settings → API tokens → Add API token → Scope: “Entire account” → 생성된 토큰 복사 보관

⚠️ API Token은 pypi-로 시작하는 긴 문자열입니다. 한 번만 표시되므로 반드시 안전한 곳에 저장하세요.

Step 2. 패키지 프로젝트 구조 만들기

my-package/
├── src/
│   └── my_package/
│       ├── __init__.py
│       └── main.py
├── tests/
│   └── test_main.py
├── pyproject.toml      ← 패키지 설정 파일 (핵심)
├── README.md
└── LICENSE

pyproject.toml 작성 (핵심 파일)

[build-system]
requires = ["setuptools>=61.0"]
build-backend = "setuptools.build_meta"

[project]
name = "my-awesome-package"       # PyPI에서 고유해야 함
version = "0.1.0"
description = "간단한 설명을 여기에"
readme = "README.md"
license = {text = "MIT"}
requires-python = ">=3.8"
authors = [
    {name = "Your Name", email = "[email protected]"}
]
keywords = ["python", "utility"]
classifiers = [
    "Programming Language :: Python :: 3",
    "License :: OSI Approved :: MIT License",
    "Operating System :: OS Independent",
]
dependencies = [
    "requests>=2.25.0",    # 의존성 패키지가 있다면 여기에
]

[project.urls]
Homepage = "https://github.com/username/my-package"

init.py

# src/my_package/__init__.py
from .main import hello

__version__ = "0.1.0"

main.py (예시)

# src/my_package/main.py
def hello(name: str = "World") -> str:
    return f"Hello, {name}!"

Step 3. 빌드

# 빌드 도구 설치
pip install build

# 패키지 빌드
python -m build

실행하면 dist/ 폴더에 두 개의 파일이 생성됩니다:

dist/
├── my_awesome_package-0.1.0-py3-none-any.whl   ← wheel 파일
└── my_awesome_package-0.1.0.tar.gz              ← 소스 배포판

Step 4. TestPyPI에 먼저 테스트 (권장)

실제 PyPI에 올리기 전에 테스트 환경에서 먼저 확인합니다:

# twine 설치 (업로드 도구)
pip install twine

# TestPyPI에 업로드
twine upload --repository testpypi dist/*

Username에는 __token__, Password에는 TestPyPI 토큰을 입력합니다.

# TestPyPI에서 설치 테스트
pip install --index-url https://test.pypi.org/simple/ my-awesome-package

Step 5. PyPI 패키지 배포 (본 업로드)

# 실제 PyPI에 업로드
twine upload dist/*

Username: __token__
Password: pypi-로 시작하는 API Token

업로드 성공 후 1~2분 내로 pip install my-awesome-package가 전 세계에서 가능해집니다!

.pypirc 설정 (매번 토큰 입력 생략)

# ~/.pypirc
[pypi]
username = __token__
password = pypi-여기에_토큰_입력

[testpypi]
repository = https://test.pypi.org/legacy/
username = __token__
password = pypi-여기에_테스트_토큰_입력

Step 6. 버전 업데이트

pyproject.toml에서 version 변경 (예: "0.1.0" → "0.2.0")
python -m build로 다시 빌드
twine upload dist/*로 다시 업로드

같은 버전 번호로는 재업로드할 수 없으므로, 반드시 버전을 올려야 합니다.

자주 하는 실수

실수	해결
패키지 이름 중복	pypi.org에서 먼저 검색. 이름이 이미 있으면 다른 이름 사용
같은 버전 재업로드	PyPI는 같은 버전 덮어쓰기 불가. 버전 번호를 올려야 함
2FA 미설정	2024년부터 필수. 설정 안 하면 업로드 차단
README가 PyPI에 안 보임	`pyproject.toml`에 `readme = "README.md"` 확인
의존성 패키지 누락	`[project] dependencies`에 필요한 패키지 전부 명시

PyPI 패키지 배포 체크리스트

✅ pyproject.toml 작성 완료
✅ README.md 작성
✅ LICENSE 파일 추가
✅ 로컬에서 pip install -e . 로 테스트
✅ TestPyPI 업로드 및 설치 테스트
✅ 실제 PyPI 업로드
✅ pip install 내패키지 동작 확인

내가 만든 코드를 전 세계에 배포하는 건 생각보다 간단합니다. pyproject.toml 하나 작성하고, build하고, twine upload하면 끝. 더 자세한 내용은 Python 공식 패키징 가이드를 참고하세요.