IT 20년차의 복합 비즈니스 도전

아래는 Python 프로젝트의 패키지 및 의존성 관리를 위한 도구인 Poetry를 소개하고, 기본적인 사용법을 다루는 블로그 포스팅 예시입니다. 이 글은 Poetry 사용법 시리즈의 1편(기본 편)으로, 2편에서는 보다 심화된 기능과 고급 활용 예시를 다룰 예정입니다.

---

I. 포스팅의 의도 & 필요성

1. 현업에서 자주 사용하는 의존성 관리 도구
   Python을 이용하여 애플리케이션을 개발하다 보면, 꾸준히 업데이트되는 다양한 라이브러리 및 패키지를 관리하는 것이 중요합니다. pip, pipenv, conda 등 다양한 도구가 있지만, 최근에는 Poetry가 보다 편리하고 강력한 관리 기능을 제공하며 많은 관심을 받고 있습니다.
2. 개발 환경 세분화 및 협업
   여러 명이 협업하거나, 한 컴퓨터에서 서로 다른 프로젝트를 동시에 관리해야 할 때 환경 충돌(다른 버전의 라이브러리에서 발생하는 문제)이 빈번히 일어납니다. Poetry는 프로젝트별로 가상 환경을 자동으로 관리하고, 깔끔하게 의존성을 정리할 수 있어 협업 시 충돌을 크게 줄여줍니다.
3. 프로젝트 유지보수 편의성
   버전 충돌은 한 번이라도 겪어본 사람이라면 그 번거로움을 잘 알 것입니다. Poetry는 프로젝트 내부의 pyproject.toml를 통해 의존성과 패키징 정보 등을 한곳에 관리해 주어, 유지보수가 훨씬 수월해집니다.

---

II. 포스팅의 목표

1. Poetry의 기본 개념 이해
   • Poetry가 어떤 방식으로 Python 패키지(라이브러리) 의존성을 관리하는지 전반적인 개념을 파악할 수 있습니다.
2. Poetry 설치 및 기본 명령어 숙지
   • Poetry를 설치하고, 프로젝트를 초기화하고, 패키지를 추가/삭제/업데이트 등 실전 상황에서 주로 사용되는 명령어를 알아봅니다.
3. 가상 환경 설정 및 관리 방법 학습
   • Poetry의 가상 환경 사용 방식과 파이썬 버전 설정 방법을 익혀서, 향후 프로젝트를 구성할 때 활용할 수 있습니다.
4. 문제 상황 및 해결법 익히기
   • 설치 과정에서 발생할 수 있는 오류, 패키지 버전 충돌 등 대표적인 문제 상황을 예시로 들어보고 해결 방안을 소개합니다.

---

III. 목차

1. Poetry란 무엇인가?
   1.1. Poetry의 배경과 특징
   1.2. 다른 Python 패키지 관리 도구와의 비교(pip, pipenv 등)
2. Poetry 설치 및 기본 설정
   2.1. Poetry 설치 방법 (Windows, macOS, Linux)
   2.2. Poetry가 Python 프로젝트를 관리하는 구조
   2.3. 초기 세팅 후 pyproject.toml 구조 소개
3. 프로젝트 생성 및 의존성 관리
   3.1. 프로젝트 생성: poetry new
   3.2. 패키지 추가: poetry add
   3.3. 패키지 삭제/업데이트: poetry remove, poetry update
   3.4. 패키지 검색 및 버전 제어
4. 가상 환경 관리
   4.1. Poetry가 가상 환경을 생성하는 방식
   4.2. 특정 Python 버전 사용하기
   4.3. 가상 환경 위치 설정 및 변경
5. 프로젝트 실행 & 스크립트 실행
   5.1. poetry run 명령어 사용법
   5.2. poetry shell과의 차이점
   5.3. scripts 섹션을 이용한 커맨드 alias 등록
6. 핸즈온 과정 중 발생 가능 문제 및 해결 방법
   6.1. 설치 충돌 또는 pip 버전 호환성 문제
   6.2. 가상 환경을 찾지 못하는 문제
   6.3. 패키지 버전 충돌 발생 시 처리
   6.4. Windows/Mac/Linux 환경별 특이점
7. 정리 & 다음 편 예고
   7.1. 요약
   7.2. 심화 편 예고: 버전 범위 지정, 프로젝트 배포, PyPI 업로드, CI/CD 파이프라인 연동 등

---

IV. 본문

1. Poetry란 무엇인가?

Poetry는 Python 프로젝트의 의존성 관리를 위한 툴로, 종종 pip와 pipenv의 장점을 결합했다는 평가를 받습니다.

