정리 목차

Poetry소개
- 핵심 개념
- 3가지 특징
Poetry 설치 및 첫 프로젝트
- 설치 (pipx, curl)
- 프로젝트 생성 (poetry new)
- 프로젝트 구조 이해
기본 의존성 관리
- 패키지 추가 (poetry add)
- 패키지 제거 (poetry remove)
- 버전 제약 문법 (^, ~, ==)
가상환경 사용
- poetry install 이해
- poetry shell vs poetry run
- 의존성 잠금 (poetry.lock)
프로젝트 구성
- pyproject.toml 상세 이해
- 스크립트 진입점 (script entry point)
- 개발 의존성 분리 (--group dev)

Poetry 설치 및 첫 프로젝트

각 OS별 설치 방법과 설치 후 검증, 그리고 첫 프로젝트 생성까지 다룬다.

설치 방법 비교

방법	OS	난이도	권장도	장점	단점
pipx	Windows, macOS, Linux	중간	⭐⭐⭐⭐⭐	격리된 환경, 버전 관리 용이	pipx 설치 필요
curl	macOS, Linux	초급	⭐⭐⭐⭐	한 줄 설치, 공식 권장	Windows 미지원
pip	모든 OS	초급	⭐⭐⭐	간단, 기존 pip 활용	전역 설치 (권장 안 함)
Homebrew	macOS, Linux	초급	⭐⭐⭐	간단, 패키지 관리 통합	macOS/Linux만 지원

Windows 개발환경 설정 (권장)

Windows에서 범용적인 Python 개발환경을 구축하려면 pyenv + Poetry 조합이 최적입니다.
pyenv로 Python 버전을 관리하고, Poetry로 패키지 의존성을 관리하여 프로젝트별 독립적인 환경을 유지할 수 있습니다.

PowerShell Policy 적용

Windows에서 PowerShell 스크립트 실행을 허용하기 위해 필요합니다.

기본적으로 Windows는 보안상 외부 스크립트 실행을 제한하는데, pyenv와 poetry 같은 도구들이 PowerShell 스크립트를 사용하므로 이 제한을 해제해야 합니다.

설정 방법:
1. Windows 키 → PowerShell을 관리자 권한으로 실행
2. 다음 명령어 입력:

Set-ExecutionPolicy RemoteSigned -Scope CurrentUser -Force

적용 완료 후 PowerShell을 종료했다가 다시 실행

단계 2: Git 설치 (선택사항)

실습 코드를 GitHub에서 다운로드하고 버전 관리를 위해 필요합니다.

64-bit Git for Windows Setup 다운로드: https://git-scm.com/download/win
add a git bash profile to windows terminal 옵션 선택
설치 후 확인:

git --version

단계 3: pyenv 설치

pyenv는 여러 Python 버전을 관리하기 위한 도구입니다.
배포자가 만든 가상환경이 아니라, Python 버전 관리 도구입니다.

특정 프로젝트가 Python 3.11을 요구할 때, 시스템의 기본 Python과 충돌 없이 원하는 버전을 사용할 수 있게 합니다.

pyenv-win 설치:

git clone https://github.com/pyenv-win/pyenv-win.git "$env:USERPROFILE\.pyenv"

중요: pyenv는 Python 인터프리터 버전만 관리합니다.
- pyenv의 역할: Python 인터프리터 버전 관리 (3.8, 3.9, 3.11 등)
- Poetry의 역할: 가상환경 생성 + 패키지 의존성 관리

실제 작업 흐름:
1. pyenv로 Python 3.11 설치 및 선택
2. Poetry로 해당 Python 버전 기반의 가상환경 생성 + 패키지 관리

단계 4: 환경변수 추가

pyenv가 시스템 어디서든 실행될 수 있도록 PATH 환경변수에 pyenv 경로를 추가합니다.

PYENV 환경변수 설정:
PowerShell에서 다음 명령어 복사 후 실행:

