[Poetry] poetry 개발 환경 셋팅하기 : 설치부터 가상환경 구축까지

Python 프로젝트를 하다 보면 매번 고민되는 부분이 있다.
“이 프로젝트는 어떤 가상환경을 쓰지?”, “패키지 버전 충돌은 어떻게 관리하지?”, “requirements.txt를 최신으로 유지하는 게 맞나?” 같은 문제들 말이다.

나 역시 프로젝트가 조금만 복잡해지면 venv와 pip freeze만으로는 관리가 번거롭다는 걸 자주 느꼈다. 그래서 poetry라는 개발 환경을 알게 되었고, 마침 인턴 과정을 진행하면서 poetry개발환경에서 진행하게 되어 poetry로 가상환경을 셋팅한 과정을 기록하려고 한다.

오늘은 Poetry가 무엇인지, 왜 쓰는지부터 시작해 설치 방법과 기본 명령어까지 정리해보려고 한다. 앞으로 Python 프로젝트를 새로 시작할 때 훨씬 깔끔하게 관리할 수 있는 기반이 될 것이다.

---

1. Poetry란?

Poetry는 Python 프로젝트의 패키지와 가상환경을 통합 관리하는 도구이다.
기존의 pip + requirements.txt 조합보다 훨씬 체계적이고, Node.js의 npm, Rust의 cargo와 비슷한 철학을 가진 툴이라고 이해하면 쉽다.

• 가상환경 자동 관리 : poetry는 프로젝트별 가상 환경을 자동으로 생성하고 관리
• 의존성 관리 : pyproject.toml 파일을 사용
• 패키지 버전 충돌 해결 : poetry.lock 파일로 
• 빌드/배포 지원

즉, Python 개발에 필요한 프로젝트 관리 기능을 한 번에 제공하는 도구이다.

poetry를 설치하고 가상환경을 구축하게 되면 위의 두가지 파일이 생긴다! 

 

pyproject.toml 파일은 프로젝트 설정과 의존성을 관리하고

poetry.lock 파일은 프로젝트의 의존성이 해결된 후 생성되어 호환 가능한 패키지 버전을 찾는다. 즉, 의존성 트리에 있는 모든 패키지의 정확한 버전을 고정하고 기록하여, 프로젝트가 다양한 환경에서도 일관된 의존성을 유지할 수 있게 해준다

---

2. Poetry 설치하기 

설치는 매우 간단하다. 공식 문서에서 권장하는 방법은 다음과 같다.

# Linux / macOS
curl -sSL https://install.python-poetry.org | python3 -

# Windows (PowerShell)
(Invoke-WebRequest -Uri https://install.python-poetry.org -UseBasicParsing).Content | py -

 

설치가 완료 된 후 정상 동작을 확인하려면 아래 명령어로 확인하면 된다.

poetry --version

 

설치했는데도 버전이 뜨지 않으면 쉘을 재시작하거나 설치한 위치를 확인해보기!

---

3. Poetry 기본 명령어

설치가 끝났다면, 바로 프로젝트에서 활용할 수 있다.

3.1 프로젝트 생성

poetry new myproject

 

- 개발 의존성으로 패키지 추가하고 싶다면 

poetry add --dev 패키지명

 

- 특정 버전의 패키지를

poetry add <패키지명>@<버전>

프로젝트에 설치하는 방법

 

3.2 의존성 설치

poetry install

3.3 패키지 

패키지 추가

poetry add 패키지명

 

설치된 패키지 목록 조회

poetry show

 

패키지 제거

 

poetry remove requests

 

3.4 가상환경 

poetry shell

앞에 (chloe-py3.11) 가상환경이 활성화 된것을 알 수 있다. 

가상환경을 비활성화 하려면 아래 명령어 사용하면 된다.

deactivate

exit

 

현재 활성화된 가상환경 정보를 알고싶다면 env info. 현재 프로젝트와 연관된 모든 가상환경 나열하려면 env list 명령어 사용 

poetry env info

poetry env list

 

가상환경을 삭제하려면

poetry env remove 가상환경이름

 

3.5 특정 파일 실행

poetry run python 파일이름

 

---

 

Poetry를 써보면 “아, 이제 Python 프로젝트 관리가 훨씬 단순해졌구나”라는 걸 바로 느낄 수 있다.
가상환경 생성부터 패키지 설치, 버전 고정, 배포까지 한 도구로 해결되니 더 이상 requirements.txt를 수동으로 업데이트할 필요가 없다.

앞으로 새로운 프로젝트를 시작한다면, 가상환경부터 패키지 관리까지 Poetry로 셋팅하는 습관을 들이는 것이 좋다.

다음 글에서는 Poetry를 이용한 Docker 환경에서 Python 프로젝트를 배포하는 방법을 다뤄보려고 한다. Poetry와 Docker를 함께 쓰면 협업과 배포 과정에서 더 강력한 시너지를 낼 수 있다!