1 가상환경이 필요한 이유

Python은 라이브러리를 전역(global)에 설치하면 프로젝트 간 버전 충돌이 발생한다.

전역 Python 환경
├── 프로젝트 A: numpy==1.24 필요
└── 프로젝트 B: numpy==1.21 필요
→ 둘 중 하나만 설치 가능 → 충돌!

가상환경은 프로젝트마다 독립적인 Python 환경을 만들어 이 문제를 해결한다.

프로젝트 A/.venv/  → numpy==1.24 (독립)
프로젝트 B/.venv/  → numpy==1.21 (독립)
→ 충돌 없음

Poetry는 가상환경 생성과 관리를 자동으로 처리한다.

2 poetry install

poetry install은 Poetry의 가장 핵심 명령어다. pyproject.toml과 poetry.lock을 기반으로 가상환경을 생성하고 모든 의존성을 설치한다.

# 기본 설치 (모든 그룹 포함)
poetry install

# 특정 그룹 제외
poetry install --without dev,docs

# 필수 의존성만 설치
poetry install --only main

# lock 파일 업데이트 없이 설치 (CI/CD에 적합)
poetry install --no-update

2.1 동작 순서

1. poetry.lock 확인 (없으면 pyproject.toml에서 생성)
       ↓
2. 가상환경 확인 (없으면 자동 생성)
       ↓
3. lock 파일 기준으로 패키지 설치
       ↓
4. 현재 프로젝트를 editable 모드로 설치

4단계 덕분에 import my_project로 현재 프로젝트 코드를 바로 사용할 수 있다.

3 코드 실행: poetry run vs poetry shell

3.1 poetry run (권장)

가상환경을 활성화하지 않고도 가상환경 내에서 명령을 실행한다.

# Python 스크립트 실행
poetry run python main.py

# pytest 실행
poetry run pytest

# 코드 포매터 실행
poetry run black .

# 한 줄 Python 코드 실행
poetry run python -c "import pandas; print(pandas.__version__)"

장점: 명시적이고, 셸 상태를 변경하지 않아 깔끔하다.

3.2 poetry env activate (Poetry 2.x 권장)

Poetry 2.x에서 poetry shell은 deprecated되었다. 대신 poetry env activate를 사용한다.

# Linux/Mac: 가상환경 활성화
eval $(poetry env activate)

# PowerShell: 가상환경 활성화
poetry env activate | Invoke-Expression

# 이후 일반 Python 명령어 사용 가능
python main.py
pytest
black .

# 셸 종료
deactivate

경고

poetry shell은 Poetry 2.x에서 deprecated되었다. 기존 스크립트나 문서에서 poetry shell을 사용하고 있다면 eval $(poetry env activate)로 교체한다.

3.3 poetry shell (deprecated)

Poetry 1.x에서 사용하던 방식으로, 가상환경을 활성화한 새 셸을 연다.

# (deprecated) 가상환경 셸 진입
poetry shell

3.4 비교

항목	`poetry run`	`poetry env activate`	`poetry shell` (deprecated)
셸 상태 변경	없음	현재 셸에 활성화	새 셸 생성
사용법	명령 앞에 `poetry run` 붙임	한번 활성화 후 자유롭게 사용	한번 활성화 후 자유롭게 사용
적합한 상황	단일 명령, 스크립트, CI/CD	대화형 작업, 디버깅	Poetry 1.x 호환 필요 시

4 가상환경 설정

4.1 프로젝트 내부에 .venv 생성 (권장)

기본적으로 Poetry는 중앙 캐시 디렉토리에 가상환경을 생성한다. 프로젝트 폴더 안에 .venv를 생성하려면:

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

# 설정 확인
poetry config --list | grep virtualenvs

이렇게 하면:

my_project/
├── .venv/              ← 여기에 가상환경 생성
├── pyproject.toml
├── poetry.lock
└── src/

장점:

IDE(VS Code, PyCharm)가 자동으로 가상환경을 인식
프로젝트 삭제 시 가상환경도 함께 삭제
.gitignore에 .venv/ 추가하면 Git에서 제외

힌트

.venv/는 반드시 .gitignore에 추가해야 한다. 가상환경은 OS/아키텍처에 종속적이라 공유할 수 없다.

4.2 Python 버전 지정

특정 Python 버전으로 가상환경을 생성한다.

# 특정 버전 사용
poetry env use python3.11

# 또는 절대 경로로 지정
poetry env use /usr/bin/python3.11

# pyenv와 함께 사용
pyenv install 3.11
pyenv local 3.11
poetry env use python

5 가상환경 관리: poetry env

