Skip to content

Python Poetry: 현대적인 의존성 관리 및 패키징 가이드

Updated on

Python 의존성 관리가 고통스러울 필요는 없습니다. 하지만 모든 Python 개발자가 이런 상황을 겪어본 적이 있을 겁니다. 프로젝트를 clone한 뒤 pip install -r requirements.txt를 실행하면, 의존성 충돌이 터미널에 연쇄적으로 쏟아집니다. 패키지 A는 어떤 라이브러리의 1.x 버전을 필요로 하고, 패키지 B는 2.x 버전을 필요로 하며, pip은 마지막에 해결된 쪽을 설치합니다 — 그리고 조용히 둘 중 하나를 망가뜨립니다. 이후 몇 시간의 디버깅이 이어지는데, 그 원인은 pip에 제대로 된 의존성 해결(resolver)과 lock 파일 메커니즘이 부족하기 때문입니다.

이 문제는 팀 환경에서 더 심해집니다. 한 개발자는 정확한 버전을 고정(pin)하고, 다른 개발자는 느슨한 범위를 쓰며, 또 다른 개발자는 새 패키지를 설치하고도 requirements.txt 업데이트를 잊어버립니다. 배포는 실패하고, 로컬에서는 통과한 테스트가 CI에서는 깨집니다. 근본 원인은 언제나 같습니다. Python의 기본 도구 체계가 의존성 관리를 부차적인 일로 취급한다는 점입니다.

Poetry는 의존성 해결, 가상 환경 관리, 패키지 배포를 하나의 도구로 제공해 이 문제를 해결합니다. 표준화된 pyproject.toml 파일을 사용하고, 결정론적(lock) 파일을 생성하며, 설치 “후”가 아니라 설치 “전”에 의존성 충돌을 해결합니다. 이 가이드는 설치부터 배포까지, 각 워크플로우별 실용적인 예제와 함께 전부 다룹니다.

📚

Python Poetry란?

Poetry는 Python을 위한 오픈소스 의존성 관리 및 패키징 도구입니다. 2018년 Sebastien Eustace가 만들었으며, 여러 도구로 흩어져 있던 Python 패키징 생태계를 하나의 일관된 도구로 통합해 다음 기능을 제공합니다.

  • 의존성 해결(Dependency resolution): Poetry는 어떤 것도 설치하기 전에, 모든 의존성과 그 하위 의존성(transitive dependencies)을 분석해 호환 가능한 버전 조합을 찾습니다.
  • Lock 파일: poetry.lock 파일에 설치된 모든 패키지의 정확한 버전을 기록해, 머신이 달라도 동일한 빌드를 재현할 수 있게 합니다.
  • 가상 환경 관리: 프로젝트별로 격리된 가상 환경을 자동으로 생성하고 관리합니다.
  • 패키지 빌드 및 배포: 소스 배포본과 wheel을 빌드하고, PyPI 또는 사설 저장소로 직접 배포합니다.
  • 프로젝트 스캐폴딩: 올바른 pyproject.toml 설정과 함께 프로젝트 구조를 생성합니다.

Poetry는 PEP 518 및 PEP 621 표준을 따르는 pyproject.toml을 설정 파일로 사용합니다. 이는 전통적인 Python 프로젝트에서 필요했던 setup.py, setup.cfg, requirements.txt, MANIFEST.in 조합을 대체합니다.

Poetry 설치하기

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 | py -

설치 후 Poetry를 PATH에 추가하세요. 설치 프로그램이 정확한 경로를 출력하며 — 보통 Linux/macOS에서는 $HOME/.local/bin, Windows에서는 %APPDATA%\Python\Scripts입니다.

설치 확인:

poetry --version

pipx로 설치하기

pipx(역시 CLI 도구를 격리해주는 도구)를 선호한다면:

pipx install poetry

Poetry 업데이트

poetry self update

특정 버전으로 업데이트:

poetry self update 1.8.0

탭 자동완성 활성화

Poetry는 Bash, Zsh, Fish 자동완성을 지원합니다.

