1 poetry config: 설정 관리

Poetry의 동작을 제어하는 전역/로컬 설정을 관리한다.

1.1 설정 확인

# 모든 설정 확인
poetry config --list

# 특정 설정 확인
poetry config virtualenvs.in-project

1.2 주요 설정 항목

설정	기본값	설명
`virtualenvs.create`	`true`	가상환경 자동 생성 여부
`virtualenvs.in-project`	`false`	프로젝트 내 `.venv` 생성
`virtualenvs.path`	`{cache-dir}/virtualenvs`	가상환경 저장 경로
`virtualenvs.prefer-active-python`	`false`	활성 Python 인터프리터 우선 사용
`installer.parallel`	`true`	병렬 설치
`installer.max-workers`	(CPU 수)	병렬 설치 워커 수

1.3 설정 변경

# 전역 설정 (모든 프로젝트에 적용)
poetry config virtualenvs.in-project true

# 로컬 설정 (현재 프로젝트만 적용)
poetry config virtualenvs.in-project true --local
# → poetry.toml 파일이 프로젝트 루트에 생성됨

# 설정 초기화 (기본값으로 복원)
poetry config virtualenvs.in-project --unset

1.4 전역 설정 vs 로컬 설정

전역 설정: ~/.config/pypoetry/config.toml (Linux)
          ~/Library/Application Support/pypoetry/config.toml (macOS)
          %APPDATA%\pypoetry\config.toml (Windows)

로컬 설정: <project>/poetry.toml

로컬 설정이 전역 설정보다 우선한다. poetry.toml은 Git에 커밋하여 팀 전체가 동일한 설정을 사용할 수 있다.

1.5 권장 초기 설정

# 프로젝트 내 .venv 생성 (IDE 자동 인식)
poetry config virtualenvs.in-project true

# 활성 Python 버전 사용 (pyenv 호환)
poetry config virtualenvs.prefer-active-python true

2 poetry source: 패키지 소스 관리

의존성을 가져올 저장소(소스)를 관리한다.

2.1 소스 추가

# 사설 저장소 추가
poetry source add private https://pypi.company.com/simple/

# 우선순위 지정
poetry source add private https://pypi.company.com/simple/ --priority=supplemental

2.2 소스 우선순위

priority	동작
`default`	이 소스만 사용 (PyPI 대체)
`primary`	PyPI와 동일 우선순위
`supplemental`	PyPI에 없는 패키지만 여기서 검색
`explicit`	명시적으로 지정된 패키지만 여기서 설치

2.3 소스 관리

# 소스 목록 확인
poetry source show

# 소스 제거
poetry source remove private

2.4 pyproject.toml에서의 소스 설정

[[tool.poetry.source]]
name = "private"
url = "https://pypi.company.com/simple/"
priority = "supplemental"

[[tool.poetry.source]]
name = "torch-cu118"
url = "https://download.pytorch.org/whl/cu118"
priority = "explicit"

explicit 소스에서 설치할 패키지를 지정하는 방법:

[tool.poetry.dependencies]
torch = {version = "^2.0", source = "torch-cu118"}

3 poetry cache: 캐시 관리

Poetry는 다운로드한 패키지를 캐시하여 재설치 시 속도를 높인다.

# 캐시 목록 확인
poetry cache list

# 특정 캐시 삭제
poetry cache clear pypi --all

# 특정 패키지 캐시만 삭제
poetry cache clear pypi:requests:2.31.0

3.1 캐시 관련 문제 해결

설치 중 이상한 에러가 발생하면 캐시 문제일 수 있다:

# 모든 캐시 삭제 후 재설치
poetry cache clear --all pypi
poetry install

4 poetry self: Poetry 자체 관리

Poetry 자체를 업데이트하거나 플러그인을 관리한다.

# Poetry 업데이트
poetry self update

# 특정 버전으로 업데이트
poetry self update 1.8.0

# Poetry 버전 확인
poetry --version

5 poetry plugin: 플러그인 시스템

Poetry의 기능을 확장하는 플러그인을 관리한다.

5.1 유용한 플러그인

# poetry-plugin-export: requirements.txt 내보내기 (Poetry 1.2+ 별도 설치 필요)
poetry self add poetry-plugin-export

# poetry-plugin-sort: 의존성 알파벳 정렬
poetry self add poetry-plugin-sort

# poetry-dynamic-versioning: Git 태그 기반 자동 버전 관리
poetry self add poetry-dynamic-versioning

5.2 플러그인 관리

# 설치된 플러그인 목록
poetry self show plugins

# 플러그인 제거
poetry self remove poetry-plugin-sort

6 poetry check: 프로젝트 검증

pyproject.toml의 유효성을 검사한다.

poetry check

# 출력 예시 (문제 있을 때):
# Warning: A wildcard Python constraint is used.
# Error: 'description' is a required field.

배포 전이나 CI에서 실행하면 설정 오류를 조기에 발견할 수 있다.

7 poetry search: 패키지 검색

PyPI에서 패키지를 검색한다.

poetry search pandas
# 출력 예시:
# pandas (2.0.3) - Powerful data structures for data analysis
# pandas-stubs (2.0.3.230814) - Type annotations for pandas

노트

Poetry 1.6+ 이후 poetry search가 비활성화된 경우가 있다. PyPI API 변경 때문이며, pypi.org에서 직접 검색하는 것이 더 정확하다.

8 환경변수를 통한 설정

CI/CD 환경에서 설정 파일 대신 환경변수로 Poetry를 제어할 수 있다.

# 가상환경 생성 비활성화 (Docker에서 유용)
export POETRY_VIRTUALENVS_CREATE=false

# PyPI 토큰 설정
export POETRY_PYPI_TOKEN_PYPI=pypi-XXXXXXXXXXXXXX

# 사설 저장소 인증
export POETRY_HTTP_BASIC_PRIVATE_USERNAME=user
export POETRY_HTTP_BASIC_PRIVATE_PASSWORD=pass

# 병렬 설치 비활성화 (디버깅용)
export POETRY_INSTALLER_PARALLEL=false

환경변수 네이밍 규칙: POETRY_ + 설정키를 대문자로 변환하고 .을 _로 교체.

설정키	환경변수
`virtualenvs.create`	`POETRY_VIRTUALENVS_CREATE`
`virtualenvs.in-project`	`POETRY_VIRTUALENVS_IN_PROJECT`
`http-basic.private.username`	`POETRY_HTTP_BASIC_PRIVATE_USERNAME`

9 요약

명령어	역할
`poetry config --list`	전체 설정 확인
`poetry config key value`	설정 변경
`poetry config key value --local`	프로젝트별 설정
`poetry source add name url`	패키지 소스 추가
`poetry cache clear pypi --all`	캐시 삭제
`poetry self update`	Poetry 업데이트
`poetry self add plugin`	플러그인 설치
`poetry check`	pyproject.toml 검증