poetry 로 python 개발환경 세팅

Python 프로젝트를 만들다 보면 버전 충돌, 의존성 지옥, 배포 설정 등 다양한 문제에 직면하게 됩니다. 이럴 때 도움을 주는 도구가 바로 Poetry입니다. Poetry는 의존성 관리와 패키징을 통합적으로 해결해주는 Python 전용 툴입니다. 이 글에서는 Poetry를 활용해 Python 개발환경을 깔끔하게 세팅하는 방법을 소개합니다.

 

왜 poetry인가?

보통 Python 프로젝트에서는 requirements.txt, pip, virtualenv, setup.py 등 다양한 툴을 따로따로 사용합니다. 하지만 이 조합은 번거롭고 유지보수가 어렵습니다. Poetry는 다음 기능을 통합 제공합니다:

• 가상환경 자동 관리
• 의존성 설치 및 잠금(lock)
• 프로젝트 초기화 및 설정 (pyproject.toml 기반)
• 배포를 위한 빌드 및 퍼블리싱

 

poetry 설치

poetry 를 전역으로 설치합니다.

pip install poetry

# 설치 확인
poetry --version

 

 

zsh, oh my zsh 등 자신의 쉘 환경에 맞게 자동완성 세팅

 

공식문서 내용 참고: https://python-poetry.org/docs/

 

 

poetry 사용법

 

프로젝스 생성

poetry new [project-name]

 

의존성 패키지 설치

cd [package name]

# 기존 pip install [package name]
poetry add [package name]

 

스크립트 실행

# 스크립트 실행
poetry run python [python file name]

# 모듈 실행 / module_name/__main__.py 파일이 존재해야 된다.
poetry run python -m [module name]

 

poetry 사용시 팁

가상환경 위치를 프로젝트 내로 변경

poetry 를 사용하면 가상환경의 위치가 기본적으로 프로젝트 바깥에 잡히게 된다.

이때 가상환경이 설정되는 기본 위치를 프로젝트 내의 .venv 로 지정하는 방법은 다음과 같다.

 

# 프로젝트 폴더 내에 가상환경 세팅
poetry config virtualenvs.in-project true

# 현재 가상환경 삭제
poetry env remove python

# 가상환경 재 인스톨
poetry install

# 가상환경 위치 확인
poetry env info --path

 

vscode 에서 가상환경 위치 설정

vscode 에서 가상환경 위치가 자동으로 세팅이 안되어, 자동완성, 실행 등등이 안되어본 경험이 종종 생기게 된다. 이를 위해서 가상환경 위치를 설정하는 방법을 공유한다.

 

python extensions 가 설치 되어있다는 전제하에 cmd + shift + p

 

python: Select Interpreter - 검색 및 선택

 

원하는 가상환경이 보인다면 선택 or enter interpreter path 를 선택후 가상환경 위치 입력 (예. 가상환경이 프로젝트 내에 위치해있다면, ./.venv/bin/python 입력)

마무리

Poetry를 도입하면 프로젝트를 사용하는 전체적인 경험이 훨씬 깔끔하고 명확해집니다.

복잡했던 가상환경 관리, 의존성 충돌, 빌드 설정 같은 문제들이 눈에 띄게 줄어들고, “작동하는 코드”를 “잘 작동하는 프로젝트”로 정리하는 데 큰 도움이 됩니다.

 

특히 개인 프로젝트든 팀 협업이든, 처음부터 일관된 구조와 관리 체계를 만드는 것이 장기적인 생산성과 유지보수에 매우 중요합니다.
Poetry는 그 출발점으로 훌륭한 선택입니다.