# Bash
poetry completions bash >> ~/.bash_completion
 
# Zsh
poetry completions zsh > ~/.zfunc/_poetry
 
# Fish
poetry completions fish > ~/.config/fish/completions/poetry.fish

새 프로젝트 만들기

Poetry는 프로젝트를 시작하는 방법을 두 가지로 제공합니다. 완전히 새로 만들거나, 기존 프로젝트에 Poetry를 초기화할 수 있습니다.

완전히 새 프로젝트 생성

poetry new my-project

다음 구조가 생성됩니다.

my-project/
├── pyproject.toml
├── README.md
├── my_project/
│   └── __init__.py
└── tests/
    └── __init__.py

루트에 패키지를 두는(flat) 소스 레이아웃이 아니라, src/ 레이아웃을 사용하려면:

poetry new --src my-project

패키지가 src/ 디렉터리 안에 생성됩니다.

my-project/
├── pyproject.toml
├── README.md
├── src/
│   └── my_project/
│       └── __init__.py
└── tests/
    └── __init__.py

기존 프로젝트에서 초기화

기존 프로젝트 디렉터리로 이동 후 실행:

cd existing-project
poetry init

Poetry가 대화형 설정을 진행하며, 패키지 이름, 버전, 설명, 작성자, Python 버전 호환 범위, 의존성을 묻습니다. Enter로 기본값을 수락하거나 선택 필드는 건너뛸 수 있습니다.

비대화형 설정:

poetry init --name my-package --description "A useful package" --author "Your Name <you@example.com>" --python "^3.9" --no-interaction

pyproject.toml 이해하기

pyproject.toml은 프로젝트 설정의 단일 진실 공급원(single source of truth)입니다. 아래는 완전한 예시입니다.

[tool.poetry]
name = "my-project"
version = "1.0.0"
description = "A data processing library"
authors = ["Your Name <you@example.com>"]
license = "MIT"
readme = "README.md"
homepage = "https://github.com/yourname/my-project"
repository = "https://github.com/yourname/my-project"
keywords = ["data", "processing", "analytics"]
classifiers = [
    "Development Status :: 4 - Beta",
    "Intended Audience :: Developers",
    "Topic :: Software Development :: Libraries",
]
 
[tool.poetry.dependencies]
python = "^3.9"
pandas = "^2.0"
requests = "^2.31"
pydantic = ">=2.0,<3.0"
 
[tool.poetry.group.dev.dependencies]
pytest = "^8.0"
black = "^24.0"
mypy = "^1.0"
ruff = "^0.3"
 
[tool.poetry.group.docs.dependencies]
sphinx = "^7.0"
sphinx-rtd-theme = "^2.0"
 
[tool.poetry.scripts]
my-cli = "my_project.cli:main"
 
[build-system]
requires = ["poetry-core"]
build-backend = "poetry.core.masonry.api"

버전 제약(Version constraints) 문법

Poetry는 버전 제약을 명확한 문법으로 표현합니다.

ConstraintMeaningAllows
^2.0호환 릴리스>=2.0.0, <3.0.0
^2.1.3호환 릴리스(패치)>=2.1.3, <3.0.0
~2.1대략(Approximately)>=2.1.0, <2.2.0
>=2.0,<3.0범위(Range)명시적 상/하한
2.1.3정확히(Exact)2.1.3
>=2.0최소(Minimum)2.0 이상
*아무거나(Any)모든 버전

caret(^) 제약은 가장 일반적이며 권장됩니다. 시맨틱 버저닝 원칙에 따라 “0이 아닌 가장 왼쪽 자리”를 바꾸지 않는 업데이트를 허용합니다.

의존성 그룹(Dependency groups)

Poetry는 의존성을 그룹으로 정리해, 별도의 requirements 파일들을 대체합니다.

  • 메인 의존성 ([tool.poetry.dependencies]): 패키지가 동작하는 데 필요한 필수 의존성. 다른 사람이 패키지를 설치할 때 포함됩니다.
  • 개발 의존성 ([tool.poetry.group.dev.dependencies]): 개발/테스트/린팅 도구. 배포 패키지에는 포함되지 않습니다.
  • 커스텀 그룹 ([tool.poetry.group.docs.dependencies]): 문서 도구처럼 추가로 원하는 그룹을 구성할 수 있습니다.

