1 의존성 관리 개요

Poetry의 의존성 관리는 pyproject.toml에 직접 필요한 패키지만 선언하고, 하위 의존성은 Poetry가 자동으로 해결하는 방식이다.

pyproject.toml    ← 직접 의존성 선언 (사람이 관리)
       ↓
poetry.lock       ← 전체 의존성 트리 + 정확한 버전 (Poetry가 자동 관리)
       ↓
.venv/            ← 실제 설치된 패키지 (poetry install로 생성)

2 패키지 추가: poetry add

# 기본 추가 (최신 호환 버전 설치)
poetry add requests

# 여러 패키지 한번에 추가
poetry add pandas numpy scikit-learn

# 특정 버전 지정
poetry add requests==2.31.0

# 버전 범위 지정
poetry add "requests>=2.28,<3.0"

# 최신 버전 강제 설치
poetry add requests@latest

poetry add 실행 시 일어나는 일:

pyproject.toml의 [tool.poetry.dependencies]에 패키지 추가
모든 의존성 간 호환성 검증 (dependency resolution)
poetry.lock 갱신
가상환경에 패키지 설치

3 패키지 제거: poetry remove

# 패키지 제거
poetry remove requests

# 개발용 패키지 제거
poetry remove --group dev pytest

poetry remove는 해당 패키지와 더 이상 필요 없는 하위 의존성도 함께 제거한다.

4 패키지 업데이트: poetry update

# 모든 패키지를 pyproject.toml 제약 범위 내에서 최신 버전으로 업데이트
poetry update

# 특정 패키지만 업데이트
poetry update requests pandas

# 업데이트 가능한 패키지 확인 (실제 업데이트하지 않음)
poetry update --dry-run

4.1 update vs install

명령어	동작	사용 시점
`poetry install`	`poetry.lock` 기준으로 설치	클론 후 환경 구성, CI/CD
`poetry update`	최신 호환 버전으로 lock 갱신 + 설치	의존성 업데이트

5 버전 제약 문법

Poetry에서 가장 중요한 부분이다. 버전을 어떻게 지정하느냐에 따라 설치되는 버전이 달라진다.

5.1 Caret (^) - 기본값, 가장 많이 사용

주 버전(Major)을 고정하고, 나머지는 업데이트를 허용한다.

pandas = "^2.0.0"    # >=2.0.0, <3.0.0
numpy = "^1.24"      # >=1.24.0, <2.0.0

선언	허용 범위
`^2.0.0`	2.0.0 ~ 2.99.99
`^0.9.0`	0.9.0 ~ 0.9.99 (0.x에서는 마이너가 주 버전 역할)
`^0.0.3`	0.0.3 ~ 0.0.3 (0.0.x에서는 패치만 고정)

5.2 Tilde (~) - 보수적 업데이트

마이너 버전까지 고정하고, 패치 업데이트만 허용한다.

pandas = "~2.1.0"    # >=2.1.0, <2.2.0

5.3 정확한 버전 (==)

pandas = "==2.0.3"   # 2.0.3만 설치

5.4 범위 지정

pandas = ">=2.0,<3.0"
numpy = ">=1.20,!=1.24.0"  # 1.24.0은 제외

5.5 와일드카드 (*)

pandas = "2.*"       # 2.0.0 ~ 2.99.99
numpy = "*"          # 아무 버전

5.6 실무 권장

상황	권장 문법	이유
일반적인 경우	`^` (Caret)	안전하면서 버그 수정 반영
매우 신중할 때	`~` (Tilde)	패치만 허용
재현성 최우선	`==` (정확한 버전)	버전 고정
넓은 호환성 필요	`>=1.0,<3.0`	범위 명시

6 poetry.lock 파일

6.1 역할

poetry.lock은 실제로 설치된 모든 패키지의 정확한 버전을 기록한다.

pyproject.toml                poetry.lock
───────────────              ──────────────
pandas = "^2.0"     →       pandas==2.0.3
                             numpy==1.24.1
                             python-dateutil==2.8.2
                             pytz==2023.3
                             six==1.16.0

왼쪽은 직접 의존성 1개, 오른쪽은 그 하위 의존성까지 포함한 전체 트리다.

6.2 재현성 보장

# 팀원 A: 의존성 추가 후 lock 파일을 Git에 커밋
poetry add pandas
git add pyproject.toml poetry.lock
git commit -m "chore: Add pandas dependency"

# 팀원 B: 정확히 동일한 버전 설치
git pull
poetry install  # poetry.lock 기준으로 설치

poetry.lock은 반드시 Git에 커밋해야 한다

Lock 파일이 없으면 poetry install 시 pyproject.toml 기준으로 새로 resolve하므로, 팀원마다 다른 버전이 설치될 수 있다.

6.3 lock 파일 갱신

# lock 파일만 갱신 (설치 안 함)
poetry lock

# lock 갱신 없이 현재 lock 기준으로만 설치
poetry install --no-update

7 의존성 그룹 (Dependency Groups)

개발/테스트/문서 등 용도별로 의존성을 분리할 수 있다.

7.1 그룹 정의

# 필수 의존성 (항상 설치)
[tool.poetry.dependencies]
python = "^3.9"
pandas = "^2.0"
requests = "^2.28"

# 개발용 의존성
[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.dependencies]
mkdocs = "^1.5"
mkdocs-material = "^9.0"

7.2 그룹별 설치/제외

# 모든 그룹 포함하여 설치 (기본)
poetry install

# 특정 그룹 제외
poetry install --without dev,docs

# 특정 그룹만 포함
poetry install --with test

# 필수 의존성만 설치 (모든 그룹 제외)
poetry install --only main

7.3 그룹별 패키지 추가/제거

# dev 그룹에 추가
poetry add --group dev pytest black

# test 그룹에 추가
poetry add --group test pytest-cov

# 그룹에서 제거
poetry remove --group dev black

8 의존성 확인 명령어

# 설치된 패키지 목록
poetry show

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

# 특정 패키지의 상세 정보
poetry show pandas

# 업데이트 가능한 패키지 확인
poetry show --outdated

# 최상위(직접) 의존성만 확인
poetry show --top-level

8.1 poetry show –tree 출력 예시

pandas 2.0.3
├── numpy >=1.21.0
├── python-dateutil >=2.8.2
│   └── six >=1.5
└── pytz >=2020.1

이렇게 하면 어떤 패키지가 왜 설치되었는지 추적할 수 있다.

9 의존성 충돌 해결

9.1 충돌 발생 시

poetry add some-package
# SolverProblemError: ...
# Because package-a requires numpy>=1.24
# and package-b requires numpy<1.23,
# they are incompatible.

9.2 해결 방법

# 1. 충돌하는 패키지의 다른 버전 시도
poetry add "some-package@^1.0"

# 2. 충돌 원인 파악
poetry show --tree | grep numpy

# 3. 제약 조건을 직접 조정
# pyproject.toml에서 버전 범위 수정 후
poetry lock

10 요약

명령어	역할
`poetry add <pkg>`	패키지 추가
`poetry add --group dev <pkg>`	그룹별 추가
`poetry remove <pkg>`	패키지 제거
`poetry update`	최신 호환 버전으로 업데이트
`poetry install`	lock 기준 설치
`poetry show`	설치 목록 확인
`poetry show --tree`	의존성 트리
`poetry show --outdated`	업데이트 가능 목록
`poetry lock`	lock 파일 갱신