Poetry에 대하여

wldbs._.·2025년 9월 5일

linux sw 스터디 실습 정리

SW

목록 보기

5/8

가상환경을 구축할 때, poetry를 사용한다.
이에 대해서 정리해보자.

[Poetry 사용법 1편] 기본기능의 활용

🤖 Poetry란 1

✅ Python 프로젝트의 패키지 및 의존성 관리를 위한 도구 Poetry

프로젝트별로 가상 환경을 자동 관리, 깔끔하게 의존성 정리
프로젝트 내부의 pyproject.toml를 통해 의존성과 패키징 정보 등을 한곳에 관리
꾸준히 업데이트되는 다양한 라이브러리 및 패키지 관리

✅ 종종 pip와 pipenv의 장점을 결합했다는 평가를 받는다

자동화된 환경 관리: 프로젝트마다 별도의 가상 환경을 자동으로 생성 → 환경 충돌 위험 줄인다
명확한 의존성 기술: pyproject.toml에 프로젝트 정보와 의존성 명확히 기재
일관된 빌드 툴: 빌드, 패키징, 배포 등 라이프사이클을 한 도구에서 관리

✅ Poetry를 이용해 프로젝트를 생성하면, 프로젝트 루트 경로에 pyproject.toml 파일이 생긴다.

여기에 프로젝트명, 버전, 의존성 등 기본적인 프로젝트 메타 정보가 저장된다
종전의 setup.py, requirements.txt를 대체하여, 한 파일에 모두 정리하는 방식
버전과 의존성 범위를 보다 직관적으로 명시

🧑‍💻 Linux - Poetry

# 프로젝트 생성: poetry new
# -- my_project 폴더가 생성되고 기본적인 Python 패키지 구조가 자동 구성됨
poetry new my_project

# 패키지 추가: poetry add
# -- requests 라이브러리를 프로젝트에 추가, pyproject.toml에 requests가 의존성으로 기록됨
# -- 이 과정에서 Poetry가 자동으로 가상 환경 생성
cd my_project
poetry add requests

# 패키지 제거
poetry remove requests

# 패키지 업데이트
# -- 특정 버전으로 업/다운그레이드도 가능: poetry add requests==2.26.0
poetry update requests

# 패키지 검색
poetry search <package_name>

# 버전 범위 지정
# -- ^2.25.1 표기는 2.x 버전대에서 하위 호환이 가능한 버전을 허용한다는 의미
[tool.poetry.dependencies]
requests = "^2.25.1"

# 특정 파이썬 버전 사용하기
# -- 프로젝트별로 특정 버전 사용하려면, 
# -- pyproject.toml의 [tool.poetry.dependencies] 섹션에 python 버전 범위 지정하거나 
# -- 아래 명령어로 설정
poetry env use python3.9

# 가상 환경 위치 설정 및 변경
# -- 현재 프로젝트에서 사용 중인 가상 환경 경로 확인
poetry env info
# -- 별도 디렉터리(.venv)를 프로젝트 내부에 사용하고 싶다면
poetry config virtualenvs.in-project true
poetry install

# poetry 환경에서 명령어 실행: poetry run
# -- 가상 환경 내부에서 python main.py 수행
poetry run python main.py

# poetry shell을 실행하면 현재 터미널 세션이 가상 환경으로 활성화
# -- 그 뒤에는 python main.py 처럼 바로 실행 가능
# 환경을 빠져나가려면 exit

# scripts 섹션을 이용한 명령어 alias 등록
# -- pyproject.toml 내에 scripts 섹션을 설정하면, 자주 쓰는 명령어를 단축어처럼 사용 가능
[tool.poetry.scripts]
start = "my_project.main:run"
# -- 이후 poetry run start 명령으로 myproject/main.py의 run() 함수를 바로 실행 가능

🤖 Poetry란 2

Poetry는 Python 프로젝트의 의존성 관리와 패키징을 위한 현대적인 도구이다.
기존의 pip + virtualenv + requirements.txt 조합을 대체하는 올인원 솔루션이라고 볼 수 있다.

