fastapi uvicorn 실행 안됨 문제 진단과 실무 해결법

fastapi uvicorn 실행 안됨이 필요한 상황

fastapi uvicorn 실행 안됨 상황을 마주했을 때, 이 글에서 얻을 내용은 근본 원인 식별(로그·환경·코드), 빠른 복구를 위한 단계별 명령어와 코드 예시, Docker/운영 환경에서 주의할 점입니다. 실무에서 개발 서버가 켜지지 않거나 자동 재시작(reload) 문제가 발생할 때 바로 적용 가능한 점검 리스트와 대처법을 제공합니다.

fastapi uvicorn 실행 안됨 핵심 개념

Uvicorn은 ASGI 서버로, FastAPI 같은 프레임워크를 실제로 서비스하는 런타임입니다. Uvicorn이 실행되지 않으면 애플리케이션이 외부 요청을 받지 못합니다.
흔한 원인: 포트 충돌, 의존성(라이브러리) 문제, 잘못된 import/앱 객체 참조, asyncio 이벤트 루프 충돌, 권한 문제, Docker 네트워크 설정, 환경 변수 미설정.
진단 우선순위: 로그(콘솔) 확인 → 포트·프로세스 확인 → 코드/모듈문제 확인 → 환경/컨테이너 확인.

fastapi uvicorn 실행 안됨 실무 예제

아래는 로컬에서 FastAPI 앱을 uvicorn으로 실행하는 기본 명령입니다.

# 기본 실행
uvicorn app.main:app --host 0.0.0.0 --port 8000

# 개발 중 자동 리로드 사용
uvicorn app.main:app --reload --host 127.0.0.1 --port 8000

app/main.py 예제:

from fastapi import FastAPI

app = FastAPI()

@app.get("/")
async def read_root():
    return {"hello": "world"}

# 잘못된 경우: if __name__ == "__main__": uvicorn.run(...) 를 사용하면
# 다른 실행 컨텍스트에서 중복 실행 또는 import 문제를 일으킬 수 있음.

실무에서 자주 보이는 문제 상황과 해결 예시:

문제: uvicorn이 즉시 종료(크래시)하거나 에러 없이 프로세스가 사라짐
- 조치: 로그와 stderr 확인, systemd나 supervisor 설정에서 StdOut/Err 리디렉션 체크
문제: reload 모드에서 import error 반복 발생
- 조치: 모듈 수준에서 네트워크 소켓을 생성하거나 이벤트 루프를 생성하는 코드 제거
문제: Docker 컨테이너 내부에서 접근 불가
- 조치: uvicorn을 0.0.0.0 바인딩, 컨테이너 포트 매핑 확인

포트 충돌과 프로세스 확인 방법 (진단 명령)

리눅스/macOS:

# 포트 8000을 사용 중인 프로세스 찾기
sudo lsof -i :8000
# 또는
ss -tulpn | grep 8000

# 프로세스 종료
kill <PID>
# 강제 종료
kill -9 <PID>

윈도우:

netstat -ano | findstr :8000
# PID로 프로세스 종료
taskkill /PID <PID> /F

Docker 관련 빠른 체크

Dockerfile에서 uvicorn CMD 예시:

FROM python:3.11-slim
WORKDIR /app
COPY pyproject.toml poetry.lock /app/
RUN pip install --no-cache-dir -r requirements.txt
COPY . /app
CMD ["uvicorn", "app.main:app", "--host", "0.0.0.0", "--port", "8000"]

docker run 시 포트 매핑 확인:

docker run -p 8000:8000 myimage

비교: 흔한 원인별 판단 기준표

구분	항목1	항목2	항목3
내용	로그에 Traceback 존재	포트가 이미 사용 중	컨테이너 바인딩이 127.0.0.1으로 설정됨

이 표를 보고 해당 행에 맞춰 다음 행동을 선택하세요: Traceback → 코드 수정, 포트 사용 중 → 포트 변경/프로세스 종료, 컨테이너 바인딩 → 0.0.0.0 바인딩.

언제 쓰면 좋고 언제 피해야 할까

