Python Poetry 패키지 관리와 가상 환경 완벽 정리

Poetry를 선택하는 이유

pip + venv + setup.py의 조합은 설정이 분산되고 lock 파일이 없어 재현 가능한 빌드가 어렵습니다. Poetry는 의존성 선언, 가상 환경, lock 파일, 패키지 빌드를 pyproject.toml 하나로 통합하여 Node.js의 npm/yarn과 유사한 경험을 제공합니다.

설치 및 프로젝트 초기화

# Poetry 설치 (공식 방법)
curl -sSL https://install.python-poetry.org | python3 -

# 새 프로젝트 생성
poetry new my-api
# 기존 프로젝트에 Poetry 도입
cd existing-project && poetry init

# 가상 환경 프로젝트 내 생성 설정
poetry config virtualenvs.in-project true

pyproject.toml 구조

[tool.poetry]
name = "my-api"
version = "1.2.0"
description = "FastAPI 기반 REST API"
authors = ["dev <dev@example.com>"]
readme = "README.md"
packages = [{include = "my_api", from = "src"}]

[tool.poetry.dependencies]
python = "^3.11"
fastapi = "^0.109.0"
uvicorn = {version = "^0.27.0", extras = ["standard"]}
sqlalchemy = "^2.0"
pydantic-settings = "^2.1"

[tool.poetry.group.dev.dependencies]
pytest = "^8.0"
pytest-asyncio = "^0.23"
ruff = "^0.2"
mypy = "^1.8"

[tool.poetry.group.docs]
optional = true
[tool.poetry.group.docs.dependencies]
mkdocs = "^1.5"
mkdocs-material = "^9.5"

[tool.poetry.scripts]
start = "my_api.main:app"

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

의존성 관리 명령어

# 패키지 추가 (자동으로 호환 버전 해결)
poetry add fastapi uvicorn[standard]

# 개발 의존성 추가
poetry add --group dev pytest ruff

# 선택적 그룹 추가
poetry add --group docs mkdocs

# 버전 제약 지정
poetry add "sqlalchemy>=2.0,<3.0"

# 패키지 제거
poetry remove unused-package

# 의존성 트리 확인
poetry show --tree

# 보안 취약점 확인 (poetry-audit-plugin)
poetry audit

가상 환경과 실행

# 의존성 설치 (lock 파일 기반)
poetry install

# 프로덕션 의존성만 설치
poetry install --without dev,docs

# 가상 환경 내에서 명령 실행
poetry run python -m my_api.main
poetry run pytest tests/
poetry run uvicorn my_api.main:app --reload

# 가상 환경 셸 진입
poetry shell

# 가상 환경 정보 확인
poetry env info
poetry env list

Lock 파일과 재현성

# poetry.lock은 모든 하위 의존성의 정확한 버전을 기록
# 반드시 버전 관리에 포함해야 함

# lock 파일 갱신 (의존성 업데이트)
poetry update           # 모든 패키지
poetry update fastapi   # 특정 패키지만

# lock 파일 검증
poetry check
poetry lock --check    # pyproject.toml과 일치 확인

패키지 빌드와 배포

# 빌드 (wheel + sdist)
poetry build

# PyPI에 배포
poetry publish

# 사설 저장소 설정
poetry config repositories.private https://pypi.company.com/simple/
poetry config http-basic.private username password
poetry publish -r private

# Docker에서 활용
# Dockerfile
FROM python:3.11-slim
WORKDIR /app
RUN pip install poetry && poetry config virtualenvs.create false
COPY pyproject.toml poetry.lock ./
RUN poetry install --without dev --no-root
COPY src/ ./src/
RUN poetry install --without dev
CMD ["uvicorn", "my_api.main:app", "--host", "0.0.0.0"]

pip vs Poetry vs PDM 비교

• Poetry는 Python 프로젝트의 표준 도구로 자리잡았으며, 대부분의 새 프로젝트에서 권장됩니다
• CI/CD에서는 poetry install --no-interaction으로 비대화형 설치를 사용하세요
• 모노레포에서는 poetry-workspace-plugin을 활용할 수 있습니다