Poetry 의존성 해결 에러 해결 가이드

Poetry는 Python 프로젝트의 의존성 관리를 위한 강력한 도구이지만, 복잡한 의존성 그래프에서 해결 에러가 빈번하게 발생합니다. 이 글에서는常见的 에러 패턴과 해결 방법을 다룹니다.

Environment

$ poetry --version
Poetry (version 1.7.1)

$ python --version
Python 3.11.5

$ cat pyproject.toml
[tool.poetry]
name = "my-project"
version = "0.1.0"
description = "Example project"

[tool.poetry.dependencies]
python = "^3.10"
django = "^4.2"
celery = "^5.3"
redis = "^4.5"

Problem: Dependency Resolution Failed

다음과 같은 에러가 발생하는 경우:

$ poetry add psycopg2-binary

SolverProblemError

Because celery (5.3.3) depends on kombu (>=5.3.2,<5.4)
 and kombu (5.3.2) depends on amqp (>=5.1.1,<5.2),
 celery (5.3.3) requires amqp (>=5.1.1,<5.2).
And because amqp (5.1.4) depends on billiard (>=4.1.0,<4.2),
 celery (5.3.3) requires billiard (>=4.1.0,<4.2).
So, because billiard (4.0.2) is not compatible with billiard (>=4.1.0,<4.2),
 and my-project (0.1.0) depends on celery (^5.3),
 version solving failed.

또는 lock 파일이 손상된 경우:

$ poetry install
PoetryException

Poetry was unable to lock the project dependencies.
Please verify that your pyproject.toml is valid.

Analysis: 의존성 그래프 분석

의존성 문제를 진단하기 위해 그래프를 분석합니다:

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

django 4.2.5 Django is a high-level Python Web framework.
├── asgirefs >= 3.6.0, < 4
├── sqlparse >= 0.3.1
└── tzdata *

celery 5.3.3 Distributed Task Queue.
├── billiard >= 4.1.0, < 4.2
├── kombu >= 5.3.2, < 5.4
│   ├── amqp >= 5.1.1, < 5.2
│   └── vine >= 5.0.0
└── click >= 8.1.2, < 9.0

redis 4.5.5 Redis client library for Python.
└── async-timeout >= 4.0.2

의존성 충돌을 더 자세히 확인합니다:

# 특정 패키지 의존성 확인
$ poetry show --why billiard

The following packages depend on billiard:
celery 5.3.3

# 특정 버전의 의존성 확인
$ pip show billiard
Name: billiard
Version: 4.0.2
Requires: kombu

Solution: 의존성 해결 에러 해결 방법

방법 1: 버전 제약 완화

# pyproject.toml 수정 전
[tool.poetry.dependencies]
celery = "5.3.3"  # 정확한 버전 고정
redis = "4.5.5"

# 수정 후
[tool.poetry.dependencies]
celery = "^5.3"  # 유연한 버전 허용
redis = "^4.5"

방법 2: lock 파일 초기화

# Lock 파일 삭제 후 재생성
$ rm poetry.lock
$ poetry lock

# 또는 특정 메이저 버전으로 초기화
$ poetry lock --no-update

방법 3: 마이그레이션 매니저 활용

# pyproject.toml에 마이그레이션 매니저 추가
[tool.poetry.dependencies]
python = "^3.10"
django = "^4.2"
celery = {version = "^5.3", extras = ["redis"]}
redis = {version = "^4.5", extras = ["hiredis"]}

방법 4: 소스 제한 설정

# pyproject.toml
[[tool.poetry.source]]
name = "pypi"
url = "https://pypi.org/simple/"
priority = "primary"

[[tool.poetry.source]]
name = "private"
url = "https://private.pypi.org/simple/"
priority = "supplemental"

Advanced: 복잡한 의존성 관리

그룹 의존성

# pyproject.toml
[tool.poetry.group.dev.dependencies]
pytest = "^7.4"
black = "^23.0"
mypy = "^1.5"

[tool.poetry.group.docs.dependencies]
sphinx = "^7.2"
sphinx-rtd-theme = "^1.3"

[tool.poetry.group.test.dependencies]
pytest-cov = "^4.1"
factory-boy = "^3.3"

플랫폼별 의존성

# pyproject.toml
[tool.poetry.dependencies]
pywin32 = {version = "^306", markers = "sys_platform == 'win32'"}
uvloop = {version = "^0.17", markers = "sys_platform != 'win32'"}

Python 버전별 의존성

# pyproject.toml
[tool.poetry.dependencies]
importlib-metadata = {version = "^6.0", python = "<3.8"}
typing-extensions = {version = "^4.5", python = "<3.11"}

Troubleshooting Checklist

# 1. 캐시 정리
$ poetry cache clear --all .

# 2. 가상 환경 재생성
$ poetry env remove python3.11
$ poetry install

# 3. 의존성 그래프 확인
$ poetry show --tree --depth 3

# 4. 특정 패키지 의존성 확인
$ poetry show --why 

# 5. lock 파일 검증
$ poetry check

# 6. verbose 모드로 실행
$ poetry add -vvv

Lessons Learned

버전 제약 유연하게: 정확한 버전 고정 대신 ^ 연산자를 사용하여 패치 업데이트를 허용하세요.
Lock 파일 관리: poetry.lock은 버전 관리 시스템에 커밋하여 팀원 간 일관된 환경을 보장하세요.
의존성 그래프 이해: 복잡한 프로젝트에서는 의존성 트리를 정기적으로 확인하여 충돌을 예방하세요.
그룹 의존성 활용: 개발, 테스트, 문서화 등 목적에 따라 의존성을 그룹화하면 환경 관리가 쉬워집니다.
에러 메시지 읽기: Poetry의 에러 메시지는 의존성 그래프 경로를 보여주므로, 이를 따라가면 충돌 원인을 파악할 수 있습니다.

This blog does not accept any external sponsorships, affiliate marketing, or ad revenue.