1 pyproject.toml이란?

pyproject.toml은 Python 프로젝트의 표준 설정 파일이다. Poetry뿐만 아니라 setuptools, Hatch, Flit 등 모든 현대 빌드 도구가 이 파일을 사용한다.

하나의 파일에 프로젝트의 모든 설정이 담긴다:

프로젝트 이름, 버전, 설명
의존성 (필수, 개발, 옵션)
빌드 시스템 설정
스크립트 진입점
도구별 설정 (black, pytest, mypy 등)

2 전체 구조 예시

[tool.poetry]
name = "my-project"
version = "0.1.0"
description = "My awesome Python project"
authors = ["홍길동 <hong@example.com>"]
license = "MIT"
readme = "README.md"
packages = [{include = "my_project", from = "src"}]

[tool.poetry.dependencies]
python = "^3.9"
requests = "^2.28"
pandas = "^2.0"

[tool.poetry.group.dev.dependencies]
pytest = "^7.4"
black = "^23.0"
mypy = "^1.0"

[tool.poetry.scripts]
my-cli = "my_project.cli:main"

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

[tool.black]
line-length = 120

[tool.pytest.ini_options]
testpaths = ["tests"]

[tool.mypy]
strict = true

3 각 섹션 상세 설명

3.1 [tool.poetry] - 프로젝트 메타데이터

[tool.poetry]
name = "my-project"                          # 패키지 이름 (pip install 시 이름)
version = "0.1.0"                            # 현재 버전
description = "프로젝트 설명"                  # 짧은 설명
authors = ["홍길동 <hong@example.com>"]       # 작성자 목록
license = "MIT"                              # 라이선스
readme = "README.md"                         # README 파일 경로
homepage = "https://example.com"             # 프로젝트 홈페이지
repository = "https://github.com/user/repo"  # 소스 저장소
documentation = "https://docs.example.com"   # 문서 URL
keywords = ["data", "analytics"]             # 검색 키워드
classifiers = [                              # PyPI 분류
    "Development Status :: 3 - Alpha",
    "Programming Language :: Python :: 3.11",
]

3.2 [tool.poetry] - packages 설정

Poetry가 어떤 디렉토리를 패키지로 인식할지 지정한다.

# src layout (권장)
packages = [{include = "my_project", from = "src"}]

# flat layout
packages = [{include = "my_project"}]

# 여러 패키지
packages = [
    {include = "my_project", from = "src"},
    {include = "my_utils", from = "src"},
]

디렉토리 구조:

# src layout
my-project/
├── src/
│   └── my_project/
│       ├── __init__.py
│       └── main.py
├── tests/
└── pyproject.toml

# flat layout
my-project/
├── my_project/
│   ├── __init__.py
│   └── main.py
├── tests/
└── pyproject.toml

3.3 [tool.poetry.dependencies] - 필수 의존성

프로젝트 실행에 반드시 필요한 패키지들이다.

[tool.poetry.dependencies]
python = "^3.9"                   # Python 버전 제약
requests = "^2.28"                # 기본 버전 제약
pandas = {version = "^2.0", python = "^3.9"}  # Python 버전별 조건
numpy = {version = "^1.24", optional = true}  # 선택적 의존성

3.4 [tool.poetry.group.*.dependencies] - 그룹별 의존성

# 개발용
[tool.poetry.group.dev.dependencies]
pytest = "^7.4"
black = "^23.0"
mypy = "^1.0"

# 테스트용
[tool.poetry.group.test.dependencies]
pytest-cov = "^4.1"
httpx = "^0.24"

# 문서용 (선택적 그룹 - 기본 설치에서 제외)
[tool.poetry.group.docs]
optional = true

[tool.poetry.group.docs.dependencies]
mkdocs = "^1.5"

3.5 [tool.poetry.extras] - Optional Dependencies

패키지 소비자가 선택적으로 설치할 수 있는 기능 묶음이다.

[tool.poetry.dependencies]
numpy = {version = "^1.24", optional = true}
matplotlib = {version = "^3.7", optional = true}
redis = {version = "^5.0", optional = true}

