Uvicorn / ASGI vs WSGI

📌 Uvicorn이란?

Uvicorn은 FastAPI, Starlette, Django 같은 ASGI 웹 프레임워크를 실행하는 초고속 ASGI 서버

• 비동기(Async) 지원 → async/await을 활용한 비동기 웹 서비스 개발 가능
• 초고속 → Rust로 작성된 uvloop을 사용해 매우 빠른 성능 제공
• ASGI(Application Server Gateway Interface) 지원 → FastAPI, Starlette 등과 함께 사용
• WebSocket & HTTP/2 지원 → 실시간 통신을 위한 WebSocket을 기본 지원

🔹 쉽게 말해서?

"FastAPI를 실행하려면 웹 서버가 필요한데, 그 역할을 하는 게 Uvicorn이다."

 

 

📌WSGI vs ASGI

웹 애플리케이션을 실행할 때 사용하는 서버 인터페이스에는 크게 두 가지 방식이 있다.

 

• WSGI (Web Server Gateway Interface)
• ASGI (Asynchronous Server Gateway Interface)

기존에 많이 쓰이던 방식은 WSGI, 최근에는 ASGI를 주로 쓴다. 

 

1. WSGI (Web Server Gateway Interface)

기존의 동기 기반 웹 서버 인터페이스
(Flask, Django(기본), Bottle 등에서 사용)

 

🔹 WSGI의 특징

• "동기적" 요청 처리 → 요청을 하나씩 순차적으로 처리
• 멀티스레드, 멀티프로세스를 사용해 동시 요청 처리
• WebSocket, HTTP/2 같은 실시간 기능 미지원
• 대표적인 웹 서버: Gunicorn, uWSGI

 

🔹 WSGI 실행 방식 (Flask 예제)

from flask import Flask

app = Flask(__name__)

@app.route("/")
def home():
    return "Hello, Flask!"

if __name__ == "__main__":
    app.run()

 

 

2. ASGI (Asynchronous Server Gateway Interface)

WSGI를 확장한 비동기(Async) 기반 웹 서버 인터페이스
(FastAPI, Django(ASGI 지원 버전), Starlette에서 사용)

 

🔹ASGI의 특징

• "비동기" 요청 처리 가능 (async/await 지원)
• WebSocket, HTTP/2, gRPC 같은 실시간 통신 지원
• 멀티스레드, 멀티프로세스, 비동기 이벤트 루프 활용 가능
• 대표적인 웹 서버: Uvicorn, Daphne

 

🔹 ASGI 실행 방식 (FastAPI 예제)

from fastapi import FastAPI

app = FastAPI()

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

if __name__ == "__main__":
    import uvicorn
    uvicorn.run(app, host="0.0.0.0", port=8000)

 

3. WSGI vs ASGI 차이점 비교

비교 항목	WSGI (Flask, 기본 Django)	ASGI (FastAPI, Starlette)
동작 방식	동기(Synchronous)	비동기(Asynchronous)
동시 요청 처리	멀티스레드, 멀티프로세스 활용	비동기 이벤트 루프(async/await) 지원
WebSocket 지원	X	O
HTTP/2 지원	X	O
실시간 처리 (gRPC 등)	X	O

 

4. FastAPI가 ASGI를 사용하는 이유

1. 비동기(Async) 지원 → 동시 요청 처리 속도가 빠름
   • WSGI는 요청을 하나씩 처리하지만, ASGI는 비동기 이벤트 루프를 이용해 다중 요청을 처리할 수 있다.
2. WebSocket, HTTP/2, gRPC 등 최신 기술 지원
   • FastAPI는 WebSocket을 기본 지원하는데, WSGI 환경에서는 불가능하다.
3. 비동기 데이터베이스 (Tortoise ORM, Async SQLAlchemy) 활용 가능
   • WSGI 환경에서는 일반적인 SQLAlchemy를 사용할 수밖에 없지만, ASGI 환경에서는 비동기 DB 처리도 가능.
4. Uvicorn 같은 초고속 ASGI 서버 사용 가능
   • uvicorn은 Rust 기반의 uvloop을 사용해 성능을 최적화함.

 

5. 결론: 언제 WSGI vs ASGI를 선택할까?

선택 기준	WSGI (Flask, 기본 Django)	ASGI (FastAPI, Django ASGI)
단순한 REST API	가능	가능
동기 DB (SQLAlchemy ORM 등)	가능	가능
WebSocket 필요	불가능	가능
실시간 데이터 스트리밍	불가능	가능
성능 최적화 & 고속 API	제한적	FastAPI 추천

 

 

📌 uvicorn은 설치 방법 2가지

pip install uvicorn
pip install "uvicorn[standard]"

 

