본 글은 Ubuntu 22.04.1 LTS 환경에서 진행하였습니다.

Poetry란?

• Poetry란 파이썬 의존성 관리 툴입니다.

Poetry를 사용해야 하는 이유

• Dependency Resolver로 복잡한 의존성들의 버전 충돌을 방지합니다.
• Virtualenv를 생성해서 격리된 환경에서 빠르게 개발을 할 수 있습니다.
• 기존 파이썬 패키지 관리 도구에서 지원하지 않는 Build, Publish가 가능합니다.
• pyproject.toml을 기준으로 여러 툴들의 config를 명시적으로 관리할 수 있습니다.

Poetry 설치

설치가 잘 안 된다면 공식 홈페이지를 참고해주시기 바랍니다.

• 다음 명령어로 Poetry를 설치합니다.

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

• 설치 후 출력되는 안내에 따라 PATH를 추가해줍니다.
  
• 쉘을 재시작합니다

exec $SHELL

• poetry --help가 다음과 같이 잘 작동한다면, 설치가 완료된 것입니다.
  
  

Poetry 사용하기

Poetry 프로젝트 생성해보기

프로젝트 init

# 프로젝트를 init 합니다.
# init를 사용하면 대화 형식으로 패키지를 설치할 수 있습니다. 

poetry init

• Init되는 과정은 다음과 같습니다.
  1. 프로젝트 메타 정보 설정: Package name, Version, Desc, …
  2. main dependencis(프로덕트용) 정의
  3. dev dependencies(Dev용) 정의
  4. (현재 path에) pyproject.toml 파일 생성
• (2) (3)과 같이 개발환경마다 필요한 패키지를 분리할 수 있습니다.
• 생성된 pyproject.toml 파일이 의존성을 관리하는 파일입니다.
• python = “^3.8” 은 파이썬 3.8버전보다 높은 버전은 다 허용한다는 의미입니다.
  (정확히는 3.8 이상, 4.0미만을 의미합니다)

패키지 add

• 필요한 패키지를 Add해보겠습니다.

# 필요한 패키지를 추가합니다.
poetry add pandas 

# pyproject.toml을 출력해보면 다음과 같이 추가됨을 알 수 있습니다.
cat pyproject.toml  

Pyenv & Poetry 가상환경 생성

• Pyenv로 Local 파이썬 버전을 설정하고, Poetry로 Local 파이썬 버전에 해당하는 가상환경을 생성합니다.

  # local 파이썬 버전 설정
  pyenv local 3.8.10
  
  # Poetry로 가상환경 생성
  poetry env use python3
  
  # 쉘을 활성화
  poetry shell

  

poetry install

• poetry install으로 (활성화된 가상환경에) pyproject.toml에 저장된 내용에 기반해 라이브러리 설치 합니다.

  # pyproject.toml에 저장된 내용에 기반해 라이브러리 설치
  poetry install
  
  # 다음 명령어로 poetry.lock 파일이 생긴 것을 확인
  ls

  
  
• poetry.lock 파일을 통해 작성하고 있는 프로젝트 의존성과 동일한 의존성을 가질 수 있습니다.

Poetry 명령어 정리

poetry init

• 현재 디렉토리에 pyproject.toml을 생성합니다

# 대화 형식으로 패키지를 설치 
poetry init

poetry new

# path에 파이썬 프로젝트를 생성
poetry new <path>

# poetry new 로 생성한 프로젝트의 구조
.
├── poetry_test
│   └── __init__.py
├── pyproject.toml
├── README.md
└── tests
    └── __init__.py

poetry install

• pyproject.toml에 저장된 내용에 기반해 라이브러리를 설치 합니다.

# poetry install으로 pyproject.toml에 저장된 내용에 기반해 라이브러리를 설치
poetry install

# (옵션) 개발환경의 라이브러리는 빼고 설치
poetry install --no-dev

# (옵션) 캐시를 저장하지 않습니다.
poetry install --no-cache

poetry update

• dependencies를 최신버전으로 업데이트 하고, poetry.lock파일을 최신화합니다(lock 파일을 삭제하고, 다시 install).

# dependencies 업데이트
poerty update

# 일부 dependencies만 업데이트
poetry update pandas numpy

poetry add

