[pyproject.toml 완전 정복 1편] pyproject.toml 등장 배경 및 기본 구조

파이썬 패키징 환경은 오랜 기간 setup.py, requirements.txt 등 여러 파일에 의존해 왔습니다. 이 방식은 비일관적이고, 빌드 백엔드와 의존성 관리가 분산되어 프로젝트 설정이 복잡해지는 문제가 있었습니다. 이러한 문제를 해결하기 위해 PEP 518, PEP 621 등의 표준 제안이 나오고, 그 결과로 pyproject.toml이라는 단일 설정 파일을 중심으로 한 현대적 패키징 생태계가 구축되었습니다.

이번 글에서는 pyproject.toml이 왜 등장했는지, 기존 방식 대비 어떤 이점을 갖는지, 그리고 pyproject.toml의 기본 구조를 개괄적으로 살펴보겠습니다.

기존 파이썬 패키징 방식: setup.py, requirements.txt

이전에는 다음과 같은 파일들을 따로 관리했습니다.

• setup.py: 패키지 메타데이터(이름, 버전, 의존성)와 빌드 로직 정의
• requirements.txt: 개발 환경에서 필요한 의존성 명시
• MANIFEST.in, setup.cfg: 패키지에 포함할 파일 목록이나 추가 설정

이 방식의 문제점:

• 분산된 설정: 패키지 메타데이터, 의존성, 빌드 규칙이 여러 파일에 흩어져 있음
• 비표준적 빌드 시스템: setup.py는 실행 가능한 스크립트로, 빌드 과정이 개발자마다 달라질 수 있음
• 복잡한 의존성 관리: requirements.txt와 setup.py 사이 의존성 중복 또는 불일치 발생 가능

결과적으로 프로젝트 규모가 커질수록 패키징·빌드·의존성 관리가 혼란스러워지고, 재현성 높은 빌드 환경 구성이 어려워집니다.

pyproject.toml 등장 배경

PEP 518(2017년)에서 pyproject.toml 파일을 통한 빌드 시스템 설정 표준을 제안했습니다. 이 파일은 다음을 목표로 합니다.

• 단일 진입점: 빌드 시스템 정보, 의존성 정의를 한 곳에 모으기
• 표준화된 빌드 인터페이스: 빌드 백엔드(예: setuptools, Poetry, Flit)를 pyproject.toml에 명시하면 pip 같은 설치 도구가 이를 자동으로 인식
• 의존성 명시: 빌드 시 필요한 의존성을 pyproject.toml 내 [build-system] 섹션에 기재, 빌드 단계 의존성 해결 자동화
• 이후 PEP 621(2020년)에서 [project] 섹션을 통해 패키지 메타데이터를 표준화하여 setup.py 없이도 패키지 정보를 정의할 수 있게 됨.

이로써 pyproject.toml는 Python 패키징의 새로운 표준 기반이 되었습니다.

pyproject.toml 기본 구조 개요

pyproject.toml는 TOML 포맷으로, 다음과 같은 섹션을 가질 수 있습니다.

• [build-system]: 빌드 백엔드 지정(예: "build-backend" = "setuptools.build_meta"), 빌드 시 필요한 의존성(requires) 명시
• [project]: PEP 621 기반 패키지 메타데이터(이름, 버전, 작가, 라이선스, 종속성 등) 정의
• [project.optional-dependencies]: 추가 선택적 의존성 그룹 관리
• [project.scripts], [project.entry-points]: CLI 스크립트나 엔트리 포인트 정의
• [tool.<tool_name>]: Poetry, Flit, Hatch 등 특정 빌드 백엔드나 린터, 포매터용 툴 설정

예시(간단히):

[build-system]
requires = ["setuptools", "wheel"]
build-backend = "setuptools.build_meta"

[project]
name = "my_package"
version = "0.1.0"
description = "My awesome Python package"
authors = [{name="Alice", email="alice@example.com"}]
dependencies = ["requests", "numpy"]

이렇게 한 파일에 빌드 백엔드, 패키지 이름/버전, 의존성을 모아놓을 수 있어 관리가 수월해집니다.

장단점

장점:

• 중앙화된 설정: 빌드, 의존성, 메타데이터를 한 곳에서 관리
• 표준화: PEP 표준 기반으로 도구 간 호환성↑, 릴리즈/배포 파이프라인 자동화 용이
• 재현성 있는 빌드: 빌드에 필요한 의존성 명시로 동일한 환경 재현 가능

단점:

• 새로운 표준 학습 필요: 기존 setup.py 방식에서 전환 시 초기 러닝 커브 발생
• 도구 선택 고민: Poetry, Flit, Hatch 등 빌드 백엔드 다양, 각 도구 특징 파악 필요

대부분의 현대 Python 패키징 툴들이 pyproject.toml을 지원하거나 적극 활용하는 추세이므로, 새로운 프로젝트나 기존 프로젝트 마이그레이션 시 pyproject.toml 도입을 고려해볼 만합니다.

결론

• 기존 파이썬 패키징의 복잡성과 비일관성을 해소하기 위해 pyproject.toml 표준이 등장
• 단일 설정 파일로 빌드 시스템, 메타데이터, 의존성 관리 표준화 가능
• 다음 글에서 [build-system] 섹션을 비롯한 세부 설정, 빌드 백엔드 선택 및 설정 방법을 더욱 자세히 다루며 실용적인 예제를 살펴볼 예정