Poetry 설치 환경
2026년 11월 8일 공식 2.5 문서는 Poetry 자체 실행에 Python 3.10 이상을 요구합니다. 이 조건과 프로젝트가 지원할 Python 범위는 별도입니다. 문서 속 오래된 프로젝트 예시의 Python 버전을 현재 Poetry 최소 조건으로 옮기지 않습니다.
공식 설치 방법 중 pipx를 사용할 경우 pipx install poetry로 도구를 분리하고 poetry --version으로 확인합니다. 기존 프로젝트 가상환경에 관리 도구까지 섞어 넣기 전에 설치 방식을 선택합니다. 이 글에서는 설치를 실행하지 않았습니다.
새 프로젝트와 기존 프로젝트
새로 만들 때는 poetry new demo-notes, 이미 있는 폴더를 관리할 때는 그 위치에서 poetry init을 검토합니다. 기존 pyproject나 잠금 파일이 있다면 새 파일로 덮어쓰기 전에 현재 관리 도구부터 확인합니다.
프로젝트 폴더에서 pyproject.toml의 프로젝트 이름·지원 Python·의존성 범위를 읽습니다. 지원 범위를 적었다고 해당 Python 실행 파일이 PC에 자동으로 준비되는 것은 아닙니다. 실제 실행할 Python 선택은 가상환경 글에서 다룹니다.
추가·잠금·설치의 차이
| 명령 | 주로 하는 일 |
|---|---|
poetry add 패키지명 |
요구 조건 추가와 의존성 해석·설치 |
poetry lock |
잠금 파일 작성·갱신, 패키지 설치는 하지 않음 |
poetry install |
잠금 상태에 따른 프로젝트 환경 설치 |
poetry check |
pyproject 내용과 잠금 파일의 일관성 검사 |
현재 문서는 poetry lock이 기본적으로 기존에 잠긴 패키지를 모두 최신으로 올리지 않는다고 설명합니다. 전체 재해석을 하는 --regenerate와 구분하며, 구버전의 --no-update 명령을 필수 단계로 복제하지 않습니다.
잠금 파일이 있는 경우
공식 기본 사용법은 lock이 있으면 해당 버전으로 설치하고, 없으면 의존성을 해석해 lock을 만든다고 설명합니다. 애플리케이션 프로젝트에서는 팀과 CI가 같은 잠금 상태를 사용할 수 있도록 파일 변경을 함께 검토합니다.
자체 사례로 pyproject의 패키지 조건만 바꾸고 lock은 그대로 둔 상태를 생각해 보세요. 에디터에서 저장했다는 사실만으로 환경까지 갱신된 것은 아닙니다. poetry check 결과와 lock diff를 확인하고, 설치 뒤 poetry run으로 필요한 실행·검사를 확인합니다.
실행과 업데이트 판단
프로젝트 명령은 poetry run python --version처럼 해당 환경에서 실행합니다. poetry update는 버전 갱신 목적이므로 단순 재설치와 구분하고 변경된 의존성과 테스트 결과를 확인합니다. lock 파일이 있다고 OS·시스템 라이브러리 차이까지 모두 사라지는 것은 아닙니다.
공식 현재 명령과 자체 파일 상태 사례를 대조했습니다. 실제 Poetry 설치·패키지 내려받기·의존성 해석·환경 실행은 미실행입니다. 기존 프로젝트·잠금 파일·전역 Python도 변경하지 않았습니다.
목적별 가이드
| 하려는 일 | 가이드 |
|---|---|
| Python과 가상환경 경로 선택 | Poetry 환경 관리 |
| 다른 Python 관리 도구 확인 | uv |