글을 쓰게 된 배경

Poetry를 이용해서 Python Project를 진행했는데, 구성원간의 패키지 버전이 다른 문제와, poetry install만 해도 poetry.lock이 수정되는 문제가 발생했습니다.

이런 현상으로, poetry에 대한 이해도가 부족함을 느꼈습니다.

poetry에 대한 이해를 높이고, 여러 문제와 그에 맞는 해결방법을 소개하고자 글을 작성하게 되었습니다.

내용

Poetry?

간단하게 Poetry를 왜 사용하는지, 그리고 다른 의존성 관리도구에 비해 어떤 장점이 있는지 소개하겠습니다.

poetry란?

Poetry는 Python 프로젝트의 패키지 관리 및 의존성 관리 도구이다. 기존의 pip과 virtualenv를 대체하여 의존성 관리, 가상 환경 생성, 패키지 배포까지 한 번에 처리할 수 있도록 설계되었습니다.

주요 기능

• pyproject.toml + poetry.lock 의존성 관리
• 프로젝트 별 가상환경 관리
• 패키지 빌드 및 배포 (PyPI or private store에 배포 가능)
• 버전 및 프로젝트 관리

해당 내용이 주제가 아니므로 간단하게 소개하고 넘어가겠습니다. 궁금한 분들은 더 찾아보시면 좋을 것 같습니다.

Poetry를 이용한 프로젝트 진행

poetry.lock 기준으로 설치하기

주의할 점

• 구성원들은 동일한 poetry version을 사용해야 합니다.

1. Poetry 설치:

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

2. Poetry 버전 맞추기: 팀원 간 동일한 Poetry 버전을 사용하도록 설정하는 것이 중요합니다. 특정 버전이 필요하다면 다음과 같이 업데이트하거나 다운그레이드할 수 있습니다.

   poetry self update <버전>

3. 패키지 추가 및 관리:

   • 새로운 패키지 추가 시 pyproject.toml을 직접 수정하지 않고 다음 명령어를 사용해야 합니다.

     poetry add <패키지명>

   • 특정 버전의 패키지를 설치하려면:

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

   • 개발용 패키지는 -dev 옵션을 추가하여 설치합니다.

     poetry add <패키지명> --dev

   • 의존성 패키지를 업데이트하려면:

     poetry update

   • 기존 환경과 동일한 패키지를 설치하려면:

     poetry install

poetry.lock 기준으로, pyproject.toml 수정하기

pyproject.toml 파일은 의존성 버전을 고정하는 경우가 있습니다.

• 일관된 환경을 유지하기 위해
• 의존성 충돌을 방지하기 위해
• 디버깅 및 버전 롤백을 하기 위해

Poetry는 기본적으로 pyproject.toml에 작성된 버전을 기준으로 패키지를 설치하지만, poetry.lock에 있는 버전들을 pyproject.toml에 직접 반영하려면 명령어로 설정할 수 있습니다.

먼저, poetry.lock에 저장된 모든 패키지와 버전을 확인하려면 다음 명령어를 실행합니다.

poetry show --tree # tree 구조로 설치 패키지 확인
poetry show --no-ansi | awk '{print $1, $2}' # requirments.txt 형태로 확인

• 해당 내용을 기반으로 pyproject.toml을 수정.

한줄 명령어로, pyproject.toml을 생성할 수 있습니다.

poetry export --without-hashes --format=requirements.txt | awk -F '==' '{print $1 " = \"" $2 "\""}' | tee pyproject.toml

• 결과로 나온 것은 의존성 영역이기 때문에, 부분 수정할 필요가 있습니다.
• export 가 안된다면 poetry-plugin-export을 설치해야 합니다.
  poetry self add poetry-plugin-export

⚠️ 설정 간 발생할 수 있는 문제

poetry install을 할때, 왜 poetry.lock 파일이 수정될까?

Poetry 버전 차이로 인한 poetry.lock 변경

• Poetry의 버전이 다르면 의존성 해석 방식이 달라질 수 있습니다.
• 새로운 Poetry 버전에서는 이전 버전과 다르게 의존성을 처리하는 방식이 업데이트될 수 있어, 같은 pyproject.toml을 사용해도 poetry.lock이 다르게 생성될 수 있습니다.
• 해결책: 팀원들이 동일한 Poetry 버전을 사용하도록 맞춥니다.

  poetry --version  # 현재 Poetry 버전 확인
  poetry self update <버전>  # 특정 버전으로 맞추기

