🔧 FastAPI 개발 환경 설정 (Windows 기준) - nojamlog (life is boring but let's find fun!)

Table of Contents

🕒 약 1분 읽는 데 소요됩니다

개발보다 더 어려운 개발 환경 설정을 시작해봅시다!
FastAPI는 설치와 실행이 비교적 간단하지만, 제대로 된 개발을 위해서는 몇 가지 필수 도구와 설정이 필요합니다. 이 글에서는 Windows 환경에서 FastAPI 프로젝트를 시작하는 데 필요한 모든 과정을 자세히 안내합니다.
가상환경 생성부터 FastAPI 실행까지, 하나씩 시작해봅시다.

✅ 1. Python 설치

FastAPI는 Python 3.7 이상에서 동작합니다. 가장 먼저 Python이 설치되어 있는지 확인하고, 없으면 설치해봅시다.

설치 방법:

공식 Python 다운로드 페이지로 이동
최신 버전의 Windows installer (64-bit) 클릭
설치 시 아래 항목 체크 필수:
- ✅ Add Python to PATH
- ✅ Install launcher for all users
설치 후 커맨드 프롬프트(cmd) 열고 다음 명령어 입력:

python --version

정상적으로 설치되었다면 버전이 출력됩니다. 예: Python 3.11.2

📁 2. 프로젝트 폴더 생성

작업할 디렉토리를 하나 만들어주세요. 예를 들어:

C:\Users\사용자명\fastapi-tutorial

이제 해당 폴더로 이동합니다.

cd C:\Users\사용자명\fastapi-tutorial

🧪 3. 가상환경(Virtual Environment) 설정

가상환경을 사용하면 다른 프로젝트와 의존성 충돌 없이 독립적으로 개발할 수 있습니다.

가상환경 생성:

python -m venv venv

venv는 가상환경 폴더 이름입니다. 자유롭게 바꿔도 됩니다.

가상환경 활성화:

venv\Scripts\activate

활성화되면 (venv) 같은 프롬프트가 앞에 붙습니다. 가상환경이 정상적으로 활성화된 것입니다.

📦 4. FastAPI & Uvicorn 설치

FastAPI는 웹 프레임워크, Uvicorn은 웹 서버 역할을 합니다. 함께 설치해줍니다.

pip install fastapi uvicorn

설치가 완료되면 다음 명령어로 확인:

pip list

여기서 fastapi, uvicorn이 보이면 성공입니다.

✍️ 5. Hello FastAPI: 첫 번째 앱 만들기

FastAPI의 기본 작동을 확인해보기 위해 간단한 예제를 만들어보겠습니다.

1. 파일 생성

main.py라는 이름의 파일을 생성하고, 다음 코드를 작성합니다:

from fastapi import FastAPI

app = FastAPI()

@app.get("/")
def read_root():
    return {"message": "Hello, FastAPI!"}

이건 FastAPI의 가장 기본적인 API입니다. 루트 경로(/)에 GET 요청이 들어오면 JSON 형태로 메시지를 반환합니다.

🚀 6. Uvicorn으로 서버 실행

서버를 실행하려면 아래 명령어를 입력하세요:

uvicorn main:app --reload

main: 파일 이름 (main.py)
app: FastAPI 인스턴스 이름
--reload: 코드 변경 시 자동으로 서버를 재시작해주는 개발자 모드

성공적으로 실행되었다면 아래처럼 출력됩니다:

INFO:     Uvicorn running on http://127.0.0.1:8000 (Press CTRL+C to quit)

🌐 7. 브라우저에서 확인

이제 브라우저를 열고 아래 주소로 접속해보세요:

http://127.0.0.1:8000 → “Hello, FastAPI!” 메시지 확인
http://127.0.0.1:8000/docs → Swagger UI 자동 문서화 페이지
http://127.0.0.1:8000/redoc → ReDoc 문서화 페이지

자동으로 생성된 API 문서 덕분에 바로 테스트도 가능하고, 동작도 한눈에 볼 수 있습니다.

🛠️ (선택) Visual Studio Code 환경 설정 팁

VS Code는 FastAPI 개발에 매우 적합한 에디터입니다.

터미널에서 가상환경 자동 활성화

VS Code를 프로젝트 폴더에서 실행하면 기본 터미널에서 venv 가상환경이 자동으로 활성화됩니다.

code .

🧾 마무리: 환경 세팅은 한 번, 효과는 평생

FastAPI는 빠르고 생산적인 웹 프레임워크이지만, 첫 걸음을 잘 떼는 것이 중요합니다. 이번 글에서는 Windows에서 Python, 가상환경, FastAPI 설치, 그리고 첫 실행까지의 전 과정을 정리했습니다.

이제 본격적인 FastAPI 개발을 위한 준비가 완료되었습니다!
다음 글에서는 라우팅과 경로 매개변수, 쿼리 매개변수에 대해 깊이 있게 다뤄볼 예정입니다.

FastAPI 공식 문서 : https://fastapi.tiangolo.com/ko/