• 자동화된 환경 관리: 프로젝트마다 별도의 가상 환경을 자동으로 생성해 주어, 환경 충돌 위험을 줄입니다.
• 명확한 의존성 기술: pyproject.toml에 프로젝트 정보와 모든 의존성을 명확하게 기재합니다.
• 일관된 빌드 툴: 빌드, 패키징, 배포 등 라이프사이클을 한 도구에서 관리할 수 있어 편리합니다.

2. Poetry 설치 및 기본 설정

2.1. Poetry 설치 방법

• Windows
  • PowerShell에서 다음 명령을 실행:

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

  • 설치 경로가 자동으로 설정되지 않는다면, 설치가 완료된 후 %USERPROFILE%\.poetry\bin (또는 %APPDATA%\Poetry\bin) 경로를 PATH 환경변수에 추가해야 합니다.
• macOS / Linux
  • 설치가 끝난 뒤, 터미널 설정 파일(~/.bashrc, ~/.zshrc 등)에 아래 내용을 추가해 Poetry가 인식되도록 합니다.

    export PATH="$HOME/.poetry/bin:$PATH"
    

• curl -sSL https://install.python-poetry.org | python3 -

2.2. 구조 이해: pyproject.toml의 역할

Poetry를 이용해 프로젝트를 생성하면, 프로젝트 루트 경로에 pyproject.toml 파일이 생깁니다. 여기에는 프로젝트명, 버전, 의존성 등 기본적인 프로젝트 메타 정보가 저장됩니다.

• 종전의 setup.py, requirements.txt를 대체하여, 한 파일에 모두 정리하는 방식입니다.
• 버전과 의존성 범위를 보다 직관적으로 명시할 수 있습니다.

3. 프로젝트 생성 및 의존성 관리

3.1. 프로젝트 생성: poetry new

poetry new my_project

• 위 명령을 실행하면, my_project 폴더가 생성되고 기본적인 Python 패키지 구조(my_project/my_project/__init__.py, tests 디렉터리 등)가 자동 구성됩니다.

3.2. 패키지 추가: poetry add

cd my_project
poetry add requests

• requests 라이브러리를 프로젝트에 추가하고, pyproject.toml에 requests가 의존성으로 기록됩니다.
• 이 과정에서 Poetry가 자동으로 가상 환경을 생성합니다.

3.3. 패키지 삭제/업데이트

• 패키지 제거

  poetry remove requests
  

• 패키지 업데이트

  poetry update requests
  

  특정 버전으로 업/다운그레이드도 가능합니다. 예: poetry add requests==2.26.0

3.4. 패키지 검색 및 버전 제어

• 패키지 검색

  poetry search <package_name>
  

• 버전 범위 지정
  예:

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

  위 ^2.25.1 표기는 2.x 버전대에서 하위 호환이 가능한 버전을 허용한다는 의미입니다.
  (자세한 범위 지정 규칙은 2편 심화 과정에서 다룹니다.)

4. 가상 환경 관리

4.1. 가상 환경 자동 생성

기본적으로 Poetry는 프로젝트별로 가상 환경을 $HOME/.cache/pypoetry/virtualenvs (OS별 차이 있음) 내부에 자동으로 생성해줍니다.

4.2. 특정 Python 버전 사용하기

프로젝트별로 특정 Python 버전을 사용하려면, pyproject.toml의 [tool.poetry.dependencies] 섹션에 python 버전 범위를 지정하거나,

poetry env use python3.9

처럼 명령어로 설정할 수 있습니다.

4.3. 가상 환경 위치 설정 및 변경

다음 명령어로 현재 프로젝트에서 사용 중인 가상 환경 경로를 확인할 수 있습니다.

poetry env info

만약 별도 디렉터리(예: .venv)를 프로젝트 내부에 사용하고 싶다면, 아래와 같이 설정할 수 있습니다.

poetry config virtualenvs.in-project true
poetry install

그 후 my_project/.venv/ 경로에 가상 환경이 생성됩니다.

5. 프로젝트 실행 & 스크립트 실행

5.1. poetry run 명령어

Poetry 환경에서 명령어를 실행하기 위해서는 poetry run을 사용합니다.

poetry run python main.py

이 명령은 Poetry가 관리하는 가상 환경 내부에서 python main.py를 수행합니다.

5.2. poetry shell과의 차이

• poetry shell을 실행하면 현재 터미널 세션이 가상 환경으로 활성화됩니다.
  • 그 뒤에는 python main.py처럼 바로 실행이 가능하죠.
  • 환경을 빠져나가려면 exit를 입력합니다.

