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에서 가상환경이 안 잡혀요?” 같은 고민은 끝입니다.

중첩 함수란 하나의 함수 내에서 다른 함수를 정의하는 것을 말합니다.  중첩 함수는 해당 부모 함수 내부에서만 유효하며 외부에서 직접 접근할 수 없습니다. 중첩 함수는 주로 부모 함수 내에서만 필요한 보조 작업을 수행하기 위해 사용됩니다.

def outer_function():
    def inner_function():
        return "This is inner function."
    
    return inner_function()

# outer_function을 호출하여 중첩된 inner_function을 실행합니다.
result = outer_function()
print(result)  # 출력: This is inner function.

위의 예시에서 inner_function은 outer_function 내에서만 정의되었습니다. 이는 outer_function 외부에서는 직접적으로 접근할 수 없음을 의미합니다.

타입 힌트는 코드의 가독성을 높이고 협업 효율성을 향상시키는데 도움이 됩니다.

파이썬은 동적 프로그래밍 언어로, 변수의 자료형이 중간에 변경될 수 있습니다. 하지만 큰 프로젝트에서는 변수의 타입을 명시적으로 지정하는 것이 좋습니다. 이때 타입 힌트를 사용하면 변수나 함수의 인자, 반환값에 대한 타입을 명시할 수 있습니다.

기본 사용법 

name: str = "John Doe"
age: int = 30
email: list = ["john@example.com", "jeny@gmail.com"]

함수에 타입 힌트

def greeting(name: str) -> str:
	return "Hello "  + name

typing 모듈 활용

파이썬의 typing 모듈을 사용하면 더 구체적인 타입 힌트를 작성할 수 있습니다. 

from typing import List, Set, Dict, Tuple

nums_list: List[int] = [1, 2, 3]
nums_set: Set[int] = {1, 2, 3}
students: Dict[int, str] = {1: "Alice", 2: "Bob"}
student: Tuple[int, str, List[float]] = (19, "John", [178.1])

class User:
    ...

def find_user(user_id: str) -> User:
    ...

def create_user(user: User) -> User:
    ...