🐍 가상환경(Virtual Environment)과 FastAPI 설치

FastAPI로 본격적인 백엔드 개발을 시작하기 전에 반드시 먼저 정리해야 할 개념:

가상환경(Virtual Environment)

---

🤔 Virtual Environment란?

단어부터 풀어보자.

• Virtual → 실제는 아니지만 실제처럼 동작하는
• Environment → 작업 환경

즉, 가상환경이란

👉 프로젝트마다 독립적으로 사용하는 Python 환경

---

📦 비유로 이해하기

가상환경은 각자 따로 쓰는 책상과 같다.

• 철수의 책상 → 철수 프로젝트에 필요한 도구만
• 영희의 책상 → 영희 프로젝트에 필요한 도구만

서로의 도구가 섞이지 않으니 패키지 버전 충돌이 발생하지 않는다.

👉 가상환경의 핵심 목적은 격리(Isolation)다

---

⚠️ 헷갈리기 쉬운 개념

Virtual Environment ≠ Environment Variable

• Virtual Environment → 파일과 패키지가 들어 있는 디렉토리
• Environment Variable → 프로그램이 참조하는 설정 값

이름이 비슷할 뿐, 완전히 다른 개념이다.

---

🚨 왜 가상환경이 필요한가?

Python 패키지를 전역(Global)에 설치하면 아래와 같은 문제가 생긴다.

❌ 패키지 버전 충돌

예를 들어,

• A 프로젝트 → harry==1 필요
• B 프로젝트 → harry==3 필요

전역 환경에는 하나의 버전만 설치할 수 있다.

👉 한 프로젝트를 고치면 다른 프로젝트가 깨진다

가상환경은 이 문제를 완전히 해결해준다.

---

📁 1단계: 프로젝트 디렉토리 만들기

먼저 프로젝트를 담을 디렉토리를 만든다.

# 홈 디렉토리로 이동
cd ~

# 코드들을 모아둘 디렉토리 생성
mkdir code

# code 디렉토리로 이동
cd code

# 새 프로젝트 생성
mkdir cloud-community

# 프로젝트 디렉토리로 이동
cd cloud-community

이제 이 디렉토리가 FastAPI 커뮤니티 백엔드 프로젝트의 시작점이다.

---

🐍 2단계: 가상 환경 생성

📌 가상 환경 생성은 프로젝트당 한 번만 수행한다

방법 1️⃣ Python 기본 venv 사용

python -m venv .venv

이 명령어는 .venv라는 디렉토리를 만들고, 그 안에 독립적인 Python 실행 환경을 구성한다.

방법 2️⃣ uv 사용 (더 빠른 대안)

uv venv .venv

둘 중 어떤 방식을 써도 상관없다. 개념은 완전히 동일하다.

---

⚡ 3단계: 가상 환경 활성화

❗ 이 단계는 터미널 세션을 열 때마다 필요하다

운영체제	명령어
Linux / macOS	source .venv/bin/activate
Windows (PowerShell)	.venv\Scripts\Activate.ps
Windows (Git Bash)	source .venv/Scripts/activate

Linux / macOS 예시

source .venv/bin/activate

이제 터미널 앞에 (.venv) 같은 표시가 붙었다면 가상 환경이 정상적으로 활성화된 상태다.

---

🔍 4단계: 가상 환경 활성화 확인 (선택사항)

가상 환경이 제대로 활성화되었는지 한 번 더 확인하고 싶다면 아래 방법을 사용하면 된다.

핵심은 아주 단순하다.

👉 현재 사용 중인 python이 프로젝트 내부의 .venv를 가리키는지 확인하는 것

Linux / macOS / Git Bash

which python

출력 예시는 아래와 비슷하게 나온다.

/home/your-name/code/cloud-community/.venv/bin/python

여기서 가장 중요한 포인트는 이것이다.

👉 경로 안에 .venv가 포함되어 있는가?

• ✅ 포함되어 있다 → 가상 환경 정상 활성화
• ❌ 포함되어 있지 않다 → 가상 환경 미활성화 상태

💡 이 출력이 보이면 성공
현재 터미널에서 실행되는 python은 전역 Python이 아니라
프로젝트 전용 가상 환경의 Python이다.

---

Windows (PowerShell)

Get-Command python

출력 예시는 다음과 같다.

C:\Users\your-name\code\cloud-community\.venv\Scripts\python.exe

마찬가지로,

👉 경로에 .venv가 포함되어 있으면 정상

---

🧠 가상 환경 활성화의 원리 (간단 설명)

가상 환경을 활성화하면 내부적으로 PATH 환경 변수가 바뀐다.

원래 상태에서는

/usr/bin:/bin

가상 환경 활성화 후에는

.venv/bin:/usr/bin:/bin

이렇게 .venv/bin 경로가 맨 앞에 추가된다.

그래서 터미널에서 python을 실행하면,

• 시스템 Python이 아니라
• 가상 환경의 Python이 먼저 선택된다

👉 이것이 가상 환경이 동작하는 핵심 원리다

---

📦 5단계: FastAPI 설치

이제 가상 환경이 준비되었으니 FastAPI를 설치할 차례다.

⚠️ 반드시 (.venv)가 활성화된 상태에서 실행해야 한다

pip 최신 버전으로 업그레이드 (권장)

python -m pip install --upgrade pip

이 명령어는

• pip가 오래된 경우 발생하는 오류를 예방하고
• 패키지 설치 안정성을 높여준다

---

FastAPI 설치

pip install "fastapi[standard]"

여기서 [standard]는

• FastAPI 실행에 필요한
• 권장 의존성 패키지들을 함께 설치하는 옵션이다

👉 실습용/학습용에서는 [standard] 사용을 권장한다

---

.gitignore 설정

가상 환경 디렉토리는 Git에 포함시키지 않는다.

# 루트 디렉토리 안에 .gitignore 파일 생성
echo "*" > .gitignore

명령어 해석:

echo "*": "*" 문자열을 출력 (* 는 Git에서 "모든 것"을 의미)
> : 출력을 파일로 리다이렉트
.gitignore : 생성할 파일 경로

---

🛑 가상 환경 비활성화

작업을 마쳤다면 가상 환경을 종료할 수 있다.

deactivate

이후 python 명령어는 다시 전역 Python을 사용하게 된다.

---

✅ 핵심 요약

• 가상 환경은 프로젝트별 독립 Python 환경이다
• 생성은 1번, 활성화는 터미널 세션마다 필요하다
• which python으로 활성화 여부를 확인할 수 있다
• FastAPI는 반드시 가상 환경 안에 설치한다