Python 개발에서 패키지 관리와 의존성 해결은 항상 중요한 과제였습니다. 기존의 pip와 requirements.txt 조합이나 setuptools는 복잡한 프로젝트에서 한계를 보였고, 이러한 문제를 해결하기 위해 Poetry가 등장했습니다. 이 글에서는 Poetry의 기본 개념부터 실제 사용법, 그리고 자주 발생하는 문제와 해결책까지 상세히 알아보겠습니다.
1. Poetry란 무엇인가?
Poetry는 Python 패키지의 의존성 관리와 패키징을 위한 도구로, 다음과 같은 특징을 가지고 있습니다:
- 의존성 해결: 패키지 간 호환성을 자동으로 확인하고 해결
- 격리된 환경: 프로젝트별 가상환경 자동 생성 및 관리
- 패키지 게시: PyPI 등에 쉽게 패키지 배포 가능
- 단일 설정 파일: pyproject.toml 하나로 모든 설정 관리
- 락 파일: poetry.lock 파일로 정확한 의존성 버전 보장
2. Poetry 설치 및 기본 설정
2.1 Poetry 설치하기
Poetry는 공식 설치 스크립트를 사용하여 설치하는 것이 권장됩니다:
# Linux, macOS, Windows (WSL)
curl -sSL https://install.python-poetry.org | python3 -
# Windows (PowerShell)
(Invoke-WebRequest -Uri https://install.python-poetry.org -UseBasicParsing).Content | python -
설치 후 PATH에 Poetry를 추가해야 합니다. 대부분 자동으로 추가되지만, 필요한 경우 다음 경로를 PATH에 추가하세요:
- Linux/macOS: $HOME/.local/bin
- Windows: %APPDATA%\Python\Scripts
2.2 기본 설정
Poetry의 설정은 다음 명령어로 확인하고 변경할 수 있습니다:
# 현재 설정 확인
poetry config --list
# 가상환경을 프로젝트 내부에 생성하도록 설정
poetry config virtualenvs.in-project true
# 캐시 디렉토리 설정
poetry config cache-dir /path/to/cache
3. 프로젝트 관리
3.1 새 프로젝트 시작하기
# 새 프로젝트 생성
poetry new my-project
# 기존 프로젝트에 Poetry 추가
cd existing-project
poetry init
새 프로젝트를 생성하면 다음과 같은 구조가 만들어집니다:
my-project/
├── pyproject.toml
├── README.md
├── my_project/
│ └── __init__.py
└── tests/
└── __init__.py
3.2 pyproject.toml 파일 이해하기
pyproject.toml은 프로젝트의 모든 메타데이터와 의존성을 관리하는 핵심 파일입니다:
[tool.poetry]
name = "my-project"
version = "0.1.0"
description = "My awesome project"
authors = ["Your Name <your.email@example.com>"]
readme = "README.md"
[tool.poetry.dependencies]
python = "^3.8" requests = "^2.28.1"
[tool.poetry.group.dev.dependencies]
pytest = "^7.0.0"
[build-system]
requires = ["poetry-core"]
build-backend = "poetry.core.masonry.api"
3.3 의존성 관리
# 패키지 추가 poetry add requests # 개발용 의존성 추가 poetry add pytest --group dev # 특정 버전 지정 poetry add django@^4.0.0 # 의존성 제거 poetry remove requests # 모든 의존성 업데이트 poetry update # 특정 패키지만 업데이트 poetry update requests
4. 가상환경 관리
4.1 가상환경 생성 및 활성화
Poetry는 프로젝트별로 자동으로 가상환경을 생성하고 관리합니다:
# 가상환경 정보 확인 poetry env info # 가상환경 목록 확인 poetry env list # 가상환경 활성화 poetry shell # 가상환경 재생성 poetry env remove python poetry env use python3.9
4.2 Poetry 없이 가상환경 활성화하기
Poetry 쉘을 사용하지 않고 직접 가상환경을 활성화할 수도 있습니다:
# Linux/macOS
source $(poetry env info --path)/bin/activate
# Windows
& ((poetry env info --path) + "\Scripts\activate.ps1")
5. 스크립트 실행 및 패키지 배포
5.1 스크립트 실행
Poetry를 사용하면 가상환경을 활성화하지 않고도 스크립트를 실행할 수 있습니다:
# Python 스크립트 실행
poetry run python my_script.py
# 설치된 패키지 명령어 실행
poetry run pytest
# 사용자 정의 스크립트 실행 (pyproject.toml에 정의)
poetry run start-app
5.2 사용자 정의 스크립트
pyproject.toml에 사용자 정의 스크립트를 추가할 수 있습니다:
[tool.poetry.scripts]
start-app = "my_project.main:main"
5.3 패키지 빌드 및 배포
# 패키지 빌드 poetry build # PyPI에 배포 poetry publish # 빌드 후 배포 poetry publish --build
6. 자주 발생하는 문제와 해결 방법
6.1 의존성 해결 충돌
의존성 충돌이 발생하면 다음과 같은 오류 메시지가 표시됩니다:
The current project's Python requirement (>=3.8,<3.9) is not compatible with some of the required packages Python requirement:
- package-name requires Python >=3.9, so it will not be satisfied for Python >=3.8,<3.9
해결 방법:
- Python 버전 요구사항 조정:
poetry add package-name --python ">=3.9" - 호환되는 패키지 버전 찾기:
poetry add package-name@^1.0.0
6.2 락 파일 충돌
여러 개발자가 동시에 작업할 때 poetry.lock 파일 충돌이 발생할 수 있습니다.
해결 방법:
- 최신 변경사항 병합 후:
poetry lock --no-update - 의존성 다시 계산:
poetry lock
6.3 설치 오류
패키지 설치 중 오류가 발생하는 경우:
# 캐시 초기화
poetry cache clear --all pypi
# 디버그 모드로 설치
poetry install -v
6.4 가상환경 문제
가상환경이 제대로 작동하지 않는 경우:
# 가상환경 재생성 poetry env remove python poetry env use python # 의존성 다시 설치 poetry install --sync
7. Poetry vs 다른 도구들
Poetry와 다른 Python 패키지 관리 도구들의 비교:
- pip + requirements.txt: 간단하지만 의존성 해결이 부족하고 개발/배포 환경 분리가 어려움
- pipenv: Poetry와 유사하지만 업데이트가 느리고 일부 기능이 제한적
- conda: 과학 계산용 패키지에 강점이 있지만 일반적인 Python 개발에는 다소 무거움
- Poetry: 현대적인 워크플로우, 의존성 해결, 패키징, 가상환경 관리를 모두 통합
8. 결론
Poetry는 Python 패키지 및 의존성 관리를 위한 강력하고 현대적인 도구입니다. 단일 설정 파일, 정확한 의존성 해결, 통합된 가상환경 관리 등의 기능은 개발자의 생산성을 크게 향상시킵니다. 특히 팀 프로젝트나 배포가 필요한 패키지 개발에서 그 효용성을 더욱 느낄수 있습니다.
Poetry를 사용하면 “이 코드는 내 컴퓨터에서는 작동해요”라는 문제에서 벗어나, 모든 환경에서 일관된 개발 경험을 제공할 수 있습니다. Python 개발을 더 효율적이고 즐겁게 만들어주는 Poetry를 다음 프로젝트에서 적용해보세요!
답글 남기기