🧑‍💻 Poetry의 주요 특징

✅ 의존성 관리

pyproject.toml 파일을 통해 프로젝트 메타데이터와 의존성을 선언적으로 관리
의존성 해결 알고리즘이 내장되어 버전 충돌을 자동으로 해결
poetry.lock 파일로 정확한 버전을 고정하여 재현 가능한 환경 보장

✅ 가상환경 통합

가상환경을 자동으로 생성하고 관리
프로젝트별로 격리된 환경 제공
별도의 virtualenv 설치나 관리가 불필요

✅ 패키징과 배포

PyPI 배포를 위한 패키지 빌드 기능
표준 Python 패키징 형식 지원

🧑‍💻 기본 사용법

# Poetry 설치
curl -sSL https://install.python-poetry.org | python3 -

# 새 프로젝트 시작
poetry new my-project
cd my-project

# 기존 프로젝트에 Poetry 설정
poetry init

# 의존성 추가
poetry add requests
poetry add pytest --group dev  # 개발 의존성

# 가상환경에서 명령 실행
poetry run python main.py
poetry run pytest

# 가상환경 활성화
poetry shell

# 의존성 설치
poetry install

🧑‍💻 주요 파일들

pyproject.toml

[tool.poetry]
name = "my-project"
version = "0.1.0"
description = ""

[tool.poetry.dependencies]
python = "^3.8"
requests = "^2.28.0"

[tool.poetry.group.dev.dependencies]
pytest = "^7.0.0"

poetry.lock

정확한 버전과 해시값이 기록된 락 파일
팀원들과 동일한 환경 보장

# This file is automatically @generated by Poetry 2.1.4 and should not be changed by hand.
package = []

[metadata]
lock-version = "2.1"
python-versions = ">=3.11"
content-hash = "---"

🤖 최종 정리

📚 1. 왜 Poetry를 쓰나?

기존 Python 프로젝트에서 흔히 겪는 문제들:

requirements.txt, setup.py, setup.cfg … 파일이 따로 놀아서 관리가 번거로움
pip만 쓰면 의존성 충돌 버전 해결이 까다로움
virtualenv, venv 따로 쓰면서 가상환경 위치 관리가 불편함
PyPI 배포 준비(sdist, wheel)가 복잡함

➡️ Poetry는 이를 하나의 도구 + 하나의 설정 파일(pyproject.toml) 로 깔끔히 해결

📚 2. 주요 기능

(1) ✅ 가상환경 관리

프로젝트별 가상환경 자동 생성
poetry shell 로 진입, poetry run python 으로 실행
.venv/ 안에 둘 수도 있고, 전역 관리도 가능

(2) ✅ 의존성 관리

poetry add requests → requests 설치 + 버전 기록
poetry remove requests → 제거
poetry update → lock 파일 기준 업데이트
자동으로 poetry.lock 파일을 만들어 재현성 있는 환경 보장

(3) ✅ 패키징 & 배포

poetry build → wheel, sdist 생성
poetry publish → PyPI 업로드
pyproject.toml 안의 메타데이터(name, version, authors, packages)로 패키지 정의

(4) ✅ 일관된 설정 파일

모든 게 pyproject.toml 한 파일 안에서 정의됨 (의존성, 파이썬 버전, 패키징 설정, 스크립트 등)

📚 3. 기본 사용 흐름

# 새 프로젝트 생성
poetry new myproj
cd myproj

# 가상환경 생성 및 설치
poetry install

# 패키지 추가
poetry add fastapi uvicorn

# 가상환경 진입
poetry shell

📚 4. pip/venv와 비교

기능	pip + venv	Poetry
가상환경 생성	`python -m venv` 따로 필요	`poetry install` 시 자동 생성
의존성 기록	`requirements.txt` 수동 작성	`pyproject.toml` 자동 관리
버전 고정	`pip freeze > requirements.txt`	`poetry.lock` 자동 관리
배포 지원	`setup.py` 직접 작성	`poetry build/publish` 자동 지원