Poetry Python 의존성 관리 완벽 가이드

Python 프로젝트의 의존성을 효율적으로 관리하는 Poetry 도구에 대해 알아봅니다. 패키지 설치부터 가상환경 관리, 배포까지 Poetry의 핵심 기능을 단계별로 학습합니다.

---

---

들어가며

이 글에서는 Poetry Python 의존성 관리 완벽 가이드에 대해 상세히 알아보겠습니다. 총 12가지 주요 개념을 다루며, 각각의 개념에 대한 설명과 실제 코드 예제를 함께 제공합니다.

목차

1. Poetry_프로젝트_초기화
2. 패키지_설치하기
3. 의존성_파일_구조
4. 가상환경_관리
5. 패키지_제거하기
6. 의존성_설치_및_동기화
7. 의존성_업데이트
8. 설치된_패키지_조회
9. 버전_범위_지정하기
10. 스크립트_실행하기
11. 패키지_빌드_및_배포
12. 가상환경_설정_관리

---

1. Poetry 프로젝트 초기화

개요

Poetry로 새로운 Python 프로젝트를 시작합니다. pyproject.toml 파일이 자동으로 생성되어 프로젝트 설정을 관리합니다.

코드 예제

# 터미널에서 실행
poetry new my-project

# 기존 프로젝트에 Poetry 추가
poetry init

설명

poetry new는 새 프로젝트 구조를 생성하고, poetry init은 대화형으로 기존 프로젝트에 Poetry를 설정합니다.

---

2. 패키지 설치하기

개요

Poetry로 프로젝트에 필요한 패키지를 설치합니다. pyproject.toml과 poetry.lock 파일에 자동으로 기록됩니다.

코드 예제

# 패키지 설치
poetry add requests

# 개발 의존성 설치
poetry add --group dev pytest

# 특정 버전 설치
poetry add "numpy>=1.20,<2.0"

설명

add 명령어로 패키지를 설치하면 의존성이 자동으로 해결되고, --group dev로 개발용 패키지를 구분할 수 있습니다.

---

3. 의존성 파일 구조

개요

pyproject.toml 파일은 프로젝트의 모든 의존성과 설정을 관리합니다. 사람이 읽기 쉬운 TOML 형식을 사용합니다.

코드 예제

[tool.poetry]
name = "my-project"
version = "0.1.0"

[tool.poetry.dependencies]
python = "^3.9"
requests = "^2.28.0"

[tool.poetry.group.dev.dependencies]
pytest = "^7.0"

설명

dependencies에는 실행에 필요한 패키지를, dev.dependencies에는 개발에만 필요한 패키지를 명시합니다.

---

4. 가상환경 관리

개요

Poetry는 프로젝트마다 독립된 가상환경을 자동으로 생성하고 관리합니다.

코드 예제

# 가상환경 활성화
poetry shell

# 가상환경에서 명령 실행
poetry run python main.py

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

설명

poetry shell로 가상환경에 진입하거나, poetry run으로 일회성 명령을 실행할 수 있습니다.

---

5. 패키지 제거하기

개요

더 이상 필요 없는 패키지를 프로젝트에서 안전하게 제거합니다.

코드 예제

# 패키지 제거
poetry remove requests

# 개발 의존성 제거
poetry remove --group dev pytest

설명

remove 명령어는 패키지를 제거하고 pyproject.toml과 poetry.lock을 자동으로 업데이트합니다.

---

6. 의존성 설치 및 동기화

개요

poetry.lock 파일을 기반으로 정확한 버전의 패키지들을 설치합니다. 팀원 간 동일한 환경을 보장합니다.

코드 예제

# 모든 의존성 설치
poetry install

# 개발 의존성 제외하고 설치
poetry install --without dev

# 의존성만 설치 (프로젝트 코드 제외)
poetry install --no-root

설명

poetry install은 poetry.lock의 정확한 버전을 설치하여 모든 환경에서 동일한 의존성을 보장합니다.

---

7. 의존성 업데이트

개요

설치된 패키지들을 최신 버전으로 업데이트합니다. pyproject.toml의 버전 제약을 따릅니다.

코드 예제

# 모든 의존성 업데이트
poetry update

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

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

설명

update는 버전 제약 내에서 최신 버전으로 업데이트하고, --outdated로 업데이트 가능한 패키지를 미리 확인할 수 있습니다.

---

8. 설치된 패키지 조회

개요

프로젝트에 설치된 모든 패키지와 의존성 트리를 확인합니다.

코드 예제

# 모든 패키지 목록
poetry show

# 특정 패키지 상세 정보
poetry show requests

# 의존성 트리 보기
poetry show --tree

설명

show 명령어로 설치된 패키지를 확인하고, --tree 옵션으로 의존성 관계를 트리 구조로 볼 수 있습니다.

---

9. 버전 범위 지정하기

개요

패키지 버전을 유연하게 지정하여 호환성을 유지합니다. 캐럿(^)과 틸드(~) 기호를 사용합니다.

코드 예제

# 캐럿: 메이저 버전 고정
poetry add "requests^2.28.0"  # 2.28.0 ~ 3.0.0 미만

# 틸드: 마이너 버전 고정
poetry add "numpy~1.20.0"  # 1.20.0 ~ 1.21.0 미만

# 정확한 버전
poetry add "django==4.2.0"

설명

^는 호환 가능한 최신 버전을, ~는 더 엄격한 버전 범위를 지정합니다. ==로 정확한 버전을 고정할 수 있습니다.

---

10. 스크립트 실행하기

개요

pyproject.toml에 자주 사용하는 명령어를 스크립트로 등록하여 간편하게 실행합니다.

코드 예제

# pyproject.toml에 추가
[tool.poetry.scripts]
start = "my_project.main:run"
test = "pytest tests/"

# 터미널에서 실행
poetry run start
poetry run test

설명

scripts 섹션에 명령어를 등록하면 poetry run으로 간단히 실행할 수 있어 개발 생산성이 향상됩니다.

---

11. 패키지 빌드 및 배포

개요

프로젝트를 패키지로 빌드하여 PyPI에 배포할 수 있습니다.

코드 예제

# 패키지 빌드 (wheel, tar.gz 생성)
poetry build

# PyPI에 배포
poetry publish

# 빌드와 배포 동시 실행
poetry publish --build

설명

build로 배포 가능한 패키지를 생성하고, publish로 PyPI에 업로드하여 다른 사람들이 pip install로 설치할 수 있게 합니다.

---

12. 가상환경 설정 관리

개요

Poetry의 가상환경 생성 위치와 동작을 설정으로 제어할 수 있습니다.

코드 예제

# 프로젝트 내 .venv 폴더에 생성
poetry config virtualenvs.in-project true

# 가상환경 삭제
poetry env remove python

# 설정 확인
poetry config --list

설명

virtualenvs.in-project를 true로 설정하면 프로젝트 폴더 내에 .venv가 생성되어 관리가 편리합니다.

---

마치며

이번 글에서는 Poetry Python 의존성 관리 완벽 가이드에 대해 알아보았습니다. 총 12가지 개념을 다루었으며, 각각의 사용법과 예제를 살펴보았습니다.

관련 태그

#Python #Poetry #DependencyManagement #VirtualEnv #PackageManager