📄 [문서][가상화] uvicorn을 이용한 파이선 가상환경 설정 방법

[Cassiiopeia]

📝 현재 문제점

• 일반 파이선을 사용한 fast-api를 사용중입니다
• 프로젝트별 독립적인 파이선 환경을 위해 수정해야합니다

🛠️ 해결 방안 / 제안 기능

• 생성

python3 -m venv venv

source venv/bin/activate   # macOS/Linux

pip install -r requirements.txt

인텔리제이서 사용방법 공유

🙋‍♂️ 담당자

• 백엔드: 이름
• 프론트엔드: 이름
• 디자인: 이름

[github-actions]

Chuseok22 Issue Helper

브랜치명

20251222_#6_uvicorn을_이용한_파이선_가상환경_설정_방법

커밋 메시지

uvicorn을_이용한_파이선_가상환경_설정_방법 : feat : {변경 사항에 대한 설명} https://github.com/Team-Romi/romi-chatbot/issues/6

[coderabbitai]

📝 CodeRabbit Plan Mode

Generate an implementation plan and prompts that you can use with your favorite coding agent.

• Create Plan

Examples

• Example 1
• Example 2

---

🔗 Similar Issues

Related Issues

• ⚙️ [기능추가][DB] PostgreSQL 연결 및 테이블 생성 #1
• ⚙️ [기능추가][프로젝트] 프로젝트 init 및 구조 설정 #2
• ⚙️ [기능추가][배포][인증] 인증서 생성 및 https 프록시 설정 필요 #3

👤 Suggested Assignees

• Cassiiopeia
• Chuseok22

---

🧪 Issue enrichment is currently in open beta.

You can configure auto-planning by selecting labels in the issue_enrichment configuration.

To disable automatic issue enrichment, add the following to your .coderabbit.yaml:

issue_enrichment:
  auto_enrich:
    enabled: false

💬 Have feedback or questions? Drop into our discord or schedule a call!

[Cassiiopeia]

Python 가상환경(venv) 설정 가이드

이슈: #6 uvicorn을 이용한 파이선 가상환경 설정 방법

---

📌 작업 개요

프로젝트별 독립적인 Python 환경 구성을 위한 venv(가상환경) 설정 가이드입니다.
FastAPI + Uvicorn 기반 프로젝트에서 로컬 개발 환경을 설정하는 방법을 설명합니다.

---

🔍 venv vs .env 차이점

구분	venv (가상환경)	.env (환경변수 파일)
정체	폴더	파일
용도	Python 패키지 격리	비밀번호, API 키 저장
내용물	Python, pip, 라이브러리	KEY=VALUE 텍스트
비유	독립된 작업 공간	메모장에 적은 설정값

둘 다 필요합니다!

• venv/ → "어떤 Python/라이브러리로 실행할까"
• .env → "어떤 설정값으로 실행할까"

---

🛠️ 1단계: 가상환경 생성 (터미널)

macOS / Linux

# 1. 프로젝트 폴더로 이동
cd /path/to/romi-chatbot

# 2. 가상환경 생성
python3 -m venv venv

# 3. 가상환경 활성화
source venv/bin/activate

# 4. 의존성 설치
pip install -r requirements.txt

Windows (PowerShell)

# 1. 프로젝트 폴더로 이동
cd C:\path\to\romi-chatbot

# 2. 가상환경 생성
python -m venv venv

# 3. 가상환경 활성화
.\venv\Scripts\Activate.ps1

# 4. 의존성 설치
pip install -r requirements.txt

활성화 확인

터미널 프롬프트 앞에 (venv)가 표시되면 성공:

(venv) user@mac romi-chatbot %

---

🖥️ 2단계: IntelliJ IDEA 설정

2-1. Python SDK 추가

1. File → Project Structure (또는 ⌘; / Ctrl+Alt+Shift+S)
2. Platform Settings → SDKs 클릭
3. + 버튼 → Add Python SDK 클릭
4. Virtualenv Environment 탭 선택
5. Existing environment 선택
6. Interpreter 경로 입력:

OS	경로
macOS/Linux	{프로젝트경로}/venv/bin/python
Windows	{프로젝트경로}\venv\Scripts\python.exe

예시 (macOS):

/Users/username/Desktop/Programming/project/romi-chatbot/venv/bin/python

7. OK 클릭

2-2. 프로젝트 SDK 설정

1. Project Settings → Project 클릭
2. SDK 드롭다운에서 방금 추가한 venv Python 선택
3. OK 클릭

