liminfoPoetry 레퍼런스
Python Poetry 패키지 매니저 명령어 및 설정 가이드
Poetry 레퍼런스 소개
Poetry 명령어 레퍼런스는 Python 프로젝트 관리를 위한 모든 핵심 Poetry 명령어를 체계적으로 정리한 빠른 참조 가이드입니다. Poetry는 pyproject.toml을 단일 설정 파일로 사용하여 pip, virtualenv, setup.py의 분산된 워크플로를 통합하는 현대적인 의존성 관리 및 패키징 도구입니다. 이 레퍼런스는 프로젝트 초기화, 의존성 관리(add, remove, update, lock), 빌드 및 게시 워크플로, 설정, 가상환경 관리 등 6개의 주요 카테고리를 다룹니다.
Python 개발자, 데이터 과학자, DevOps 엔지니어들이 일상적인 개발, CI/CD 파이프라인, 라이브러리 게시 작업에서 이 레퍼런스를 활용합니다. `poetry new`로 새 프로젝트를 생성하거나, `poetry lock`으로 의존성을 고정하거나, `poetry publish`로 PyPI에 패키지를 게시하거나, `poetry env use`로 Python 버전을 전환할 때 필요한 정확한 구문과 실제 예제를 제공합니다.
레퍼런스는 Python 개발의 자연스러운 워크플로에 맞춰 프로젝트, 의존성, 빌드, 게시, 설정, 가상환경 6개 카테고리로 구성되어 있습니다. 각 항목에는 전체 명령어 구문, 간결한 설명, 실제 상황에서의 실행 예제가 포함됩니다. `--group dev` 의존성 그룹, lock 파일 관리, `poetry.toml` 로컬 설정 형식 등 Poetry 1.x 및 2.x 규칙을 모두 다룹니다.
주요 기능
- Poetry 프로젝트 명령어 완벽 커버: new, init, check, list, self update
- 의존성 생명주기 명령어: add, remove, install, update, lock, show (--tree, --outdated 포함)
- 의존성 그룹 지원: --group dev로 pytest, black, mypy 등 개발 도구 분리 관리
- 빌드 및 게시 워크플로: poetry build (sdist + wheel), poetry version (semver 버전 bump), poetry publish
- 비공개 저장소 설정: repositories, pypi-token, publish --repository
- 가상환경 관리: env use, env info, env list, env remove, poetry shell
- 설정 명령어: poetry config --list, virtualenvs.in-project, 로컬 poetry.toml
- 모든 명령어에 실제 프로젝트 구조와 출력을 보여주는 실행 가능한 예제 수록
자주 묻는 질문
Poetry란 무엇이고 pip 대신 왜 사용해야 하나요?
Poetry는 pip의 여러 한계를 해결하는 Python 의존성 관리 및 패키징 도구입니다. pyproject.toml로 런타임 및 개발 의존성을 선언하고, 격리된 가상환경을 자동으로 생성 및 관리하며, poetry.lock으로 재현 가능한 설치를 보장하고, PyPI 패키지 빌드 및 게시를 하나의 도구로 처리합니다.
poetry install과 poetry update의 차이는 무엇인가요?
`poetry install`은 poetry.lock에 기록된 정확한 버전을 설치하여 재현 가능한 빌드를 보장합니다. `poetry update`는 pyproject.toml 조건을 만족하는 최신 버전을 새로 해결하고 poetry.lock을 갱신합니다. CI/CD와 프로덕션에서는 install을, 의존성을 의도적으로 업그레이드할 때는 update를 사용하세요.
Poetry에서 개발 전용 의존성을 추가하는 방법은?
`poetry add --group dev 패키지명`을 사용합니다. 예: `poetry add --group dev pytest black mypy`. 이렇게 하면 pyproject.toml의 [tool.poetry.group.dev.dependencies] 섹션에 추가되며, `poetry install --without dev`로 설치 시 제외됩니다.
poetry lock --no-update는 무엇을 하나요?
`poetry lock --no-update`는 기존 패키지 버전을 업그레이드하지 않고 poetry.lock 파일을 재생성합니다. pyproject.toml을 수정(새 의존성 추가 등)했지만 다른 모든 패키지의 기존 해결된 버전을 유지하고 싶을 때 유용합니다.
Poetry에서 특정 Python 버전을 사용하는 방법은?
`poetry env use python3.11` 또는 `poetry env use /usr/local/bin/python3.12`를 실행하면 지정한 Python 인터프리터로 가상환경이 생성됩니다. `poetry env list`로 연결된 모든 환경을 확인하고, `poetry env use`를 다시 실행하여 전환할 수 있습니다.
Poetry로 PyPI에 패키지를 게시하는 방법은?
먼저 `poetry build`로 패키지를 빌드(dist/*.whl 및 dist/*.tar.gz 생성)한 후 `poetry publish`를 실행합니다. PyPI API 토큰으로 인증해야 합니다: `poetry config pypi-token.pypi YOUR_TOKEN`. `poetry publish --build`로 빌드와 게시를 한 번에 처리할 수 있습니다.
virtualenvs.in-project true 설정의 의미는?
기본적으로 Poetry는 중앙 캐시 디렉토리(예: ~/.cache/pypoetry/virtualenvs/)에 가상환경을 생성합니다. `poetry config virtualenvs.in-project true`를 설정하면 프로젝트 루트에 .venv 디렉토리가 생성되어, VS Code처럼 워크스페이스에서 .venv를 자동 감지하는 에디터와 잘 연동됩니다.
Poetry 가상환경 안에서 테스트나 스크립트를 실행하는 방법은?
`poetry run 명령어`를 사용하면 가상환경을 활성화하지 않고도 그 안에서 명령을 실행할 수 있습니다. 예: `poetry run pytest`, `poetry run python main.py`, `poetry run black .`. 또는 `poetry shell`로 가상환경이 활성화된 대화형 셸 세션을 시작할 수 있습니다.