본문으로 건너뛰기
Advertisement

Ch 1.5 가상환경과 패키지 관리

파이썬 프로젝트를 전문적으로 관리하려면 가상환경과 패키지 관리가 필수입니다. 이 챕터에서는 venv부터 현대적인 uv까지 실무에서 사용하는 도구들을 알아봅니다.

1. 가상환경이 필요한 이유​

파이썬 패키지를 시스템 전체에 설치하면 문제가 발생합니다.

프로젝트 A: Django 4.2 필요
프로젝트 B: Django 3.2 필요  ← 같은 이름, 다른 버전!
시스템 전체 패키지: Django ??? (버전 충돌!)

가상환경(Virtual Environment) 은 프로젝트별로 독립된 파이썬 환경을 만들어 이 문제를 해결합니다.

프로젝트 A/ → .venv/ → Django 4.2
프로젝트 B/ → .venv/ → Django 3.2
각자 독립된 환경! 충돌 없음!

2. venv — 파이썬 내장 가상환경​

생성​

# 프로젝트 디렉토리에서 실행
python3 -m venv .venv

# 디렉토리 구조
# .venv/
# ├── bin/        (macOS/Linux) 또는 Scripts/ (Windows)
# │   ├── python3
# │   ├── pip
# │   └── activate
# ├── lib/
# │   └── python3.12/
# │       └── site-packages/
# └── pyvenv.cfg

활성화 / 비활성화​

# === macOS / Linux ===
source .venv/bin/activate
# 프롬프트 변경: (.venv) user@machine:~/project$

# === Windows (CMD) ===
.venv\Scripts\activate.bat

# === Windows (PowerShell) ===
.venv\Scripts\Activate.ps1
# PowerShell 실행 정책 오류 시:
# Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser

# === 활성화 확인 ===
which python3  # macOS/Linux: .venv/bin/python3
where python   # Windows: .venv\Scripts\python.exe

# === 비활성화 ===
deactivate

활성화 후 작업​

# 가상환경 활성화 후 pip 업그레이드
(.venv) pip install --upgrade pip

# 패키지 설치
(.venv) pip install requests pandas

# 설치된 패키지 확인
(.venv) pip list

3. pip — 파이썬 패키지 관리자​

기본 명령어​

# 패키지 설치
pip install requests
pip install "django>=4.2"       # 최소 버전 지정
pip install "django==4.2.7"     # 정확한 버전 지정
pip install "django>=4.0,<5.0"  # 버전 범위 지정

# 패키지 업그레이드
pip install --upgrade requests

# 패키지 제거
pip uninstall requests
pip uninstall requests -y  # 확인 없이 제거

# 설치된 패키지 목록
pip list
pip list --outdated  # 업데이트 가능한 패키지

# 패키지 정보 조회
pip show requests
# Name: requests
# Version: 2.31.0
# Summary: Python HTTP for Humans.
# Home-page: https://requests.readthedocs.io
# ...

# 패키지 검색 (PyPI에서)
pip index versions django  # django의 모든 버전 조회

4. requirements.txt​

프로젝트의 의존성을 파일로 관리합니다.

생성​

# 현재 설치된 패키지를 requirements.txt로 저장
pip freeze > requirements.txt

# requirements.txt 내용 예시
# Django==4.2.7
# requests==2.31.0
# pandas==2.1.3
# numpy==1.26.2

사용​

# requirements.txt의 패키지 모두 설치
pip install -r requirements.txt

# 다른 환경에서 동일한 환경 재현
python3 -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt

의존성 분리 (dev / prod)​

# requirements.txt — 프로덕션 의존성
# Django==4.2.7
# gunicorn==21.2.0

# requirements-dev.txt — 개발 의존성
# -r requirements.txt  # 프로덕션 의존성 포함
# pytest==7.4.3
# black==23.12.1
# mypy==1.7.1

# 개발 환경 설치
pip install -r requirements-dev.txt

5. pyproject.toml — 현대적 프로젝트 설정​