1. pip install uvicorn 기본 설치

pip install uvicorn

 

🔹 설치되는 패키지

• uvicorn 기본 패키지만 설치됨.

🔹 사용 가능한 기능

• 일반적인 FastAPI API 서버 실행 가능
• uvicorn main:app --reload 사용 가능

하지만 성능 최적화를 위한 추가적인 라이브러리는 포함되지 않음.

 

2. pip install "uvicorn[standard]" (최적화 버전)

pip install "uvicorn[standard]"

 

🔹 설치되는 추가 라이브러리

- 성능을 향상시키는 몇 가지 핵심 라이브러리가 함께 설치됨.

 

🔹  추가 패키지 기능

uvloop	비동기 이벤트 루프 최적화 (Linux/macOS 성능 향상)
httptools	HTTP 요청 파싱 속도 향상
watchfiles	파일 변경 감지 속도 개선 (--reload 시 더 빠름)
websockets	WebSocket 지원
gunicorn	다중 프로세스를 활용한 성능 개선 (배포 시 유용)

 

🔹 추가 기능

• 비동기 처리 속도 개선 → uvloop 덕분에 async 처리가 더 빠름
• 파일 변경 감지 속도 개선 → watchfiles 덕분에 --reload 시 감지 속도 향상
• WebSocket을 기본 지원 → websockets 라이브러리 포함
• Gunicorn과 연동 가능 → 배포 시 다중 프로세스 실행 가능

💡 즉, 성능 최적화가 필요한 경우 uvicorn[standard]을 설치하는 것이 더 좋다.

 

 

📌 어떤 걸 설치해야 할까? 

설치 방식	언제 사용하면 좋을까?
pip install uvicorn	기본적인 FastAPI 개발을 할 때
pip install "uvicorn[standard]"	성능 최적화 & WebSocket 지원이 필요할 때

 

• FastAPI 개발을 간단하게 시작하려면 pip install uvicorn
• 프로덕션 환경(배포)에서는 성능 최적화를 위해 pip install "uvicorn[standard]" 추천

 

추가적인 FastAPI 성능 최적화 방법

FastAPI를 배포할 때, uvicorn을 단독으로 실행하는 대신 Gunicorn과 함께 실행하면 더 안정적인 성능을 낼 수 있다.

 

 

🔹  기본 실행 방식(개발용)

uvicorn main:app --host 0.0.0.0 --port 8000 --reload

 

 

🔹  최적화 실행 방식(Gunicorn + Uvicorn 사용)

gunicorn -w 4 -k uvicorn.workers.UvicornWorker main:app

• -w 4: 4개의 워커(worker) 프로세스 실행
• -k uvicorn.workers.UvicornWorker: Uvicorn을 Gunicorn과 함께 실행

이런 최적화 방법까지 함께 적용하면, FastAPI 서버를 더욱 강력하게 운영할 수 있다.

 

 

📌 실제로 main.py 에서 uvicorn 사용하는 방법 

from fastapi import FastAPI

app = FastAPI()

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

if __name__ == "__main__":
    import uvicorn
    uvicorn.run(app, host="0.0.0.0", port=5001)

 

그런데 이렇게 코드를 구현하면, 

uvicorn main:app --host 0.0.0.0 --port 5001 --reload

 

이렇게 실행하지 않고, 

python main.py

이렇게 실행해도 실행이 된다.

 

if __name__ == "__main__": 내부에서 uvicorn.run()을 직접 호출하면 python main.py로 실행해도 FastAPI가 정상적으로 작동한다.  

 

📌 그럼 uvicorn main:app --reload랑 뭐가 다를까?

실행 방식	동작 방식	장점	단점
python main.py	uvicorn.run()을 직접 호출	파일 하나로 실행 가능, FastAPI 지원	--reload 기능 없음
uvicorn main:app --reload	FastAPI 서버를 외부에서 실행	코드 변경 시 자동 재시작	main.py 외부에서 실행해야 함

---

📌 추가 정보: FastAPI 실행과 성능 최적화

✅ Windows에서는 `"uvicorn[standard]"` 설치가 Linux/macOS만큼 큰 성능 차이를 주지 않을 수 있다.  
✅ FastAPI는 ASGI 서버이므로 Daphne, Hypercorn도 사용 가능하지만, Uvicorn이 가장 널리 쓰인다.  
✅ `--reload`는 개발 환경에서만 사용하는 것이 좋으며, 배포 환경에서는 `--no-reload` 옵션을 쓰는 것이 효율적이다.  
✅ `uvicorn --workers` 옵션을 사용하면 Gunicorn 없이도 다중 프로세스를 실행할 수 있지만, 대규모 트래픽을 처리할 때는 Gunicorn이 더 안정적이다.