의존성 추가 및 제거

패키지 추가

메인 의존성에 추가:

poetry add pandas

버전 제약과 함께 추가:

poetry add "pandas>=2.0,<3.0"

개발 그룹에 추가:

poetry add --group dev pytest black ruff

커스텀 그룹에 추가:

poetry add --group docs sphinx

Git 저장소에서 패키지 추가:

poetry add git+https://github.com/user/repo.git

특정 branch나 tag에서 추가:

poetry add git+https://github.com/user/repo.git#branch-name
poetry add git+https://github.com/user/repo.git#v1.0.0

로컬 경로 의존성 추가:

poetry add ../my-local-package

extras와 함께 추가:

poetry add "uvicorn[standard]"

패키지 제거

패키지 제거:

poetry remove pandas

특정 그룹에서 제거:

poetry remove --group dev black

설치된 패키지 목록 보기

전체 패키지 보기:

poetry show

특정 패키지 상세 보기:

poetry show pandas

의존성 트리 보기:

poetry show --tree

업데이트 가능한 패키지 보기:

poetry show --outdated

Lock 파일: poetry.lock

poetry.lock은 Poetry의 가장 중요한 기능 중 하나입니다. poetry install 또는 poetry add를 실행하면, Poetry는 모든 의존성을 해결하고(전이 의존성 포함) 정확한 버전을 poetry.lock에 기록합니다.

Lock 파일이 중요한 이유

lock 파일 없이 느슨한 버전 범위를 가진 pip install -r requirements.txt를 실행하면, 머신이나 시점에 따라 설치 결과가 달라질 수 있습니다. lock 파일은 이 “랜덤성”을 제거합니다.

예:

[tool.poetry.dependencies]
requests = "^2.28"

이는 2.28.0부터 2.99.x까지 허용합니다. lock 파일이 없다면, CI 서버는 2.31.0을 설치하고 로컬은 2.28.2를 쓰는 식의 차이가 생길 수 있습니다. lock 파일은 모든 환경에서 정확히 동일한 버전을 고정합니다.

Lock 파일 워크플로우

poetry.lock을 버전 관리에 커밋하세요. 이를 통해 모든 개발자/배포 환경에서 동일한 패키지 버전을 사용하게 됩니다.

git add poetry.lock pyproject.toml
git commit -m "Add project dependencies"

lock 파일로 설치(재현 가능한 설치):

poetry install

poetry.lock에 명시된 정확한 버전만 설치하며, 더 최신의 호환 버전이 있어도 무시합니다.

더 최신 버전이 필요할 때 lock 파일 업데이트:

# 모든 패키지 업데이트
poetry update
 
# 특정 패키지 업데이트
poetry update pandas
 
# 설치 없이 lock 파일만 업데이트
poetry lock

lock 파일 무결성 확인:

poetry lock --check

pyproject.toml과의 일관성을 확인하며 아무 것도 수정하지 않습니다.

가상 환경 관리

Poetry는 프로젝트별 가상 환경을 자동으로 생성/관리합니다.

기본 동작

poetry install 또는 poetry add를 실행할 때 가상 환경이 없으면 생성합니다. 기본적으로 가상 환경은 중앙 캐시 디렉터리에 저장됩니다.

  • Linux: ~/.cache/pypoetry/virtualenvs/
  • macOS: ~/Library/Caches/pypoetry/virtualenvs/
  • Windows: C:\Users\<user>\AppData\Local\pypoetry\Cache\virtualenvs\

프로젝트 내부 가상 환경

많은 개발자는 프로젝트 디렉터리 안에 가상 환경을 두는 방식(Node.js의 node_modules처럼)을 선호합니다. 전역 설정:

poetry config virtualenvs.in-project true