PEP 517/518에서 정의된 현대적인 파이썬 프로젝트 설정 파일입니다. requirements.txt보다 더 풍부한 메타데이터를 관리합니다.

# pyproject.toml
[build-system]
requires = ["hatchling"]
build-backend = "hatchling.build"

[project]
name = "my-project"
version = "1.0.0"
description = "나의 파이썬 프로젝트"
requires-python = ">=3.12"

# 프로덕션 의존성
dependencies = [
    "requests>=2.31.0",
    "fastapi>=0.104.0",
    "pydantic>=2.5.0",
]

# 선택적 의존성 그룹
[project.optional-dependencies]
dev = [
    "pytest>=7.4.0",
    "pytest-cov>=4.1.0",
    "black>=23.12.0",
    "ruff>=0.1.0",
    "mypy>=1.7.0",
]
docs = [
    "mkdocs>=1.5.0",
    "mkdocs-material>=9.4.0",
]

# 도구 설정
[tool.black]
line-length = 88
target-version = ["py312"]

[tool.ruff]
line-length = 88
target-version = "py312"

[tool.mypy]
python_version = "3.12"
strict = true
# pyproject.toml로 설치
pip install .              # 기본 의존성
pip install ".[dev]"       # dev 의존성 포함
pip install ".[dev,docs]"  # 여러 그룹 포함

6. uv — 차세대 파이썬 패키지 매니저​

uv는 Rust로 작성된 초고속 파이썬 패키지 관리자입니다. pip보다 10~100배 빠릅니다.

설치​

# macOS / Linux
curl -LsSf https://astral.sh/uv/install.sh | sh

# Windows (PowerShell)
powershell -c "irm https://astral.sh/uv/install.ps1 | iex"

# pip으로 설치
pip install uv

uv 기본 사용법​

# 가상환경 생성
uv venv                    # .venv 생성
uv venv --python 3.12      # 버전 지정

# 패키지 설치 (pip보다 훨씬 빠름)
uv pip install requests
uv pip install -r requirements.txt

# 새 프로젝트 초기화
uv init my-project
cd my-project

# 의존성 추가 (pyproject.toml 자동 업데이트)
uv add fastapi
uv add --dev pytest black ruff

# 의존성 제거
uv remove requests

# 프로젝트 실행
uv run python main.py
uv run pytest

uv 속도 비교​

# pip — 느림
time pip install pandas numpy scipy matplotlib
# real: 45.3s

# uv — 초고속 (캐시 활용 시 더 빠름)
time uv pip install pandas numpy scipy matplotlib
# real: 2.1s
고수 팁: .python-version 파일, .venv 깃 무시, 의존성 그룹 분리

.python-version 파일 (pyenv 사용 시 자동 생성):

# 프로젝트 디렉토리에서
echo "3.12.3" > .python-version

# 또는 pyenv 명령으로
pyenv local 3.12.3

이 파일이 있으면 해당 디렉토리에서 자동으로 지정된 파이썬 버전이 사용됩니다.

.gitignore에 .venv 추가 (가상환경은 절대 git에 포함하면 안 됩니다):

# .gitignore
.venv/
venv/
env/
__pycache__/
*.pyc
*.pyo
*.pyd
.Python
*.egg-info/
dist/
build/
.mypy_cache/
.ruff_cache/
.pytest_cache/

uv로 의존성 그룹 관리 (실무 권장 패턴):

# pyproject.toml
[project]
name = "my-api"
dependencies = [
    "fastapi>=0.104.0",
    "uvicorn>=0.24.0",
    "pydantic>=2.5.0",
    "sqlalchemy>=2.0.0",
]

[project.optional-dependencies]
dev = ["pytest", "pytest-asyncio", "httpx", "black", "ruff", "mypy"]
prod = ["gunicorn", "sentry-sdk"]
# 개발 환경
uv sync --extra dev

# 프로덕션 환경
uv sync --extra prod

가상환경과 패키지 관리를 마스터했습니다. 다음 챕터(Ch 2)에서는 파이썬의 기본 데이터 타입과 변수를 깊이 있게 다루겠습니다.

Advertisement
Advertisement