5.3. scripts 섹션을 이용한 명령어 alias 등록

pyproject.toml 내에 scripts 섹션을 설정하면, 자주 쓰는 명령어를 단축어처럼 사용할 수 있습니다. 예시:

[tool.poetry.scripts]
start = "my_project.main:run"

이후

poetry run start

명령으로 my_project/main.py의 run() 함수를 바로 실행할 수 있습니다.

6. 핸즈온 과정 중 발생 가능 문제 & 해결 방법

6.1. 설치 충돌 혹은 pip 버전 호환성 문제

• 증상: Poetry 설치 중, pip 버전이 낮아서 설치가 실패하거나 Python 버전이 맞지 않아 오류가 발생
• 해결방법: Python 버전을 3.7 이상(가급적이면 3.8 이상)으로 업데이트하고, pip를 최신 버전으로 업그레이드합니다.

  python3 -m pip install --upgrade pip
  

  이후 다시 Poetry 설치를 시도합니다.

6.2. 가상 환경을 찾지 못하는 문제

• 증상: poetry install을 실행했는데, 가상 환경이 자동으로 안 잡히거나 경로 인식이 안 됨
• 원인: PATH 설정이 안 되었거나, 별도로 pyenv 등을 설치해둔 경우 혼선을 줄 수 있음
• 해결방법:
  • poetry env use python3.9 처럼 원하는 파이썬 버전을 명시하여 재설정
  • poetry env list 및 poetry env info로 현재 사용 중인 가상 환경 정보를 확인
  • 필요한 경우 poetry env remove <environment>를 통해 잘못 생성된 환경을 제거 후 재생성

6.3. 패키지 버전 충돌

• 증상: poetry update 도중 특정 패키지 버전 충돌 때문에 설치 실패
• 해결방법:
  • poetry add <package>@<version>을 통해 일부 패키지를 명시적으로 다운그레이드 혹은 업그레이드
  • poetry update --lock 명령어로 락 파일(poetry.lock)을 재생성
  • 필요시 pyproject.toml에서 버전 호환 범위를 조정("^2.0" → "^2.1", ">=2.0, <3.0" 등)

6.4. Windows/Mac/Linux 환경별 특이점

• Windows와 macOS/Linux에서 경로 표기 방식이 다릅니다.
  • 설치 후 PATH를 제대로 설정했는지 우선 확인하세요.
• Windows Powershell과 CMD에서의 명령어 형식이 다소 다를 수 있으니, 가급적 Powershell 사용을 권장합니다.

---

V. 정리 & 다음 편 예고

지금까지 Poetry를 통한 프로젝트 생성부터 의존성 추가/삭제, 가상 환경 관리, 그리고 스크립트 실행 방법까지 배워 보았습니다. Poetry를 이용하면, 번거로운 가상 환경 설정과 패키지 버전 관리를 간편하게 처리할 수 있습니다.

다음 편(심화편) 예고

다음 포스팅에서는 아래와 같은 심화 내용을 다룰 예정입니다.

• 버전 범위 지정의 원리 (Caret ^, Tilde ~, Wildcard * 등)
• 프로젝트 배포 및 PyPI 업로드
• CI/CD 파이프라인과 연동
• Monorepo 구조에서의 Poetry 사용
• 빌드/패키징 옵션 최적화

Poetry의 강력한 기능을 더 깊이 있게 이해하고 활용하여, 협업과 프로젝트 유지보수를 한층 효율적으로 만들어 보시기 바랍니다.

---

추가 팁: 더 나은 선택을 위한 제안

• Poetry + pyenv 조합: 여러 파이썬 버전을 손쉽게 전환해야 하는 환경이라면, pyenv(또는 asdf) 같은 Python 버전 관리 툴과 함께 사용하는 것이 좋습니다.
• Poetry Plugins: 필요에 따라 Poetry 플러그인을 설치해 기능을 확장할 수 있습니다. 예: poetry-dynamic-versioning 등.
• Docker 환경 통합: Dockerfile 안에서 Poetry를 사용하여 이미지 빌드를 구성하면, CI/CD 파이프라인을 보다 명확하게 관리할 수 있습니다(2편에서 다룰 예정).

위 내용으로도 부족하다면 공식 문서(https://python-poetry.org/docs/)에서 더 자세한 정보를 확인해 보세요. 다음 편에서도 더욱 유익한 심화 내용을 다룰 예정이니 많은 기대 부탁드립니다!