[tool.poetry.extras]
plotting = ["numpy", "matplotlib"]
cache = ["redis"]
all = ["numpy", "matplotlib", "redis"]

소비자 입장에서 설치:

pip install my-project[plotting]
pip install my-project[all]

3.6 [tool.poetry.scripts] - CLI 진입점

패키지 설치 후 터미널에서 바로 실행할 수 있는 명령을 정의한다.

[tool.poetry.scripts]
my-cli = "my_project.cli:main"

# src/my_project/cli.py
def main():
    print("Hello from my-cli!")

설치 후:

my-cli  # → "Hello from my-cli!" 출력

3.7 [build-system] - 빌드 시스템

# Poetry 기반 프로젝트
[build-system]
requires = ["poetry-core"]
build-backend = "poetry.core.masonry.api"

# setuptools 기반 프로젝트
[build-system]
requires = ["setuptools>=68", "wheel"]
build-backend = "setuptools.build_meta"

이 섹션은 PEP 517/518 표준으로, pip install이나 poetry add가 패키지를 빌드할 때 어떤 도구를 사용할지 결정한다. 자세한 내용은 12편: 빌드 시스템 이해에서 다룬다.

4 도구별 설정

pyproject.toml에 다른 도구(black, pytest, mypy 등)의 설정도 함께 넣을 수 있다.

4.1 black (코드 포매터)

[tool.black]
line-length = 120
target-version = ["py311"]

4.2 pytest (테스트)

[tool.pytest.ini_options]
testpaths = ["tests"]
addopts = "-v --tb=short"

4.3 mypy (타입 검사)

[tool.mypy]
python_version = "3.11"
strict = true
ignore_missing_imports = true

4.4 ruff (린터)

[tool.ruff]
line-length = 120
target-version = "py311"

[tool.ruff.lint]
select = ["E", "F", "I"]

5 Poetry 2.x: [project] 섹션 (PEP 621)

Poetry 2.x부터는 Python 표준인 [project] (PEP 621) 섹션을 우선 사용한다.

# Poetry 2.x 방식
[project]
name = "my-project"
version = "0.1.0"
requires-python = "^3.11"
dependencies = [
    "requests (>=2.28,<3.0)",
    "pandas (>=2.0,<3.0)",
]

[tool.poetry]
packages = [{include = "my_project", from = "src"}]

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

중요

Poetry 2.x에서 [project]와 [tool.poetry]를 혼용할 때, 의존성은 [project.dependencies]에 넣어야 poetry.lock에 반영된다. [tool.poetry.dependencies]에 넣으면 lock에 반영되지 않는 함정이 있다. 자세한 내용은 13편: Git Dependency에서 다룬다.

6 poetry new vs poetry init

6.1 poetry new - 새 프로젝트 생성

poetry new my_project

생성되는 구조:

my_project/
├── pyproject.toml
├── README.md
├── my_project/
│   └── __init__.py
└── tests/
    └── __init__.py

6.2 poetry init - 기존 프로젝트에 Poetry 적용

이미 존재하는 프로젝트에 pyproject.toml을 추가한다.

cd existing_project
poetry init
# 대화형으로 프로젝트 정보 입력

# 비대화형 (기본값으로 생성)
poetry init --no-interaction --name my-project

6.3 requirements.txt에서 마이그레이션

# 1. Poetry 초기화
poetry init --no-interaction

# 2. requirements.txt의 패키지들을 Poetry에 추가
# Linux/macOS
cat requirements.txt | xargs poetry add

# Windows (PowerShell)
Get-Content requirements.txt |
  Where-Object { $_ -and -not $_.StartsWith('#') } |
  ForEach-Object { poetry add $_ }

# 3. 가상환경 생성 & 설치
poetry install

7 요약

섹션	역할
`[tool.poetry]`	프로젝트 메타데이터, 패키지 경로
`[tool.poetry.dependencies]`	필수 의존성
`[tool.poetry.group.*.dependencies]`	그룹별 의존성
`[tool.poetry.extras]`	선택적 의존성 묶음
`[tool.poetry.scripts]`	CLI 진입점
`[build-system]`	빌드 도구 지정
`[tool.*]`	외부 도구 설정 (black, pytest 등)