프로젝트 루트에 .venv 디렉터리가 생성되어 IDE 자동 감지에도 유리합니다.

가상 환경에서 명령 실행

단일 명령 실행:

poetry run python my_script.py
poetry run pytest
poetry run black .

환경 쉘 활성화:

poetry shell

가상 환경이 활성화된 새 쉘을 실행합니다. exit 또는 Ctrl+D로 종료합니다.

환경 정보

환경 상세 정보:

poetry env info

프로젝트에 연결된 모든 환경 목록:

poetry env list

특정 Python 버전 사용:

poetry env use python3.11

환경 제거:

poetry env remove python3.11

의존성 설치

표준 설치

모든 의존성(메인 + 개발) 설치:

poetry install

프로덕션 설치

개발 의존성 제외:

poetry install --without dev

특정 그룹들 제외:

poetry install --without dev,docs

특정 그룹만 설치

poetry install --only main
poetry install --only dev

환경 동기화

lock 파일에 없는 패키지를 제거(클린 설치):

poetry install --sync

수동 설치되었거나 더 이상 lock 파일에 없는 패키지를 제거해, 환경을 프로젝트 설정과 정확히 일치시킵니다.

패키지 빌드 및 배포

Poetry는 패키지 배포 워크플로우 전체를 단순화합니다.

패키지 빌드

poetry build

dist/ 디렉터리에 소스 배포본(.tar.gz)과 wheel(.whl)을 모두 생성합니다.

dist/
├── my_project-1.0.0.tar.gz
└── my_project-1.0.0-py3-none-any.whl

PyPI에 배포

먼저 PyPI 자격 증명을 설정합니다.

poetry config pypi-token.pypi your-api-token

배포:

poetry publish --build

--build는 빌드와 배포를 한 번에 수행합니다.

사설 저장소에 배포

사설 저장소 추가:

poetry config repositories.private https://private.pypi.example.com/simple/
poetry config http-basic.private username password

배포:

poetry publish --repository private

버전 관리

시맨틱 버저닝 규칙으로 버전 증가:

poetry version patch    # 1.0.0 -> 1.0.1
poetry version minor    # 1.0.0 -> 1.1.0
poetry version major    # 1.0.0 -> 2.0.0
poetry version prepatch # 1.0.0 -> 1.0.1a0

현재 버전 표시:

poetry version

requirements.txt에서 마이그레이션

기존에 requirements.txt를 사용하는 프로젝트라면 Poetry로의 마이그레이션은 어렵지 않습니다.

1단계: Poetry 초기화

cd your-project
poetry init --no-interaction

2단계: requirements.txt에서 의존성 추가

단순한 requirements 파일이라면:

cat requirements.txt | xargs poetry add

버전 제약이 포함된 파일의 경우, 수동으로 추가하거나 마이그레이션 스크립트를 사용할 수 있습니다.

import subprocess
 
with open("requirements.txt") as f:
    packages = []
    for line in f:
        line = line.strip()
        if line and not line.startswith("#") and not line.startswith("-"):
            packages.append(line)
 
if packages:
    subprocess.run(["poetry", "add"] + packages)

3단계: 개발 의존성 추가

requirements-dev.txt가 있다면:

cat requirements-dev.txt | xargs poetry add --group dev

4단계: 검증 및 lock

poetry install
poetry lock --check

5단계: 정리

정상 동작이 확인되면, 기존 파일들을 제거할 수 있습니다.

rm requirements.txt requirements-dev.txt setup.py setup.cfg

requirements.txt로 다시 export하기

호환성(Docker 빌드, 레거시 CI 등) 때문에 requirements.txt가 필요하다면:

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

개발 의존성 포함:

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

Poetry vs pip vs pipenv vs uv: 비교

적절한 의존성 관리 도구 선택은 프로젝트 요구사항에 따라 달라집니다. 아래는 상세 비교입니다.

