[PYTHON] pyproject.toml이 setup.py와 requirements.txt를 대체하는 3가지 방법과 핵심 차이 해결

pyproject.toml

 

 

파이썬 개발 생태계는 지난 몇 년간 거대한 변화를 맞이했습니다. 과거 requirements.txt와 setup.py에 의존하던 파편화된 설정 방식에서 벗어나, 이제는 PEP 518과 PEP 621을 필두로 한 pyproject.toml 중심의 통합 관리 시대로 접어들었습니다. 본 포스팅에서는 왜 이 변화가 일어났는지, 그리고 실무에서 기존 파일들을 어떻게 성공적으로 대체할 수 있는지 구체적인 해결 방법을 제시합니다.

---

1. 파이썬 설정 파일의 역사와 변화의 필요성

기존의 파이썬 프로젝트 관리 방식은 크게 두 가지 문제점을 안고 있었습니다. 첫째, setup.py는 실행 가능한 '파이썬 코드'였기 때문에 빌드 시스템이 설정을 읽기 위해 코드를 실행해야만 했습니다. 이는 보안상 위험할 뿐만 아니라 빌드 속도를 저하시키는 원인이 되었습니다. 둘째, requirements.txt는 단순히 패키지 목록만 나열할 뿐, 프로젝트 자체의 메타데이터(버전, 저자, 라이선스 등)를 담지 못했습니다. 이러한 한계를 극복하기 위해 등장한 것이 바로 pyproject.toml입니다. 이 파일은 선언적(Declarative) 방식을 취하며, 사람이 읽기 쉽고 기계가 파싱하기 최적화된 형식을 제공합니다.

---

2. setup.py vs requirements.txt vs pyproject.toml 비교

각 설정 방식의 특징과 차이점을 한눈에 파악할 수 있도록 표로 정리했습니다.

비교 항목	requirements.txt	setup.py (setuptools)	pyproject.toml (Modern)
형식	Plain Text (단순 목록)	Python Script (실행 코드)	TOML (선언적 설정)
주요 용도	의존성 라이브러리 나열	패키지 빌드 및 배포 설정	빌드 시스템 및 메타데이터 통합 관리
보안성	높음	낮음 (코드 실행 필요)	매우 높음 (정적 파싱)
표준 준수	비표준 (pip 전용)	사실상 표준 (Legacy)	PEP 517, 518 공식 표준
유지보수성	단순함	복잡함 (로직 포함 가능)	매우 직관적이고 체계적임

---

3. pyproject.toml로 대체하는 3가지 구체적 방법

방법 01. 빌드 시스템 정의 (Build-system)

과거에는 setuptools가 고정이었으나, 이제는 Poetry, Flit, Hatch 등 다양한 빌드 백엔드를 선택할 수 있습니다. pyproject.toml 상단에 이를 명시하여 빌드 환경을 격리하고 해결할 수 있습니다.

방법 02. 프로젝트 메타데이터 통합 (Project Metadata)

setup.py의 setup() 함수 안에 적던 이름, 버전, 설명, 저자 정보를 [project] 섹션으로 옮깁니다. 이는 도구에 종속되지 않는 표준화된 방식입니다.

방법 03. 의존성 관리의 일원화 (Dependencies)

requirements.txt에 적던 패키지 목록을 dependencies 항목에 작성합니다. 특히 선택적 기능(Optional Features)은 [project.optional-dependencies]를 통해 더 체계적으로 관리할 수 있습니다.

---

4. 실전 전환 가이드 (Sample Example)

기존의 setup.py와 requirements.txt 환경을 pyproject.toml로 변환하는 예시 코드입니다.

[Before] 기존 방식

# requirements.txt
requests>=2.25.1
pandas

# setup.py
from setuptools import setup
setup(
    name="my_cool_app",
    version="0.1.0",
    install_requires=["requests>=2.25.1", "pandas"]
)
    

[After] pyproject.toml 통합 방식

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

[project]
name = "my_cool_app"
version = "0.1.0"
description = "현대적인 파이썬 프로젝트 관리 예제"
authors = [
    {name = "Chaewon", email = "dev@example.com"}
]
dependencies = [
    "requests>=2.25.1",
    "pandas",
]

[project.optional-dependencies]
dev = ["pytest", "black"]
    

---

5. 전환 시 발생할 수 있는 이슈와 해결 전략

모든 프로젝트를 한 번에 옮기는 것은 쉽지 않습니다. 다음은 현업에서 자주 발생하는 문제와 그 해결책입니다.

• 문제: 오래된 배포 환경(CI/CD)에서 pyproject.toml을 인식하지 못함.
• 해결: pip 버전을 최신(21.3 이상)으로 업그레이드하거나, 과도기적으로 setup.py에 setup()만 남겨두고 설정을 pyproject.toml에서 읽어오도록 구성합니다.
• 문제: 동적 버전 관리(Git Tag 기반 등)가 어려움.
• 해결: setuptools-scm이나 poetry-dynamic-versioning 같은 플러그인을 사용하여 dynamic 필드 설정을 활용합니다.

---

6. 결론: 왜 지금 당장 바꿔야 하는가?

파이썬 공식 문서와 커뮤니티는 이미 pyproject.toml을 권장 사항으로 확정했습니다. 이는 단순히 트렌드를 따르는 것이 아니라, 프로젝트의 재현성(Reproducibility)을 확보하고 빌드 아티팩트의 일관성을 유지하기 위함입니다. requirements.txt의 파편화된 관리를 끝내고 하나의 파일로 응집된 개발 환경을 구축해 보시기 바랍니다.

---

내용의 출처

• Python Packaging User Guide: "Project summaries"
• PEP 518: "Specifying Minimum Build System Requirements for Python Projects"
• PEP 621: "Storing project metadata in pyproject.toml"
• Setuptools Official Documentation: "Configuring setuptools using pyproject.toml"