---

▶️ 3단계: Run Configuration 설정 (IntelliJ)

3-1. FastAPI Run Configuration 생성

1. Run → Edit Configurations (또는 상단 드롭다운 → Edit Configurations)
2. + 버튼 → FastAPI 클릭

3-2. 설정값 입력

항목	입력값
이름(N)	FastAPI (또는 원하는 이름)
애플리케이션 파일	app/main.py (폴더 아이콘 클릭하여 선택)
애플리케이션 이름	<자동 탐지> (기본값 유지)
Uvicorn 옵션	--reload
Python 인터프리터	지정된 인터프리터 사용(U) 선택 → venv Python 선택

3-3. 상세 설정 화면

┌─────────────────────────────────────────────────────────────┐
│ 이름(N): FastAPI                                            │
├─────────────────────────────────────────────────────────────┤
│ 애플리케이션 파일:    [app/main.py]                    [📁] │
│ 애플리케이션 이름:    <자동 탐지>                            │
│ Uvicorn 옵션:         --reload                              │
├─────────────────────────────────────────────────────────────┤
│ ▼ 환경                                                      │
│   환경 변수(E):       [환경 변수]                       [⚙] │
│   Python 인터프리터:  ● 지정된 인터프리터 사용(U)           │
│                       [🐍 Python 3.x {프로젝트}/venv/...] ▼ │
│   작업 디렉터리(W):   [{프로젝트 루트 경로}]           [📁] │
│   ☑ 콘텐츠 루트를 PYTHONPATH에 추가                        │
│   ☑ 소스 루트를 PYTHONPATH에 추가                          │
└─────────────────────────────────────────────────────────────┘

3-4. 적용 및 실행

1. 적용(A) 클릭
2. 확인 클릭
3. 상단 ▶ 실행 버튼 클릭 또는 Shift+F10

---

🌐 4단계: 서버 실행 및 확인

IntelliJ에서 실행

Run Configuration 설정 후 ▶ 실행 버튼 클릭

터미널에서 실행 (대안)

# 가상환경 활성화
source venv/bin/activate

# 서버 실행
uvicorn app.main:app --reload --port 8000

실행 확인

브라우저에서 접속:

• Health Check: http://localhost:8000/health
• API 문서 (Swagger): http://localhost:8000/docs

정상 응답:

{"status": "ok"}

---

📁 프로젝트 구조

romi-chatbot/
├── venv/                    # 가상환경 (Git 제외)
│   ├── bin/                 # macOS/Linux
│   │   ├── python
│   │   ├── pip
│   │   └── uvicorn
│   └── Scripts/             # Windows
│       ├── python.exe
│       ├── pip.exe
│       └── uvicorn.exe
├── app/
│   ├── main.py              # FastAPI 앱 진입점
│   ├── config/
│   ├── api/
│   └── ...
├── .env                     # 환경변수 (Git 제외)
├── .gitignore               # venv/, .env 포함됨
└── requirements.txt         # 의존성 목록

---

⚠️ 주의사항

1. venv 폴더는 Git에 커밋하지 않음

• .gitignore에 이미 venv/ 포함되어 있음
• 각 개발자가 로컬에서 직접 생성해야 함

2. 새 패키지 설치 시

# 가상환경 활성화 상태에서
pip install 패키지명

# requirements.txt 업데이트
pip freeze > requirements.txt

3. 가상환경 비활성화

deactivate

4. Python 버전

• 로컬: Python 3.9 이상 권장
• Docker (배포): Python 3.13 사용

---

🔧 트러블슈팅

Q1. python3: command not found

→ Python이 설치되어 있지 않음. python.org에서 설치

Q2. IntelliJ에서 venv Python이 보이지 않음

→ Add Python SDK → Existing environment에서 직접 경로 입력

Q3. pip install 시 permission denied

→ 가상환경이 활성화되지 않은 상태. source venv/bin/activate 먼저 실행

Q4. 모듈을 찾을 수 없다는 에러

→ pip install -r requirements.txt 재실행

---

📌 참고사항

• 로컬 개발: uvicorn --reload 옵션으로 코드 변경 시 자동 재시작
• CI/CD 배포: Docker 컨테이너에서 자동으로 환경 구성됨
• 포트: 로컬 8000, Docker 내부 8000, 서버 외부 8083

---

작성일: 2025-12-22
관련 이슈: #6

[Cassiiopeia]