FeaturePoetrypippipenvuv
Dependency resolution고급 SAT solver기본(2020년 이후 백트래킹)중간고급, Rust 기반
Lock fileYes (poetry.lock)No (수동 pip freeze)Yes (Pipfile.lock)Yes (uv.lock)
Virtual env management자동수동 (python -m venv)자동자동
Build and publish내장setuptools/twine 필요No내장
Config filepyproject.tomlrequirements.txtPipfilepyproject.toml
Speed보통빠름(해결 과정 최소)느림매우 빠름(Rust)
Python version managementNo (pyenv 사용)NoNoYes (내장)
Monorepo support제한적N/ANoYes
Script runnerspoetry runNopipenv runuv run
Maturity안정적(2018)사실상 표준안정적(2017)비교적 신생(2024)
PEP compliancePEP 518, 621N/A독자 포맷PEP 518, 621
Community매우 큼중간빠르게 성장
Best for풀 라이프사이클 패키징단순 스크립트, 레거시웹 애플리케이션속도 중심 워크플로우

각 도구를 선택해야 할 때

Poetry를 선택해야 하는 경우: 의존성 관리, 빌드, PyPI 배포까지 하나의 도구로 처리하는 완성형 패키징 솔루션이 필요하고, 성숙한 생태계와 문서를 원할 때.

pip을 선택해야 하는 경우: 단순 스크립트, 빠른 프로토타이핑, 또는 표준 라이브러리 기반 도구만 써야 하는 제약이 있을 때. pip은 다른 도구들이 기반으로 삼는 핵심입니다.

pipenv를 선택해야 하는 경우: 재현 가능한 환경이 필요하지만 PyPI에 패키지를 배포하지 않는 웹 애플리케이션 중심 프로젝트. Pipfile 포맷은 개발/프로덕션 의존성을 명확히 분리합니다.

uv를 선택해야 하는 경우: 설치 속도가 최우선이거나, Python 버전 관리까지 포함한 단일 도구를 원할 때. uv는 Rust로 작성되어 Poetry 같은 Python 기반 도구보다 훨씬 빠르게 의존성을 해결합니다. pip 호환이며 drop-in replacement로도 사용할 수 있습니다.

Poetry 설정 및 팁

유용한 설정 옵션

# 가상 환경을 프로젝트 디렉터리에 저장
poetry config virtualenvs.in-project true
 
# 새 환경에서 특정 Python 버전을 우선 사용
poetry config virtualenvs.prefer-active-python true
 
# 가상 환경 자동 생성 비활성화
poetry config virtualenvs.create false
 
# 모든 설정 보기
poetry config --list

Docker에서 Poetry 사용하기

Poetry를 사용하는 프로덕션 Dockerfile 예시:

FROM python:3.12-slim
 
ENV POETRY_VERSION=1.8.0 \
    POETRY_HOME="/opt/poetry" \
    POETRY_VIRTUALENVS_CREATE=false \
    POETRY_NO_INTERACTION=1
 
RUN pip install poetry==$POETRY_VERSION
 
WORKDIR /app
 
COPY pyproject.toml poetry.lock ./
RUN poetry install --without dev --no-root
 
COPY . .
RUN poetry install --without dev
 
CMD ["python", "-m", "my_project"]

핵심 포인트:

  • POETRY_VIRTUALENVS_CREATE=false는 컨테이너 내부에서 가상 환경 생성을 건너뜁니다(컨테이너 자체가 격리 환경이기 때문).
  • 소스 코드를 복사하기 전에 의존성을 설치해 Docker 레이어 캐시를 활용합니다.
  • poetry install을 두 번 실행합니다: 먼저 프로젝트 자체를 제외하고(의존성만), 이후 프로젝트를 포함해 설치합니다.

CI/CD에서 Poetry 사용하기

GitHub Actions 예시:

name: CI
 
on: [push, pull_request]
 
jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-python@v5
        with:
          python-version: "3.12"
      - name: Install Poetry
        run: pip install poetry
      - name: Install dependencies
        run: poetry install
      - name: Run tests
        run: poetry run pytest
      - name: Run linting
        run: poetry run ruff check .

Jupyter 워크플로우에서 Poetry 사용하기

