2강. Python 가상환경과 패키지 관리

?1. 이번 강의에서 해결할 문제

컴퓨터 전체에 패키지를 설치하면 프로젝트마다 필요한 버전이 충돌합니다. game-ranking-api 전용 가상환경과 의존성 파일을 만듭니다.

✓2. 학습 목표

✓이 강의를 마치면

• Python 3.13 이상인지 확인하고 .venv를 생성합니다.
• 가상환경 안의 Python과 pip를 구분합니다.
• FastAPI, Pydantic v2, SQLAlchemy 2.x의 버전 범위를 기록합니다.

◇3. 핵심 개념

가상환경은 프로젝트 전용 Python 실행 파일과 설치 경로를 만듭니다. Python 3.13의 venv는 기본적으로 .gitignore도 생성합니다. 활성화는 편의 기능이며, 문제가 생기면 .venv\Scripts\python.exe처럼 실행 파일을 직접 호출할 수 있습니다. 공식 설치 방식은 fastapi[standard] 계열이며 이 과정은 Cloud CLI를 제외한 표준 의존성으로 Uvicorn, HTTPX, form parsing을 함께 설치합니다.

</>4. 단계별 코드 예시

파일 경로: game-ranking-api/requirements.txt

requirements.txt

fastapi[standard-no-fastapi-cloud-cli]
pydantic>=2,<3
sqlalchemy>=2,<3
python-dotenv>=1,<2
alembic
psycopg[binary]>=3,<4
pwdlib[argon2]
pyjwt
pytest
httpx

파일 경로: game-ranking-api/.gitignore

.gitignore

.venv/
__pycache__/
*.py[cod]
.env
*.db
.pytest_cache/

실행 위치: game-ranking-api/

py -3.13 --version
py -3.13 -m venv .venv
.\.venv\Scripts\Activate.ps1
python -m pip install --upgrade pip
python -m pip install -r requirements.txt
python -m pip check

macOS와 Linux에서는 source .venv/bin/activate를 사용합니다.

→5. 코드가 동작하는 이유

python -m pip는 현재 선택된 Python에 패키지를 설치합니다. >=2,<3은 Pydantic과 SQLAlchemy의 현재 주 버전을 유지하면서 호환되는 수정 버전을 받을 수 있게 합니다. 실제 배포 재현이 필요할 때 검증된 환경에서 python -m pip freeze > requirements.lock.txt로 잠급니다.

!6. 자주 하는 실수와 해결법

!자주 하는 실수

• 실수: pip가 전역 Python을 가리킵니다. 해결: python -m pip --version에서 .venv 경로를 확인합니다.
• 실수: PowerShell에서 활성화가 차단됩니다. 해결: 정책을 임의로 낮추지 말고 .venv\Scripts\python.exe -m pip ...처럼 직접 실행할 수 있습니다.
• 실수: .venv와 .env를 커밋합니다. 해결: 둘 다 .gitignore에 넣고 예시는 나중에 .env.example로 관리합니다.

✎7. 직접 실습

✎직접 실습

가상환경을 비활성화한 상태와 활성화한 상태에서 python -c "import sys; print(sys.executable)"를 비교하세요. 설치 후 python -c "import fastapi, pydantic, sqlalchemy; print(fastapi.__version__, pydantic.__version__, sqlalchemy.__version__)"로 버전을 기록합니다.

?8. 이해 점검 질문 3개

?이해 점검

1. python -m pip를 권장하는 이유는 무엇인가요?
2. 가상환경 폴더를 Git에 올리지 않는 이유는 무엇인가요?
3. 주 버전 상한 <3은 어떤 변경을 막아 주나요?

■9. 핵심 요약

■핵심 요약

프로젝트마다 .venv를 만들고 의존성은 텍스트 파일로 재현합니다. 이후 모든 Python 명령은 이 가상환경에서 실행합니다.