How to use Poetry

Python 개발의 강력한 도구 Poetry 활용법

---

Warning

이 포스팅의 원문은 테디노트입니다. 원문을 참조하세요.

---

1. Poetry란?

Poetry는 Python 프로젝트의 의존성 관리와 패키지 배포를 간소화하는 도구입니다. 기존의 pip와 virtualenv를 대체하며, 프로젝트 설정과 의존성을 선언적으로 관리할 수 있는 pyproject.toml 파일을 중심으로 작동한다.

주요 특징

• 의존성 잠금(poetry.lock)
  정확한 버전의 의존성을 기록해, 프로젝트를 다양한 환경에서 동일하게 재현 가능.
• 가상 환경 자동 관리
  프로젝트별로 독립된 가상 환경을 생성하고 관리.

---

2. Poetry와 기존 pip 방식의 차이점

특징	Poetry	기존 pip + virtualenv
의존성 관리	pyproject.toml에 선언적 관리, poetry.lock으로 잠금	수동으로 requirements.txt 작성 및 관리
가상 환경 관리	프로젝트별 가상 환경 자동 생성 및 관리	별도 가상 환경 생성 및 관리 필요
재현성 보장	poetry.lock을 통해 동일한 의존성 보장	requirements.txt에 기록된 버전만 보장, 충돌 가능성 있음
통합 관리	의존성 관리, 가상 환경 생성, 배포 기능 제공	개별 도구(pip, virtualenv, twine) 사용
편의성	선언적 관리로 간단, 명확	반복적이고 수동적인 작업 필요

Poetry는 의존성 관리와 재현성 보장에서 특히 강력하다. poetry.lock 파일은 의존성 트리의 정확한 버전을 기록하여, 동일한 환경에서 프로젝트를 재현할 수 있도록 보장한다. 반면, pip 방식은 충돌 가능성을 완전히 제거하기 어렵다.

---

3. Poetry 설치

Poetry는 Python 3.6 이상에서 사용할 수 있다.

설치 방법

Linux/macOS/Windows (WSL):

curl -sSL https://install.python-poetry.org | python3 -

Windows PowerShell:

(Invoke-WebRequest -Uri https://install.python-poetry.org -UseBasicParsing).Content | py -

설치 완료 후 환경 변수(PATH) 문제가 발생하면 아래의 해결 방법을 참고하자.

---

4. 환경 변수 오류 해결

Poetry 경로 확인

where poetry

경로 수동 설정

Windows:

1. 환경 변수 설정에서 Path에 Poetry 설치 경로 추가.
   • 기본 경로: %USEPROFILE%\AppData\Roaming\Python\Scripts\poetry.exe

macOS/Linux:

1. 쉘 설정 파일 수정:

   nano ~/.zshrc

2. 아래 내용을 추가:

   export PATH="$HOME/.local/bin:$PATH"

3. 적용:

   source ~/.zshrc

---

5. Poetry로 프로젝트 생성

기존 디렉토리 초기화

poetry init

새 프로젝트 생성

poetry new 프로젝트이름

예: poetry-demo 프로젝트 생성:

poetry new poetry-demo

생성된 프로젝트 구조

📦poetry-demo  
 ┣ 📂poetry_demo  
 ┣ 📂tests  
 ┣ 📜pyproject.toml  
 ┗ 📜README.md

---

6. 의존성 관리

패키지 추가

poetry add 패키지명

개발용 의존성 추가

poetry add --group dev

특정 버전 추가

poetry add <패키지명>@<버전>

패키지 삭제

poetry remove 패키지명

---

7. 가상 환경 관리

가상 환경 활성화

poetry shell

가상 환경 비활성화

deactivate

가상 환경 정보

poetry env info

---

8. 의존성 내보내기

Poetry를 사용해 requirements.txt 파일을 생성:

poetry export -f requirements.txt --output requirements.txt

옵션

• --without-hashes: 해시값 제외.
• --dev: 개발용 의존성 포함.

---

9. 프로젝트 빌드 및 배포

프로젝트 빌드

poetry build

PyPI에 배포

poetry publish

---

10. Poetry의 장점 요약

• 의존성 관리 간소화: 선언적으로 의존성을 관리하며, poetry.lock으로 재현성 보장.
• 가상 환경 통합: 프로젝트별 가상 환경을 자동 생성 및 관리.
• 배포 간소화: pyproject.toml을 통해 빌드 및 배포 작업 간소화.
• 강력한 재현성: 의존성 충돌을 방지하고 동일한 환경을 복제 가능.

단점으로는 일부 패키지 관리 툴과의 호환성 부족 문제와 초기 러닝 커브가 있다.