• 새로운 dependency를 pyproject.toml에 추가합니다.
  • 버전 명시는 Dependency specification을 참고해주세요.

# 필요한 패키지를 추가
poetry add pandas 

# 버전 명시
poetry add pandas@^1.0.0  # 1.0.0 이상, 2.0.0 미만
poetry add "pandas~1.0.0"  # 1.0.0 이상, 1.1.0 미만
poetry add pandas==1.0.0  # 버전을 명확히 명시
poetry add "pandas>=1.0.0"  # 해당하는 버전 이상(상한x)
poetry add pandas@latest  # 최신 버전

# 깃 저장소에 있는 패키지 설치
poetry add git+https://github.com/sdispater/pendulum.git

# 로컬에 위치한 폴더나 파일로 설치
poetry add ./my-package/
poetry add ../my-package/dist/my-package-0.1.0.tar.gz

# (옵션) --dev or -D 옵션을 통해 Dev 환경에서만 사용할 패키지를 추가
poetry add -D pandas

• 만약 requirements.txt에서 dependency를 추가하고 싶다면, 다음 명령어로 할 수 있습니다.

xargs poetry add < requirements.txt

poetry remove

• 설치된 패키지를 삭제합니다.

# 설치된 패키지 삭제
poetry remove pandas

# (옵션) --dev or -D 옵션을 통해 Dev 환경에서 패키지를 삭제
poetry remove -D pandas

poetry show

• 사용가능한 모든 패키지를 출력합니다.

# 사용가능한 모든 패키지 출력
poetry show

# --tree 옵션을 통해 패키지 의존성을 tree형태로 출력
poetry show --tree

# dev환경 제외하고 출력
poetry show --no-dev

poetry config

• poetry config를 출력하거나 변경합니다.

# config 출력
poetry config --list

# config 변경
poetry config [options] [setting-key] [setting-value1] ... [setting-valueN]

poetry run

• virtualenv 내에 주어진 명령을 실행합니다.

poetry run python -V

poetry search

• 사용가능한 패키지를 찾습니다.

poetry search pandas numpy

poetry export

• poetry의 .lock 파일을 다른 형식으로 변환하여 내보냅니다.

# -f 옵션으로 format을 지정(default: requirements.txt)하여 내보냄
poetry export -f requirements.txt --output requirements.txt

Poetry 가상환경 명령어

poetry env info

• 현재 활성화된 가상환경에 대한 정보를 얻습니다.

poetry env info

poetry env use

• Poetry로 가상환경을 생성합니다.

# 가상환경 생성
poetry env use </full/path/to/python>

# 만약 파이썬이 PATH에 잡혀있다면, 다음 명령어만 입력하면 가상환경을 생성합니다.
poetry env use python3

poetry env list

• 가상환경 리스트를 출력합니다.

poetry env list

poetry env remove

• 가상환경을 삭제합니다.

poetry env remove poetry-test-4oQtH5dM-py3.8

+) Issue

Poetry Add로 패키지 추가 시 작동이 멈추는 Issue

• Ubuntu에서 poetry init나 poetry add 로 패키지를 추가할 때 작동이 멈추는 Issue가 발견되었습니다.
• -vvv로 로그를 확인해보니 다음과 같이 keyring.backend 관련 로딩에서 다음으로 넘어가지 않습니다.
  
• Solution : 다음 코드를 입력한 후, poetry add하면 정상적으로 동작됩니다.

export PYTHON_KEYRING_BACKEND=keyring.backends.null.Keyring

vscode에서 poetry 가상환경 인터프리터가 잡히지 않는 Issue

• Solution : 생성되는 virtualenv 환경을 프로젝트 폴더 내부에 생성(.venv)되게 설정합니다.

# config 변경
poetry config virtualenvs.in-project true
poetry config virtualenvs.path "./.venv"

# 이후 vscode에서 사용할 가상환경 내 파이썬의 인터프리터를 선택하여 사용하면 됩니다.
# 만약, vscode에 원하는 경로의 파이썬 인터프리터가 나오지 않는다면, 
# 다음 명령어를 입력하여 인터프리터 위치를 찾아 수동으로 입력하세요.
which python

Reference

• Poetry 공식 사이트
• Poetry Issue #6354
• vscode-python Issue #1871