[PYTHON] setup.py vs pyproject.toml : Python 패키징의 과거와 미래

[PYTHON] setup.py vs pyproject.toml

 

Python 프로젝트에서 패키징과 배포를 위해 사용되는 핵심 파일은 setup.py와 pyproject.toml이다. 전자는 오랜 시간 동안 사실상의 표준으로 사용되었고, 후자는 PEP 518/517 이후 등장한 새로운 표준이다. 이 두 파일은 서로 다른 생태계를 기반으로 하지만, 궁극적인 목적은 동일하다. 바로 Python 코드를 재사용 가능한 패키지로 구성하고 PyPI 등으로 배포</strong할 수 있도록 하는 것이다.

1. Python 패키징의 역사적 흐름

• setup.py: distutils → setuptools 중심의 전통적 방식
• pyproject.toml: 표준화된 빌드 메타데이터 및 PEP 기반의 구성 파일

이제는 새로운 프로젝트의 대부분이 pyproject.toml을 채택하고 있으며, 특히 Poetry, Flit, Hatch 같은 도구와 함께 쓰인다.

2. setup.py란?

setup.py는 setuptools 패키지를 이용해 패키지 메타정보와 빌드 정보를 정의하는 Python 스크립트이다.

# setup.py 예시
from setuptools import setup

setup(
    name='myproject',
    version='0.1.0',
    packages=['myproject'],
    install_requires=[
        'requests',
        'numpy'
    ],
)

• 프로그램 가능한 구성이 가능
• 동적 버전, 조건부 설치 등 유연성
• 그러나 유지보수 및 표준화 어려움

3. pyproject.toml이란?

pyproject.toml은 Python 빌드 시스템을 위한 표준 설정 파일로, PEP 518에서 정의되었다. build-backend와 프로젝트 메타데이터를 명확히 분리하여 빌드 도구 간 호환성과 모듈화를 실현한다.

# pyproject.toml 예시 (Poetry 기반)
[tool.poetry]
name = "myproject"
version = "0.1.0"
description = "예제 프로젝트"
authors = ["Martino"]

[tool.poetry.dependencies]
python = "^3.10"
requests = "^2.31.0"

[build-system]
requires = ["poetry-core>=1.0.0"]
build-backend = "poetry.core.masonry.api"

• TOML 포맷으로 명확하고 파싱이 용이
• Poetry, Hatch, Flit 등 다양한 백엔드 도구 지원
• 프로젝트 루트의 단일 설정 파일로 통합 가능

4. 실제 사용 시 비교

항목	setup.py	pyproject.toml
형식	Python 코드 (스크립트)	TOML (데이터 구조)
표준화	비공식 관례	PEP 518, PEP 621 등 공식 표준
의존성 관리	requirements.txt 또는 setup.py 내부 정의	[tool.poetry.dependencies] 섹션
확장성	직접 스크립트 구현	툴에 따라 커스터마이징 가능
CI/CD 통합	전통적인 방식 지원	보다 일관된 자동화 도구와 연계
호환성	기존 프로젝트와 완벽 호환	최신 툴 및 환경에서 권장됨

5. 언제 setup.py를 써야 할까?

• 기존 프로젝트를 유지보수 중이라면
• setup.cfg, MANIFEST.in 등과 함께 쓰는 경우
• Python 스크립트 기반의 유연한 커스터마이징이 필요할 때

6. 언제 pyproject.toml을 선택해야 할까?

• 새로운 프로젝트를 시작하는 경우
• Poetry, Hatch 등의 툴과 연동하려는 경우
• 빌드와 의존성을 명확하게 분리하고 싶을 때
• 일관된 구조와 모던한 패키징 생태계를 따르고 싶을 때

7. 병행 사용도 가능할까?

일부 경우에는 setup.py와 pyproject.toml을 병행해서 사용할 수도 있다. 특히 pyproject.toml에는 build 시스템 정보만 명시하고, 실제 구성은 setup.py로 계속 유지하는 방법도 있다.

# 최소 구성 예시
[build-system]
requires = ["setuptools", "wheel"]
build-backend = "setuptools.build_meta"

8. Poetry vs setuptools

비교 항목	Poetry	setuptools
패키징 방식	pyproject.toml 기반	setup.py 또는 setup.cfg
의존성 해석	lock file 생성 (poetry.lock)	requirements.txt 필요
명령어 일관성	poetry build / install / publish	python setup.py / pip
사용자 친화성	높음	중간

9. Python Packaging Authority의 공식 방향

pyproject.toml은 Python Packaging Authority(PyPA)에서 장려하는 공식 미래 지향적 표준이다. 향후 더 많은 툴이 이를 기반으로 발전하고 있으며, 기존 setup.py 중심의 구조는 점차 축소될 전망이다.

대표적인 관련 PEP 문서:

• PEP 517: A build-system independent format for source trees
• PEP 518: Specifying Minimum Build System Requirements for Python Projects
• PEP 621: Storing project metadata in pyproject.toml

결론: 선택은 자유지만, 방향은 정해졌다

Python 개발 환경은 빠르게 진화하고 있다. setup.py는 여전히 유용하지만, pyproject.toml은 Python 생태계의 표준으로 자리 잡아가고 있다. 프로젝트의 성격과 팀의 경험, 자동화 시스템 등을 고려해 현명하게 선택하되, 장기적으로는 pyproject.toml로의 전환을 검토하는 것이 바람직하다.

---

출처 (References)

• Python Packaging Authority 공식 문서
• Poetry 공식 문서
• setuptools 공식 문서