FastAPI는 파이썬(Python) 타입 힌트를 그대로 읽어 입력 검증과 대화형 API 문서(/docs)를 자동으로 만들어 주는 백엔드 프레임워크이고, 설치는 pip 한 줄, 첫 서버는 코드 다섯 줄이면 뜹니다. Flask와 가장 크게 갈리는 지점은 바로 이 자동 문서와 데이터 검증입니다. 이 글은 제가 12개 사이트를 Next.js + 슈퍼베이스(Supabase) + 버셀(Vercel)로 직접 돌리면서, 파이썬 백엔드 한쪽을 FastAPI로 붙이고 자동 문서(/docs)로 API를 빠르게…
한 줄 요약: FastAPI는 파이썬(Python) 타입 힌트를 그대로 읽어 입력 검증과 대화형 API 문서(/docs)를 자동으로 만들어 주는 백엔드 프레임워크이고, 설치는 pip 한 줄, 첫 서버는 코드 다섯 줄이면 뜹니다. Flask와 가장 크게 갈리는 지점은 바로 이 자동 문서와 데이터 검증입니다. 이 글은 제가 12개 사이트를 Next.js + 슈퍼베이스(Supabase) + 버셀(Vercel)로 직접 돌리면서, 파이썬 백엔드 한쪽을 FastAPI로 붙이고 자동 문서(/docs)로 API를 빠르게 검증했던 실사용 순서를 그대로 옮긴 것입니다.
이 글이 필요한 사람
Flask는 들어 봤는데 FastAPI를 왜 따로 쓰는지, 무엇이 더 나은지 한 번에 비교하고 싶은 분
파이썬으로 처음 API 서버를 만들면서 입력 검증과 문서화를 손으로 짜기 싫은 입문 개발자
혼자 백엔드를 만들면서 프런트엔드와 API 명세를 빠르게 맞춰야 하는 1인 개발자
만든 FastAPI 서버를 한국 환경에서 어디에 어떻게 올려야 할지 막막한 분
※ 2026년 6월 기준으로 정리했습니다. FastAPI와 Flask의 버전·기본값, 호스팅 가격은 자주 바뀌므로 화면이 다르면 공식 문서와 각 서비스 가격 페이지에서 최신 내용을 확인하시길 권장합니다.
FastAPI는 Flask와 무엇이 다른가
FastAPI와 Flask는 둘 다 파이썬으로 웹 API를 만드는 도구지만, 설계 철학이 갈립니다. Flask는 2010년에 나온 가벼운 마이크로 프레임워크로, 필요한 기능을 사용자가 직접 붙여 가며 쓰는 자유도가 강점입니다. 반대로 FastAPI는 2018년에 나오면서 파이썬 타입 힌트를 적극적으로 활용해, 입력 검증과 문서화 같은 반복 작업을 프레임워크가 알아서 처리하도록 만들었습니다.
가장 큰 차이는 세 가지로 정리됩니다. 첫째, FastAPI는 함수 인자의 타입 힌트만 보고 요청 데이터를 자동으로 검증합니다. 둘째, 코드를 짜는 순간 대화형 문서 페이지(/docs)가 자동으로 생깁니다. 셋째, async/await 비동기 처리가 기본으로 들어 있어 동시 요청을 더 잘 버팁니다. 아래 표로 입문자가 자주 헷갈리는 지점을 정리했습니다.
항목
FastAPI
Flask
입력 검증
타입 힌트로 자동
직접 코드로 검사
API 문서
/docs 자동 생성
확장으로 별도 설정
비동기
async 기본 지원
버전 따라 제한적
학습 곡선
타입 개념이 전제
더 단순·직관적
서버 구동
uvicorn(ASGI)
gunicorn(WSGI)
제 기준으로 정리하면, 화면 렌더링까지 포함한 전통적 웹사이트를 손에 익은 방식으로 빠르게 만들 때는 Flask가 편하고, 프런트엔드와 분리된 순수 API 서버를 만들면서 명세를 자동으로 맞추고 싶을 때는 FastAPI가 시간을 크게 아껴 줍니다. 다음 항목부터는 실제 설치와 코드로 그 차이를 직접 확인해 보겠습니다.
FastAPI 입문·설치 가이드 + Flask와 비교 (자동 docs·redoc) 관련 참고 이미지
1단계 — 가상환경부터 설치까지 막힘 없이 끝내기
FastAPI 설치 자체는 어렵지 않지만, 입문자가 가장 자주 막히는 지점은 설치 그 자체보다 가상환경입니다. 파이썬 패키지를 시스템 전역에 깔면 프로젝트마다 버전이 충돌하기 쉽습니다. 그래서 프로젝트 폴더 안에 가상환경(venv)을 먼저 만들고, 그 안에서 설치하는 순서를 권장합니다. 파이썬은 3.9 이상이면 충분합니다.
아래 명령은 맥과 윈도우 모두에서 동작하도록 두 갈래로 적었습니다. 가상환경을 활성화하면 터미널 줄 앞에 (venv) 표시가 붙는데, 이 표시가 보일 때만 설치가 프로젝트 안으로 들어갑니다.
가상환경 생성·활성화 후 FastAPI 설치
# 1) 프로젝트 폴더에서 가상환경 생성
python -m venv venv
# 2) 가상환경 활성화
# 맥/리눅스
source venv/bin/activate
# 윈도우(파워셸)
venv\Scripts\Activate.ps1
# 3) FastAPI + 표준 추가 패키지(uvicorn 포함) 설치
pip install "fastapi[standard]"
여기서 핵심은 마지막 줄의 fastapi[standard]입니다. 대괄호 안의 standard는 서버를 실제로 띄우는 데 필요한 uvicorn(ASGI 서버)과 부가 도구를 함께 설치해 줍니다. 예전 자료를 보고 그냥 pip install fastapi만 하면 서버 실행 명령에서 막히는 경우가 많은데, 이 standard 묶음을 쓰면 그 단계가 한 번에 끝납니다.
윈도우 파워셸 activate 막힘 케이스 윈도우에서 Activate.ps1 실행 시 보안 정책 때문에 차단되는 경우가 흔합니다. 이때는 파워셸을 열고 Set-ExecutionPolicy -Scope CurrentUser RemoteSigned를 한 번 실행한 뒤 다시 활성화하면 풀립니다. 이 설정은 현재 사용자에게만 적용되므로 시스템 전체에 영향을 주지 않아 비교적 안전합니다.
설치가 끝나면 pip list로 fastapi와 uvicorn이 보이는지 확인합니다. 둘 다 잡혀 있으면 서버를 띄울 준비가 끝난 것입니다.
2단계 — 다섯 줄로 첫 API 서버 띄우기
이제 가장 작은 서버를 만들어 보겠습니다. 프로젝트 폴더에 main.py 파일을 만들고 아래 코드를 넣습니다. 핵심 줄은 다섯 줄이 채 안 됩니다. FastAPI 객체를 만들고, 데코레이터로 경로를 지정하고, 함수가 돌려줄 데이터를 반환하면 끝입니다.
FastAPI 입문·설치 가이드 + Flask와 비교 (자동 docs·redoc) 관련 참고 이미지
파일을 저장했으면 터미널에서 아래 명령으로 서버를 실행합니다. 설치 시 standard 묶음을 썼다면 fastapi dev 명령으로 바로 띄울 수 있고, uvicorn을 직접 부르는 방식도 함께 적어 두었습니다.
개발 서버 실행 (둘 중 하나)
# 방법 A — FastAPI CLI (설치 시 standard 포함이면 사용 가능)
fastapi dev main.py
# 방법 B — uvicorn 직접 실행
uvicorn main:app --reload
실행하면 터미널에 http://127.0.0.1:8000 주소가 뜹니다. 브라우저에서 그 주소를 열면 message가 보이고, /items/3?keyword=test를 붙이면 입력값이 그대로 JSON으로 돌아옵니다. 여기서 작지만 중요한 동작이 하나 있습니다. read_item 함수의 item_id에 int 타입 힌트를 붙였기 때문에, /items/abc처럼 숫자가 아닌 값을 넣으면 FastAPI가 알아서 422 에러와 함께 어떤 값이 잘못됐는지 알려 줍니다. 검증 코드를 한 줄도 안 짰는데 입력 검사가 되는 것, 이게 Flask와 갈리는 첫 번째 체감 포인트입니다.
참고로 --reload 옵션은 코드를 저장할 때마다 서버를 자동으로 다시 띄워 주는 개발용 옵션입니다. 실제 배포에서는 이 옵션을 빼고 별도 구동 방식을 쓰는데, 그 부분은 뒤의 배포 항목에서 다루겠습니다.
자동 문서(/docs)가 1인 개발에서 진짜 강력한 이유
FastAPI를 처음 띄우고 나면 반드시 한 번 들어가 봐야 할 주소가 두 개 있습니다. 서버 주소 뒤에 /docs와 /redoc을 붙인 페이지입니다. 둘 다 코드를 따로 짜지 않아도 자동으로 생기는 API 문서 화면이고, 성격이 조금 다릅니다.
/docs (Swagger UI) — 각 API 경로가 목록으로 나오고, 화면에서 바로 값을 입력해 요청을 실행(Try it out)할 수 있습니다. 입력값을 넣고 버튼을 누르면 실제 응답이 그 자리에서 뜹니다.
/redoc (ReDoc) — 실행 기능은 없지만 명세서처럼 깔끔하게 읽히는 정적 문서입니다. API 구조를 한눈에 훑거나 다른 사람에게 공유할 때 보기 좋습니다.
제가 1인 개발에서 이 자동 문서를 가장 요긴하게 쓴 순간은, 만든 API가 의도대로 동작하는지 빠르게 검증할 때였습니다. 포스트맨(Postman) 같은 별도 도구를 켜거나 curl 명령을 손으로 치지 않아도, /docs 화면에서 값을 바꿔 가며 바로 눌러 보면 됩니다. 프런트엔드를 붙이기도 전에 API가 어떤 형태로 응답하는지 눈으로 확인할 수 있어서, 명세를 맞추는 시간이 크게 줄었습니다.
왜 자동으로 생기나 FastAPI는 코드의 타입 힌트와 경로 정의를 읽어 내부적으로 OpenAPI 규격의 명세(JSON)를 만듭니다. /docs와 /redoc은 그 명세를 화면으로 그려 주는 것뿐입니다. 그래서 코드를 고치면 문서도 즉시 함께 바뀝니다. 문서와 코드가 따로 노는 일이 구조적으로 생기지 않습니다.
Flask에서 같은 문서를 만들려면 flasgger나 flask-restx 같은 확장을 따로 붙이고 설정을 해 줘야 합니다. 가능은 하지만 손이 더 갑니다. FastAPI는 이게 처음부터 들어 있다는 점이 입문자에게도, 시간이 부족한 1인 개발자에게도 분명한 이점입니다.
FastAPI 입문·설치 가이드 + Flask와 비교 (자동 docs·redoc) 관련 참고 이미지
입력 검증을 코드로 짜지 않게 해 주는 모델 구조
API 서버에서 가장 귀찮은 일 중 하나가 요청으로 들어온 데이터가 올바른 형태인지 검사하는 것입니다. 이름은 문자열인지, 나이는 숫자인지, 빠진 항목은 없는지를 일일이 if 문으로 검사하면 코드가 금방 지저분해집니다. FastAPI는 이 검증을 Pydantic이라는 데이터 모델로 대신합니다. 클래스로 데이터 모양을 한 번 정의해 두면, 그 모양에 맞지 않는 요청은 FastAPI가 자동으로 걸러 냅니다.
Pydantic 모델로 POST 요청 검증
from fastapi import FastAPI
from pydantic import BaseModel
app = FastAPI()
class Item(BaseModel):
name: str
price: int
in_stock: bool = True
@app.post("/items")
def create_item(item: Item):
total = item.price
return {"name": item.name, "total": total, "in_stock": item.in_stock}
여기서 create_item 함수의 인자에 Item 모델을 타입으로 지정했습니다. 이렇게만 해 두면 FastAPI는 요청 본문(JSON)을 자동으로 읽어 Item 형태에 맞는지 검사합니다. price 자리에 문자열이 들어오거나 name이 빠지면, 우리가 검사 코드를 한 줄도 안 썼는데도 어떤 항목이 왜 틀렸는지 친절한 에러로 돌려줍니다. in_stock처럼 기본값을 준 항목은 생략해도 자동으로 채워집니다.
그리고 이 모델 정의는 곧바로 /docs 문서에도 반영됩니다. 어떤 항목을 어떤 타입으로 보내야 하는지 문서에 그대로 나오니, 프런트엔드를 맡은 사람이 따로 물어보지 않아도 명세를 알 수 있습니다. 제가 혼자 프런트와 백엔드를 모두 만들 때도, 이 한 번의 모델 정의가 검증 코드, 문서, 자동완성 세 가지를 동시에 해결해 주는 게 가장 큰 시간 절약이었습니다.
그래도 Flask가 더 나은 상황은 언제인가
지금까지 FastAPI의 장점을 짚었지만, 모든 경우에 FastAPI가 정답은 아닙니다. 도구는 상황에 맞게 고르는 것이 맞습니다. Flask를 고르는 게 더 합리적인 경우를 솔직하게 정리하겠습니다.
HTML 화면을 직접 렌더링하는 전통적 웹사이트 — 서버가 템플릿으로 페이지를 그려 내려보내는 구조라면, 이런 작업에 오래 다듬어진 Flask와 Jinja2 조합이 여전히 편합니다.
타입 힌트 개념이 아직 낯선 입문자 — FastAPI의 강점은 대부분 타입 힌트에서 나옵니다. 타입이라는 개념 자체가 부담스러운 단계라면, 더 단순한 Flask로 시작해 감을 잡는 편이 덜 막힙니다.
아주 작은 단발성 스크립트나 내부 도구 — 검증·문서가 거의 필요 없는 한두 개 엔드포인트라면 어느 쪽이든 비슷하고, 익숙한 도구를 쓰면 됩니다.
기존 Flask 자료·예제가 풍부한 강의를 따라가는 중 — 학습 중이라면 보고 있는 자료와 같은 프레임워크를 쓰는 게 막힘이 적습니다.
요약하면, 화면 렌더링이 중심이면 Flask, 프런트엔드와 분리된 순수 API와 자동 문서가 중심이면 FastAPI입니다. 둘 다 파이썬 생태계 안에 있어서, 나중에 옮겨 타도 배운 지식 대부분이 그대로 쓰입니다. 그래서 처음 선택에 너무 무게를 둘 필요는 없습니다.
FastAPI 입문·설치 가이드 + Flask와 비교 (자동 docs·redoc) 관련 참고 이미지
3단계 — 한국 환경에서 FastAPI 서버 배포하기
서버를 로컬에서 띄우는 것까지는 쉽지만, 실제로 인터넷에 올리는 단계에서 입문자가 많이 헤맵니다. 가장 먼저 알아야 할 점은, FastAPI는 ASGI 방식이라 Flask처럼 단순히 파일을 올린다고 돌지 않고 uvicorn 같은 ASGI 서버로 구동해야 한다는 것입니다. 한국에서 1인 개발자가 현실적으로 고를 만한 배포 선택지를 정리했습니다.
배포 방식
특징
한국 1인 개발자 관점
국내 클라우드 VM
네이버 클라우드·카카오 클라우드 서버 직접 구동
원화 결제·국내 응답 빠름, 직접 관리 필요
컨테이너 PaaS
도커 이미지로 올리는 관리형 플랫폼
설정 단순, 대부분 외화·VAT 별도 청구
서버리스 함수
요청당 실행, 상시 서버 없음
트래픽 적을 때 저렴, 콜드 스타트 주의
제 경우, 메인 사이트들은 Next.js라서 버셀에 올리지만, 파이썬 API 한 조각만 따로 떼어 붙일 때는 도커 이미지로 만들어 컨테이너 방식으로 올리는 게 가장 군더더기가 없었습니다. 배포 환경에서는 reload 옵션을 빼고, 워커 수를 지정해 구동합니다.
배포용 구동 명령 + 최소 Dockerfile
# 배포 환경 구동 (reload 없이, 외부 접속 허용 0.0.0.0)
uvicorn main:app --host 0.0.0.0 --port 8000
# --- 아래는 Dockerfile 예시 ---
# FROM python:3.12-slim
# WORKDIR /app
# COPY requirements.txt .
# RUN pip install --no-cache-dir -r requirements.txt
# COPY . .
# CMD ["uvicorn", "main:app", "--host", "0.0.0.0", "--port", "8000"]
배포 시 한국 사용자 입장에서 꼭 챙길 두 가지가 있습니다. 첫째, 해외 플랫폼은 가격이 달러로 표시되고 한국 카드로 결제하면 환율에 더해 부가가치세(VAT) 10%가 붙어 실제 청구액이 표시가보다 늘어납니다. 가격을 비교할 때 이 점을 미리 계산해 두는 게 좋습니다. 둘째, 한국 방문자가 대부분이라면 서버가 물리적으로 가까운 지역(일본 도쿄 등)에 있을수록 응답이 빠릅니다. 가격만 보지 말고 서버 위치도 함께 보는 편이 체감 품질에 영향을 줍니다.
운영 환경에서 /docs 노출 주의 자동 문서는 개발할 때 정말 편하지만, 실제 서비스에 그대로 열어 두면 API 구조 전체가 외부에 공개됩니다. 외부 공개용이 아니라면 배포 시 docs_url과 redoc_url을 None으로 꺼 두거나, 인증을 건 경로로만 접근하게 막는 게 안전합니다. 가격·요금 정보는 변동성이 크니 2026년 6월 기준이라는 점을 감안해, 결제 직전 각 서비스 공식 가격 페이지에서 최신 금액을 확인하시길 권장합니다.
화면을 직접 그려 내려보내는 전통적 웹사이트를 만들고 싶다면 Flask가 더 단순해 막힘이 적습니다. 반대로 프런트엔드와 분리된 순수 API 서버를 만들고 자동 문서·입력 검증의 편의를 누리고 싶다면 FastAPI가 시간을 아껴 줍니다. 다만 FastAPI의 장점 대부분이 파이썬 타입 힌트에서 나오므로, 타입 개념이 아직 낯설다면 Flask로 감을 잡은 뒤 넘어가도 늦지 않습니다.
설치할 때 fastapi와 fastapi[standard] 중 무엇을 써야 하나요?
대부분의 경우 pip install fastapi[standard]를 권장합니다. 대괄호 안의 standard는 서버를 실제로 구동하는 데 필요한 uvicorn(ASGI 서버)과 부가 도구를 함께 설치해 줍니다. 그냥 fastapi만 설치하면 서버 실행 단계에서 별도로 uvicorn을 또 깔아야 하는 번거로움이 생기므로, 처음부터 standard 묶음으로 받는 편이 막힘이 적습니다.
/docs와 /redoc은 무슨 차이가 있나요?
둘 다 코드를 따로 짜지 않아도 자동으로 생기는 API 문서 화면입니다. /docs(Swagger UI)는 각 경로를 화면에서 직접 값을 넣어 실행해 볼 수 있어 검증과 디버깅에 유용하고, /redoc(ReDoc)은 실행 기능은 없지만 명세서처럼 깔끔하게 읽혀 구조를 훑거나 공유할 때 좋습니다. 둘 다 코드의 타입 힌트와 경로 정의를 읽어 만들어지므로, 코드를 고치면 문서도 즉시 함께 바뀝니다.
윈도우에서 가상환경 활성화가 차단되는데 어떻게 푸나요?
파워셸에서 Activate.ps1 실행 시 보안 정책 때문에 막히는 경우가 흔합니다. 파워셸을 열고 Set-ExecutionPolicy -Scope CurrentUser RemoteSigned 명령을 한 번 실행한 뒤 다시 활성화하면 풀립니다. 이 설정은 현재 사용자에게만 적용되어 시스템 전체에는 영향을 주지 않으므로 비교적 안전하게 쓸 수 있습니다. 활성화에 성공하면 터미널 줄 앞에 venv 표시가 붙습니다.
FastAPI 서버를 한국에 배포할 때 비용은 어떻게 봐야 하나요?
해외 플랫폼은 가격이 달러로 표시되고 한국 카드로 결제하면 환율에 더해 부가가치세(VAT) 10%가 붙어 실제 청구액이 표시가보다 늘어납니다. 국내 클라우드는 원화로 결제되고 국내 응답이 빠른 대신 서버 관리를 더 직접 해야 합니다. 트래픽이 적은 초기에는 서버리스나 무료 한도가 넉넉한 플랫폼이 부담이 적습니다. 가격은 변동성이 크므로 2026년 6월 기준이라는 점을 감안해 결제 직전 각 서비스 공식 가격 페이지에서 최신 금액을 확인하시길 권장합니다.
기존 Flask 프로젝트를 FastAPI로 옮길 만한 가치가 있나요?
이미 잘 돌고 있고 문제가 없다면 굳이 옮길 필요는 없습니다. 다만 입력 검증 코드가 늘어나 관리가 버겁거나, 프런트엔드와 API 명세를 자주 맞춰야 해서 자동 문서가 절실한 상황이라면 옮길 가치가 있습니다. 둘 다 파이썬 생태계 안에 있어 데이터베이스 연결, 비즈니스 로직 같은 핵심 코드는 대부분 재사용되고, 경로 정의와 검증 부분만 다시 쓰는 형태라 이전 작업 자체는 생각보다 부담이 크지 않습니다.
