pyproject.toml 톺아보기

Python 개발의 핵심:  pyproject.toml

pyproject.toml이란?

- Python 프로젝트의 의존성, 빌드 방식, 도구 설정을 통합 관리하는 구성 파일
- Python 공식 표준 (PEP 518)
- uv, poetry, black, pytest, ruff 등 다양한 도구와 연동됨

기본 구조 예시

[project]
name = "myapp"
version = "0.1.0"
description = "A sample Python project using pyproject.toml"
authors = [{ name = "Hyunmin", email = "hyunmin@example.com" }]
dependencies = [
    "requests>=2.31",
    "pydantic>=2.0,<3.0"
]
requires-python = ">=3.10"

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

[tool.black]
line-length = 88
target-version = ["py310"]

[tool.ruff]
select = ["E", "F"]
ignore = ["E501"]

주요 섹션 설명

project

• 프로젝트 기본 정보를 설정
• 의존성 정의를 포함

주요 항목

• name: 프로젝트 이름
• version: 프로젝트의 버전 (자유롭게 지정가능, SemVer 권장)
• description: 프로젝트의 설명
• authors: 이름/이메일
• dependencies: 의존성 패키지 목록 (requirements.txt를 대체 가능)
• requires-python: 최소 Python 버전
  
  

build-system

• 프로젝트 빌드시 사용할 도구 지정
• 패키지를 설치하거나 빌드할 때 어떤 도구를 사용할지 Python에게 알려주는 역할
• 과거엔 setup.py로만 가능했지만, PEP 517/518 도입 이후부터는 해당 방식이 표준

주요 항목

• requires: 빌드에 필요한 패키지들. 보통 setuptools, wheel, 혹은 poetry 등
• build-backend:실제 빌드 실행을 담당하는 도구의 Python 모듈 이름

 

tool

• 코드 품질 관리나 테스트 자동화를 위한 외부 도구들의 설정
• pyproject.toml을 통해 다양한 개발 도구의 설정을 중앙에서 관리할 수 있음
• 팀 프로젝트에서 일관된 개발 환경 유지에 도움

지원 도구

• black, ruff, pytest, isort, mypy, poetry, uv 등

 

pyproject.toml vs requirements.text

항목	pyproject.toml	requirements.txt
목적	전체 설정 통합	의존성 명시
종속성 고정	가능 (uv.lock)	직접 명시
확장성	높음	낮음
최신 표준	✅	❌

 

도구 추천

• uv: 초고속 패키지 설치 + uv.lock 생성
• poetry: 의존성 + 빌드 + 배포 통합 관리
• black, ruff, pytest: 코드 포맷팅, 정적 검사, 테스트
• build, flit, hatch: PyPI 업로드 및 패키징 빌드 시스템

 

요약

• pyproject.toml은 Python 프로젝트 관리의 표준
• 복잡한 설정을 한 곳에서 통합 가능
• 의존성 설치부터 린터/테스트 도구 설정까지 커버
• requirements.txt보다 더 강력하고 깔끔한 구성