[System.Environment]::SetEnvironmentVariable('PYENV', $env:USERPROFILE + "\.pyenv\pyenv-win\", "User")  
[System.Environment]::SetEnvironmentVariable('PYENV_ROOT', $env:USERPROFILE + "\.pyenv\pyenv-win\", "User")  
[System.Environment]::SetEnvironmentVariable('PYENV_HOME', $env:USERPROFILE + "\.pyenv\pyenv-win\", "User")

PATH 환경변수 설정:

[System.Environment]::SetEnvironmentVariable('PATH', $env:USERPROFILE + "\.pyenv\pyenv-win\bin;" + $env:USERPROFILE + "\.pyenv\pyenv-win\shims;" + [System.Environment]::GetEnvironmentVariable('PATH', "User"), "User")

적용:
- 현재 PowerShell을 종료했다가 다시 실행
- 이후 pyenv 명령어가 어디서든 실행 가능합니다.

설치 확인:

pyenv

명령어가 실행되고 헬프 메시지가 나타나면 성공입니다.

단계 5: Python 설치

특정 프로젝트가 요구하는 Python 버전을 설치합니다.
최신 버전보다는 검증된 안정 버전을 사용하여 호환성 문제를 방지합니다.

Python 3.11 설치:

pyenv install 3.11

시스템 기본 Python 버전 설정:

pyenv global 3.11

버전 확인:

python --version  
# 출력: Python 3.11.9 (또는 3.11.11)

단계 6: Poetry 설치

프로젝트 실습을 위해 많은 패키지를 설치해야 하는데, 각 패키지들의 의존성 관리가 매우 복잡합니다.

Poetry는:
- 패키지 의존성을 자동으로 해결
- 가상환경을 자동 관리
- 패키지 충돌 문제 방지
- pyproject.toml과 poetry.lock 파일로 정밀한 의존성 관리

Poetry 설치:

pip3 install poetry==1.8.5

버전 확인:

poetry --version  
# 출력: Poetry (version 1.8.5)

공식 권장: pipx를 이용한 설치 (다른 방법)

Windows에서 pyenv 없이 Poetry만 설치하려면 pipx를 사용할 수 있습니다.

1단계: pipx 설치

Windows (PowerShell 관리자 권한):

python -m pip install --user pipx  
python -m pipx ensurepath

macOS:

brew install pipx  
pipx ensurepath

Linux (Ubuntu/Debian):

sudo apt-get install pipx  
pipx ensurepath

Linux (Fedora/RHEL):

sudo dnf install pipx  
pipx ensurepath

2단계: pipx 경로 확인

pipx ensurepath를 실행한 후 터미널을 재시작

# 경로 확인  
echo $PATH  
# 결과: ~/.local/bin이 포함되어야 함

3단계: Poetry 설치

pipx install poetry

4단계: 설치 검증

poetry --version  
# 출력: Poetry (version 1.8.x)

Problem: poetry: command not found 오류 발생 시

# 수동으로 PATH에 추가 (Linux/macOS)  
export PATH="$HOME/.local/bin:$PATH"  

# 또는 ~/.bashrc / ~/.zshrc에 추가  
echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.bashrc  
source ~/.bashrc

대안 1: curl을 이용한 설치 (macOS, Linux)

공식 설치 스크립트를 이용한 가장 빠른 방법:

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

설치 후 PATH 설정:

# ~/.bashrc 또는 ~/.zshrc에 추가  
export PATH="$HOME/.local/bin:$PATH"  

# 적용  
source ~/.bashrc  # (또는 source ~/.zshrc)

검증:

poetry --version

대안 2: pip를 이용한 설치 (모든 OS)

주의: pip를 이용한 전역 설치는 권장하지 않음 (의존성 충돌 위험).

필요한 경우만 사용:

pip install poetry

검증:

poetry --version

대안 3: Homebrew를 이용한 설치 (macOS, Linux)

macOS:

brew install poetry

Homebrew (Linux):

brew install poetry

검증:

poetry --version

설치 후 초기 설정

가상환경 생성 위치 설정 (선택사항)

기본적으로 Poetry는 {project-root}/.venv에 가상환경을 생성합니다. 다른 위치를 원하면:

poetry config virtualenvs.in-project true

확인:

poetry config --list  
# 출력: virtualenvs.in-project = true

Python 버전 설정 (선택사항)

특정 Python 버전을 사용하도록 설정:

poetry env use /usr/bin/python3.11

또는 버전 번호로:

poetry env use 3.11

첫 번째 프로젝트 생성

새 프로젝트 생성

poetry new my_first_project

생성되는 구조:

my_first_project/  
├── pyproject.toml           # 프로젝트 설정 파일  
├── README.md  
├── my_first_project/        # 패키지 폴더  
│   └── __init__.py  
├── tests/  
│   └── __init__.py  
└── .gitignore

프로젝트 폴더로 이동

cd my_first_project

pyproject.toml 파일 이해

생성된 pyproject.toml:

[tool.poetry]  
name = "my-first-project"           # 프로젝트 이름  
version = "0.1.0"                   # 버전  
description = ""                    # 설명  
authors = ["Your Name <you@example.com>"]  

[tool.poetry.dependencies]  
python = "^3.9"                     # Python 버전 제약  

[tool.poetry.group.dev.dependencies]  
pytest = "^7.4.0"                   # 개발용 의존성  

[build-system]  
requires = ["poetry-core"]  
build-backend = "poetry.core.masonry.api"

기본 워크플로우

패키지 추가

# 일반 의존성 추가  
poetry add requests numpy pandas  

# 개발용 의존성 추가 (--group dev)  
poetry add --group dev pytest black mypy

결과: pyproject.toml 자동 업데이트 + poetry.lock 생성

의존성 설치

poetry install

이 명령은:
1. poetry.lock 파일 읽기 (또는 생성)
2. .venv 가상환경 생성
3. 모든 의존성 설치

코드 실행

방법 1: poetry run 사용 (권장)

poetry run python -c "import requests; print(requests.__version__)"

방법 2: 가상환경 활성화

poetry shell              # 가상환경 활성화  
python main.py  
deactivate               # 또는 exit로 종료

간단한 예제 작성

my_first_project/main.py 생성:

import requests  

def fetch_data(url):  
    """웹 요청을 통해 데이터 가져오기"""  
    response = requests.get(url)  
    return response.json()  

if __name__ == "__main__":  
    data = fetch_data("https://api.github.com/users/github")  
    print(f"GitHub Name: {data['name']}")  
    print(f"Public Repos: {data['public_repos']}")

실행:

poetry run python my_first_project/main.py

설치 문제 해결

문제 1: `poetry: command not found`

원인: PATH에 Poetry 설치 경로가 포함되지 않음

해결:

# 1. Poetry 설치 경로 확인  
pipx list  

# 2. PATH에 수동으로 추가  
export PATH="$HOME/.local/bin:$PATH"  

# 3. 영구 설정: ~/.bashrc 또는 ~/.zshrc에 추가  
echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.bashrc  
source ~/.bashrc

문제 2: Permission denied (권한 문제)

Windows:

# PowerShell을 관리자 권한으로 실행 후  
python -m pip install --user pipx

macOS/Linux:

# sudo 사용 금지 (권장하지 않음)  
# 대신 아래 시도  
pipx ensurepath  
export PATH="$HOME/.local/bin:$PATH"

문제 3: Python 버전 불일치

# 설치된 Python 확인  
python --version  

# Poetry가 사용하는 Python 확인  
poetry env info  

# 특정 Python 버전 사용하도록 설정  
poetry env use python3.11

문제 4: pip 버전 오래됨

# pip 업그레이드  
pip install --upgrade pip  

# 그 후 pipx 설치  
python -m pip install --user pipx

설치 후 추가 설정 (선택사항)

pip 버전 고정

Poetry는 내부적으로 pip를 사용
호환성을 위해 pip 업그레이드를 억제할 수 있다:

poetry config virtualenvs.options.always-copy false

프로젝트별 가상환경 생성

모든 프로젝트에서 프로젝트 폴더 내에 .venv 생성:

poetry config virtualenvs.in-project true

Python 캐시 설정

Poetry가 다운로드한 패키지 캐시 위치 변경 (선택사항):

poetry config cache-dir /custom/cache/path

PyPI 토큰 설정 (배포 시)

나중에 PyPI에 배포할 계획이면:

poetry config pypi-token.pypi your-api-token-here

정리 목차

Poetry 설치 및 첫 프로젝트

설치 방법 비교

Windows 개발환경 설정 (권장)

PowerShell Policy 적용

단계 2: Git 설치 (선택사항)

단계 3: pyenv 설치

단계 4: 환경변수 추가

단계 5: Python 설치

단계 6: Poetry 설치

공식 권장: pipx를 이용한 설치 (다른 방법)

1단계: pipx 설치

2단계: pipx 경로 확인

3단계: Poetry 설치

4단계: 설치 검증

대안 1: curl을 이용한 설치 (macOS, Linux)

대안 2: pip를 이용한 설치 (모든 OS)

대안 3: Homebrew를 이용한 설치 (macOS, Linux)

설치 후 초기 설정

가상환경 생성 위치 설정 (선택사항)

Python 버전 설정 (선택사항)

첫 번째 프로젝트 생성

새 프로젝트 생성

프로젝트 폴더로 이동

pyproject.toml 파일 이해

기본 워크플로우

패키지 추가

의존성 설치

코드 실행

간단한 예제 작성

설치 문제 해결

문제 1: poetry: command not found

문제 2: Permission denied (권한 문제)

문제 3: Python 버전 불일치

문제 4: pip 버전 오래됨

설치 후 추가 설정 (선택사항)

pip 버전 고정

프로젝트별 가상환경 생성

Python 캐시 설정

PyPI 토큰 설정 (배포 시)

문제 1: `poetry: command not found`