언제 쓰면 좋은가
- 개발 중 로컬 빠른 테스트가 필요할 때 uvicorn --reload 사용
- 경량 서비스로 단일 프로세스 운영하거나, 컨테이너 내부에서 간단히 서비스할 때
언제 피해야 하는가
- 프로덕션에서 --reload 옵션 사용(핫리로드는 안정성/성능 문제)
- 단일 스레드/프로세스로 고부하를 처리하려 할 때(프로덕션은 Gunicorn + Uvicorn 워커 권장)

실무 체크리스트

코드 체크리스트:
- app 인스턴스가 모듈 최상단에 정의되어 있는가 (from app.main import app 형태로 참조 가능)
- if name == "main"에서 uvicorn.run을 남발하지 않았는가
- 모듈 임포트에서 소켓/DB/외부 자원을 즉시 열지 않는가
환경 체크리스트:
- Uvicorn 명령어에서 바인딩 호스트가 0.0.0.0인지 확인
- 포트가 충돌하지 않는지 확인(lsof/ss/netstat)
- 환경변수(예: DATABASE_URL, SECRET_KEY)가 누락되지 않았는가
배포 체크리스트:
- 프로덕션은 Gunicorn+Uvicorn 워커 혹은 Process Manager 사용
- 로그 수집/StdErr 리디렉션 설정 완료
- Docker healthcheck와 readiness probe 설정

성능·보안·운영 주의점

성능
- 개발용 --reload는 파일 변경 감지를 위해 많은 I/O를 발생시켜 성능 저하 가능. 프로덕션에서는 제거.
- 단일 Uvicorn 프로세스는 CPU 바운드 작업 처리에 한계. 병렬성 필요 시 Gunicorn + multiple uvicorn worker 사용 권장.
보안
- 개발시 0.0.0.0 바인딩은 편리하지만, 외부 접근 제어가 없으면 노출 위험 있음. 프로덕션은 방화벽/리버스 프록시 뒤에 배치.
- 디버그 모드나 민감한 예외 정보를 출력하지 않도록 설정.
운영
- systemd, docker, k8s 등에서 프로세스 관리 시 로그 로테이션과 모니터링 설정을 반드시 구성.
- readiness/liveness probe로 애플리케이션 시작 실패를 빠르게 감지하고 재시작 정책을 정립.

자주 묻는 질문

Q1: uvicorn이 바로 종료되는데 로그가 안 나옵니다. 어떻게 진단하나요?

A1: systemd나 컨테이너 런타임에서 stdout/stderr를 잡아먹는 경우가 있습니다. 직접 터미널에서 실행해보고, docker logs 혹은 journalctl -u <service>를 확인하세요. 또한 python 예외가 stdout이 아닌 파일로 리디렉션되는지 확인합니다.

Q2: --reload 모드에서 import error가 반복 발생합니다. 원인은 무엇인가요?

A2: 모듈 레벨에서 이벤트 루프를 생성하거나 파일 시스템을 건드리는 코드가 있을 수 있습니다. 모듈 임포트 시점에 실행되는 코드를 최소화하고, 앱 시작 시점에만 실행되도록 수정하세요.

Q3: Docker에서 바인딩을 0.0.0.0으로 했는데도 외부에서 접속이 안 됩니다. 무엇을 확인해야 하나요?

A3: 컨테이너 포트가 호스트에 매핑되었는지(-p 옵션), Docker 네트워크 정책, 방화벽 포트 허용, 그리고 애플리케이션이 실제로 정상 기동했는지(로그/healthcheck) 확인하세요.

Q4: 프로덕션에서 Uvicorn만 사용해도 괜찮을까요?

A4: 소규모 서비스나 내부 툴은 가능하지만, 고가용성/부하 분산이 필요하면 Gunicorn(또는 다른 프로세스 매니저)과 Uvicorn 워커 조합을 추천합니다.

정리

fastapi uvicorn 실행 안됨 현상은 로그→포트→코드→환경 순으로 진단하세요.
개발환경과 프로덕션은 설정을 분리하고 --reload는 개발 전용으로 사용하세요.
Docker에서는 0.0.0.0 바인딩과 포트 매핑을 확인하고 healthcheck를 설정하세요.
운영 시에는 프로세스 매니저, 로그 수집, 모니터링을 반드시 구성하세요.
실무 체크리스트를 통해 빠르게 원인을 좁히고 적용 가능한 해결책을 실행하세요.