PowerShell에서 Python Poetry 설치 및 PyPI 배포 가이드

작성일: 2025-04-29

📌 개요

이 글은 Windows 환경에서 PowerShell을 사용하여 Python의 패키지 관리 도구인 Poetry를 설치하고, 이를 활용해 PyPI에 패키지를 배포하는 과정을 자세히 안내합니다. 또한, 설치 후 생성되는 폴더인 pypoetry의 의미도 함께 설명합니다.

1. Poetry란?

Poetry는 Python의 패키지 및 의존성 관리, 빌드, 배포 등을 현대적으로 통합 관리할 수 있게 해주는 도구입니다. setup.py, requirements.txt, virtualenv, twine 등의 기능을 하나로 통합해 줍니다.

주요 기능

• 프로젝트 생성 및 관리
• 의존성 자동 설치 및 잠금(lock)
• 가상환경 자동 생성
• PyPI 배포 지원

2. PowerShell에서 Poetry 설치 방법

1️⃣ Python 설치 확인

python --version

없다면 https://www.python.org/downloads/windows/ 에서 설치하고, "Add Python to PATH" 옵션을 체크하세요.

2️⃣ Poetry 설치

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

3️⃣ 환경 변수 설정

poetry 명령이 인식되지 않는다면 다음 경로를 환경 변수에 추가합니다:

%USERPROFILE%\AppData\Roaming\Python\Scripts\

4️⃣ 설치 확인

poetry --version

3. Poetry를 사용한 PyPI 배포

1️⃣ 프로젝트 생성

poetry new my_package
cd my_package

2️⃣ pyproject.toml 설정 예시

[tool.poetry]
name = "my-package"
version = "0.1.0"
description = "A simple example package"
authors = ["홍길동 <hong@example.com>"]

[tool.poetry.dependencies]
python = "^3.8"

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

3️⃣ 패키지 빌드

poetry build

4️⃣ PyPI 토큰 설정 및 배포

poetry config pypi-token.pypi your_token_here
poetry publish --build

TestPyPI를 사용할 경우:

poetry config repositories.test-pypi https://test.pypi.org/legacy/
poetry publish --build -r test-pypi

4. C:\Users\<사용자>\AppData\Roaming\pypoetry 폴더란?

Poetry 설치 후 생성되는 pypoetry 폴더는 사용자 설정, 캐시, 가상환경, 인증 정보 등을 저장하는 디렉토리입니다.

주요 구성

삭제하면 초기화되지만, 문제가 없으면 그대로 두는 것이 좋습니다.

✅ 요약

📎 참고 링크

• Poetry 공식 문서
• PyPI
• Python 설치

🔧 VS Code에서 Poetry 가상환경 제대로 연동하는 방법 (pyenv + launch.json 설정 포함)

Python 프로젝트를 관리할 때 Poetry는 더 이상 선택이 아닌 필수가 되어가고 있습니다. 하지만 VS Code와 Poetry를 연동할 때 인터프리터 감지가 안 되거나, 실행이 안 되는 불편함을 겪은 분들이 많을 거예요.

이 글에서는 pyenv + Poetry를 사용하는 프로젝트를 VS Code에서 완벽하게 연동하는 방법을 정리합니다. 특히 launch.json을 통해 디버깅까지 깔끔하게 설정하는 법도 다룹니다.

1️⃣ Poetry 가상환경 기본 구조 이해하기

Poetry는 기본적으로 가상환경을 아래 위치에 생성합니다:

# 프로젝트 외부 경로 (기본 설정)
C:\Users\<사용자>\AppData\Local\pypoetry\Cache\virtualenvs\<project-name>-<hash>

이로 인해 VS Code는 인터프리터를 자동으로 인식하지 못하는 경우가 많습니다.

2️⃣ Poetry 가상환경을 VS Code에서 인식시키는 방법

✅ 방법 1: 가상환경을 프로젝트 내부 .venv/에 생성 (강력 추천)

poetry config virtualenvs.in-project true
poetry env remove python      # (기존 가상환경 제거)
poetry install                # 가상환경 재생성 (.venv 생성됨)

이후 VS Code를 열면 .venv/Scripts/python.exe가 자동으로 감지됩니다.

✅ 방법 2: 수동으로 인터프리터 지정

1. 터미널에서 가상환경 경로 확인:

poetry env info --path

2. VS Code에서 Ctrl+Shift+P → Python: Select Interpreter
3. 위 경로의 Scripts/python.exe 선택

✅ 방법 3: .vscode/settings.json 직접 작성

{
  "python.defaultInterpreterPath": "C:\\Users\\flami\\AppData\\Local\\pypoetry\\Cache\\virtualenvs\\ice-breaker-xxxx\\Scripts\\python.exe"
}

3️⃣ launch.json으로 Poetry 가상환경에서 .py 자동 실행

VS Code의 launch.json을 설정하면 F5만 눌러도 poetry 가상환경에서 스크립트를 실행할 수 있습니다.

📁 예시 구조

ice_breaker/
├── main.py
└── .vscode/
    └── launch.json

📄 launch.json 예시

{
  "version": "0.2.0",
  "configurations": [
    {
      "name": "Poetry Run: main.py",
      "type": "python",
      "request": "launch",
      "program": "${workspaceFolder}/main.py",
      "console": "integratedTerminal",
      "args": ["--debug"],

      "python": "C:\\Users\\flami\\AppData\\Local\\pypoetry\\Cache\\virtualenvs\\ice-breaker-xxxx\\Scripts\\python.exe"
    }
  ]
}

4️⃣ Poetry 환경 진입 여부 확인하는 방법

Poetry 가상환경에 들어와 있는지 확인하려면 다음 명령들을 활용하세요:

poetry env info --path
poetry env info
where python

또는 Python에서:

import sys
print(sys.prefix)

✅ 마무리 체크리스트

✨ 마치며

Poetry와 VS Code를 연동하면 패키지 관리 + 실행 + 디버깅까지 깔끔하게 통합됩니다.
이번 글의 설정대로만 따라 하면, 더 이상 “왜 VS Code에서 가상환경이 안 잡혀요?” 같은 고민은 끝입니다.