5.1 환경 정보 확인

# 현재 가상환경 정보
poetry env info

# 출력 예시:
# Virtualenv
# Python:         3.11.9
# Implementation: CPython
# Path:           /home/user/project/.venv
# Executable:     /home/user/project/.venv/bin/python
# Valid:          True
#
# Base
# Platform:   linux
# OS:         posix
# Python:     3.11.9
# Path:       /home/user/.pyenv/versions/3.11.9

# 경로만 확인
poetry env info --path

5.2 가상환경 목록

poetry env list

# 출력 예시:
# my-project-py3.11 (Activated)
# my-project-py3.10

5.3 가상환경 삭제

# 특정 환경 삭제
poetry env remove python3.11

# 현재 환경 삭제
poetry env remove python

# 모든 환경 삭제
poetry env remove --all

5.4 가상환경 재생성

문제가 생겼을 때 깨끗하게 다시 시작하는 방법:

# 1. 기존 환경 삭제
poetry env remove python

# 2. 새로 설치
poetry install

6 Poetry 주요 설정

# 현재 설정 확인
poetry config --list

설정	기본값	권장값	설명
`virtualenvs.in-project`	`false`	`true`	프로젝트 내 .venv 생성
`virtualenvs.create`	`true`	`true`	가상환경 자동 생성
`virtualenvs.prefer-active-python`	`false`	`true`	활성 Python 사용

# 권장 설정
poetry config virtualenvs.in-project true
poetry config virtualenvs.prefer-active-python true

7 시스템 Python vs pyenv

Python 환경 관리 도구를 선택하기 전에 두 개념의 차이를 먼저 이해한다.

7.1 시스템 Python

OS에 기본 설치된 Python이다. 보통 /usr/bin/python3에 위치하며, OS 내부 도구들이 의존하기도 한다.

버전이 OS에 종속된다 (Ubuntu 22.04 → 3.10, Ubuntu 24.04 → 3.12 등)
버전 변경이 어렵다 (apt로 다른 버전 설치는 가능하지만 관리가 번거롭다)
함부로 건드리면 OS 도구가 깨질 수 있다

7.2 pyenv

사용자 홈 디렉토리(~/.pyenv)에 Python을 별도로 설치하는 도구다. 시스템 Python과 완전히 독립적이다.

원하는 버전을 자유롭게 설치·삭제할 수 있다
프로젝트마다 다른 버전을 지정할 수 있다 (pyenv local 3.11)
시스템에 영향이 없다

간단히 말하면, 시스템 Python은 OS가 관리하는 것이고 pyenv는 내가 관리하는 것이다.

구분	시스템 Python	pyenv
설치 위치	`/usr/bin/python3`	`~/.pyenv/versions/`
버전 관리	OS 패키지 관리자	`pyenv install`
프로젝트별 버전	어려움	`pyenv local`로 간단
수정 시 위험	OS 도구 영향 있음	없음

Windows에서는 시스템 Python 대신 Microsoft Store Python 또는 공식 installer Python이 같은 역할을 한다. pyenv-win이 동일한 기능을 제공한다.

8 pyenv + Poetry 조합

pyenv로 Python 버전을 관리하고, Poetry로 가상환경과 의존성을 관리하는 것이 가장 깔끔한 구성이다.

# 1. pyenv로 Python 설치
pyenv install 3.11

# 2. 프로젝트에서 Python 버전 고정
cd my_project
pyenv local 3.11

# 3. Poetry가 해당 버전으로 가상환경 생성
poetry env use python
poetry install

도구	역할
pyenv	Python 인터프리터 버전 관리 (3.9, 3.11, 3.12 등)
Poetry	가상환경 생성 + 패키지 의존성 관리

9 VS Code 연동

프로젝트 내부에 .venv를 생성하면 VS Code가 자동으로 인식한다. 수동으로 설정하려면:

Ctrl+Shift+P → “Python: Select Interpreter”
.venv/bin/python (또는 .venv\Scripts\python.exe) 선택

또는 .vscode/settings.json에 추가:

{
    "python.defaultInterpreterPath": "${workspaceFolder}/.venv/bin/python"
}

10 요약

명령어	역할
`poetry install`	lock 기준 환경 구성
`poetry run <cmd>`	가상환경에서 명령 실행
`poetry shell`	가상환경 셸 진입
`poetry env info`	환경 정보 확인
`poetry env use python3.11`	Python 버전 변경
`poetry env list`	환경 목록 확인
`poetry env remove python`	환경 삭제
`poetry config virtualenvs.in-project true`	.venv 위치 설정