데이터 사이언티스트는 Jupyter notebook에서 작업하는 경우가 많으며, 이때 의존성 관리는 특히 중요합니다. Poetry는 notebook이 올바른 환경을 사용하도록 보장해 Jupyter와 잘 결합됩니다.

Poetry 프로젝트에 Jupyter 설치:

poetry add --group dev jupyter ipykernel

Poetry 환경을 Jupyter 커널로 등록:

poetry run python -m ipykernel install --user --name=my-project

Poetry 환경에서 Jupyter 실행:

poetry run jupyter notebook

자동 의존성 관리 및 AI 기반 지원이 결합된 더 간결한 Jupyter 경험이 필요하다면, RunCell (opens in a new tab)은 환경 설정보다 분석에 집중할 수 있는 통합 환경을 제공합니다. RunCell은 패키지 설치와 커널 관리를 자동으로 처리해, 프로젝트 단위 의존성 제어를 제공하는 Poetry를 보완합니다.

자주 쓰는 Poetry 명령어 레퍼런스

CommandDescription
poetry new <name>새 프로젝트 생성
poetry init기존 디렉터리에 초기화
poetry add <pkg>의존성 추가
poetry remove <pkg>의존성 제거
poetry install모든 의존성 설치
poetry update의존성 업데이트
poetry locklock 파일만 업데이트
poetry show설치된 패키지 목록
poetry show --tree의존성 트리 표시
poetry show --outdated업데이트 가능한 패키지 표시
poetry build패키지 빌드
poetry publishPyPI에 배포
poetry run <cmd>가상 환경에서 명령 실행
poetry shell가상 환경 쉘 활성화
poetry env info환경 정보 표시
poetry version <rule>프로젝트 버전 증가
poetry exportrequirements.txt로 export
poetry config --list모든 설정 표시
poetry search <pkg>패키지 검색
poetry checkpyproject.toml 검증

자주 발생하는 문제 해결

의존성 해결 실패

문제: Poetry가 호환 가능한 버전 조합을 찾지 못합니다.

SolverProblemError: ...unable to find compatible versions...

해결: 버전 제약을 완화하거나 충돌하는 요구사항을 확인하세요.

# 어떤 충돌이 있는지 확인
poetry show --tree
 
# 더 넓은 제약으로 시도
poetry add "problematic-package>=1.0"

느린 해결 속도

문제: poetry lock이 너무 오래 걸립니다.

해결: Poetry는 패키지 메타데이터를 캐시하지만, 의존성이 많은 프로젝트에서 첫 해결은 느릴 수 있습니다. 몇 분 이상 걸린다면:

# 캐시를 지우고 재시도
poetry cache clear --all pypi
 
# verbose 출력으로 진행 상황 확인
poetry lock -vvv

IDE가 가상 환경을 감지하지 못함

문제: VS Code 또는 PyCharm이 Poetry 환경을 찾지 못합니다.

해결: 프로젝트 내부 가상 환경을 사용하도록 설정합니다.

poetry config virtualenvs.in-project true
poetry install  # 프로젝트 루트에 .venv 재생성

그 다음 IDE에서 인터프리터로 .venv/bin/python을 선택하세요.

Hash 불일치 오류

문제: poetry install에서 hash mismatch가 보고됩니다.

해결: lock 파일을 재생성하세요.

poetry lock --no-update

의존성 버전은 바꾸지 않고 hash만 다시 생성합니다.

FAQ

Python Poetry는 무엇에 사용되나요?

Python Poetry는 패키지 설치, 버전 충돌 해결, 가상 환경 관리, PyPI 배포까지 처리하는 의존성 관리 및 패키징 도구입니다. pyproject.toml 설정 파일을 중심으로 pip, venv, setuptools, twine 조합을 하나의 통합 도구로 대체합니다.

Poetry가 pip보다 더 좋은가요?