시스템별 의존성 해석 차이

• Poetry는 OS에 따라 일부 패키지의 해시값이 다르게 기록될 수 있습니다.
• 특히, poetry.lock에는 각 패키지의 해시값이 포함되는데, macOS, Windows, Linux에서 동일한 패키지를 설치하더라도 해시값이 달라질 가능성이 있습니다.
• 해결책: 프로젝트를 진행하는 팀이 동일한 OS 환경에서 작업하거나, Docker 등의 컨테이너 환경을 활용하여 일관된 환경을 유지한다.

poetry install이 poetry.lock을 수정하는 경우

• poetry install 명령어는 일반적으로 poetry.lock을 수정하지 않습니다.
• 그러나 pyproject.toml의 패키지 버전 범위가 너무 넓게 설정되어 있으면, Poetry가 최신 버전을 찾으면서 lock 파일이 변경될 수 있습니다.
  예를 들어,

  ```toml
  requests = "^2.0"
  ```
  
  - 위와 같이 설정하면, `poetry install`을 실행할 때 최신 버전(예: 2.30.0)이 설치될 수 있으며, `poetry.lock`이 수정될 가능성이 있다.

• 해결책: pyproject.toml에서 패키지 버전을 명확히 지정하는 것이 중요하다.

  requests = "2.28.1"

  • 위처럼 특정 버전만 설치하도록 설정하면, poetry install 시 lock이 변경되지 않습니다.

개발자의 Poetry 환경 설정 차이

• poetry config virtualenvs.in-project true 설정이 다르면, 가상환경이 생성되는 위치가 다를 수 있고, 패키지가 올바르게 설치되지 않을 가능성이 있다.
• poetry install 실행 시 다른 환경이 적용되면서 poetry.lock이 다르게 기록될 수 있다.
• 해결책: 프로젝트 내 .venv를 사용하도록 일관되게 설정한다.

  poetry config virtualenvs.in-project true

이전 가상 환경이 반영되는 문제

• 만약 이전에 사용했던 가상 환경과 현재 가상 환경이 다르면 Poetry가 패키지를 재설치하면서 lock 파일을 업데이트할 수 있다.
• 해결책: 기존 가상 환경 삭제하고 재설치

  # 기존 가상환경 조회
  peotry env list
  # 기존 가상환경 제거
  poetry env remove [some-env]
  # 새로운 가상환경 생성
  poetry install

결론 및 요약

Poetry를 사용하여 Python 프로젝트의 패키지 및 버전 관리를 체계적으로 수행하면 환경 불일치, 의존성 충돌, 배포 실패 등의 문제를 방지할 수 있습니다. 하지만 올바르게 설정하지 않으면 팀원 간 poetry.lock이 다르게 생성될 수 있는 문제가 발생할 수 있습니다.

Poetry 버전 관리를 위한 핵심 체크리스트

1. Poetry 버전 통일

   • 팀원 간 동일한 Poetry 버전을 사용한다.

   poetry --version  # 현재 Poetry 버전 확인
   poetry self update <버전>  # 특정 버전으로 맞추기

2. 패키지 버전 고정

   • pyproject.toml에서 패키지 버전을 명확히 지정한다.

   requests = "2.28.1"

3. 운영 체제(OS) 차이 해결

   • OS에 따른 차이를 줄이기 위해 Docker 등의 컨테이너를 활용한다.

4. Poetry 설정 통일

   • 프로젝트 내 .venv를 사용하도록 설정하여 일관성을 유지한다.

   poetry config virtualenvs.in-project true

5. 가상 환경 문제 해결

   • 가상 환경이 문제를 일으키면 기존 환경을 삭제 후 다시 설정한다.

   # 기존 가상환경 조회
   peotry env list
   # 기존 가상환경 제거
   poetry env remove [some-env]
   # 새로운 가상환경 생성
   poetry install

Poetry를 올바르게 활용하면 패키지 의존성을 안정적으로 관리할 수 있으며, 협업 시 발생하는 버전 충돌 문제를 최소화할 수 있습니다.