Poetry와 pip은 목적이 다릅니다. Poetry는 의존성 해결, lock 파일, 가상 환경 관리, 패키지 배포를 하나의 도구로 제공합니다. pip은 더 단순하며 간단한 설치에 잘 맞습니다. 재현 가능한 빌드, 팀 협업, 패키지 배포가 필요한 프로젝트에서는 Poetry가 큰 장점을 제공합니다. 빠른 스크립트나 단순 프로젝트에서는 pip만으로도 충분합니다.

pip에서 Poetry로 어떻게 전환하나요?

프로젝트에서 poetry init로 Poetry를 초기화한 뒤, cat requirements.txt | xargs poetry add로 requirements.txt의 의존성을 추가합니다. Poetry는 pyproject.toml과 poetry.lock 파일을 생성합니다. poetry install로 정상 동작을 확인한 뒤 기존 requirements.txt 파일을 제거할 수 있습니다. 호환성이 필요하다면 poetry export를 사용하세요.

Poetry가 virtualenv를 대체하나요?

네. Poetry는 프로젝트별 가상 환경을 자동으로 생성하고 관리합니다. 환경을 수동으로 만들거나 활성화할 필요가 없습니다. 기본적으로 중앙 캐시에 저장하며, poetry config virtualenvs.in-project true로 설정하면 프로젝트 디렉터리 안에 만들 수도 있습니다. 대화형으로 환경을 활성화하려면 poetry shell을 사용할 수 있습니다.

Poetry가 여러 Python 버전을 관리할 수 있나요?

Poetry 자체는 Python 버전을 설치하지 않지만, 시스템에 설치된 Python 버전들과 함께 동작합니다. 여러 Python 버전이 필요하다면 pyenv 또는 uv로 설치한 뒤, poetry env use python3.11처럼 Poetry에 사용할 버전을 지정하세요. Poetry는 같은 프로젝트에서도 Python 버전별로 별도의 가상 환경을 만듭니다.

poetry.lock과 requirements.txt의 차이는 무엇인가요?

poetry.lock 파일은 전이 의존성을 포함한 모든 설치 패키지와 정확한 버전을 기록하고, 검증을 위한 content hash도 포함합니다. pip freeze로 만든 requirements.txt도 정확한 버전을 나열하지만, hash 검증과 의존성 관계 추적이 부족합니다. lock 파일은 모든 환경에서 결정론적 설치를 보장하는 반면, requirements.txt는 전이 의존성이 업데이트될 때 결과가 달라질 수 있습니다.

결론

Python Poetry는 의존성 관리를 마찰의 원인에서 매끄러운 워크플로우로 바꿔줍니다. 의존성 해결, 가상 환경 관리, 패키지 배포를 하나의 도구로 통합함으로써, 오랫동안 Python 개발자들을 괴롭혀 온 파편화된 도구 체계를 제거합니다. pyproject.toml은 단일 진실 공급원을 제공하고, lock 파일은 재현 가능한 설치를 보장하며, 의존성 resolver는 런타임 실패를 일으키기 전에 충돌을 미리 잡아냅니다.

PyPI에 배포할 라이브러리를 만들든, 수십 개의 의존성을 가진 복잡한 애플리케이션을 운영하든, 일관된 환경이 필요한 팀 협업을 하든, Poetry는 pip만으로는 얻기 어려운 구조와 신뢰성을 제공합니다. 학습 곡선도 완만해 대부분의 개발자는 한 시간 내에 생산성을 확보할 수 있고, 의존성 디버깅에 절약되는 시간은 첫 주 안에 충분히 회수됩니다.

다음 프로젝트에서는 poetry new로 시작하거나 기존 프로젝트에서 poetry init을 실행해보세요. 의존성을 추가하고 lock 파일을 커밋한 뒤, “원래 이렇게 동작했어야 하는” 의존성 관리를 경험해 보시기 바랍니다. Jupyter 기반 데이터 사이언스 워크플로우라면, Poetry의 프로젝트 단위 의존성 제어와 RunCell (opens in a new tab)을 함께 사용해 패키지 관리와 인터랙티브 분석을 모두 매끄럽게 처리하는 환경을 구성할 수 있습니다.

📚