FastAPI에서 uv 사용하기

FastAPI는 현대적이고 고성능의 Python 웹 프레임워크다. uv를 사용하면 FastAPI 프로젝트를 관리할 수 있다. 여기에는 의존성 설치, 환경 관리, FastAPI 애플리케이션 실행 등이 포함된다.

Note

이 가이드의 소스 코드는 uv-fastapi-example 저장소에서 확인할 수 있다.

기존 FastAPI 프로젝트 마이그레이션

예제로 FastAPI 공식 문서에 정의된 샘플 애플리케이션을 살펴보자. 이 프로젝트의 구조는 다음과 같다:

project
└── app
    ├── __init__.py
    ├── main.py
    ├── dependencies.py
    ├── routers
    │   ├── __init__.py
    │   ├── items.py
    │   └── users.py
    └── internal
        ├── __init__.py
        └── admin.py

이 애플리케이션에서 uv를 사용하려면 project 디렉토리 안에서 다음 명령을 실행한다:

$ uv init --app

이 명령은 애플리케이션 레이아웃을 가진 프로젝트와 pyproject.toml 파일을 생성한다.

그런 다음 FastAPI에 대한 의존성을 추가한다:

$ uv add fastapi --extra standard

이제 프로젝트 구조는 다음과 같아진다:

project
├── pyproject.toml
└── app
    ├── __init__.py
    ├── main.py
    ├── dependencies.py
    ├── routers
    │   ├── __init__.py
    │   ├── items.py
    │   └── users.py
    └── internal
        ├── __init__.py
        └── admin.py

pyproject.toml 파일의 내용은 다음과 비슷할 것이다:

pyproject.toml

[project]
name = "uv-fastapi-example"
version = "0.1.0"
description = "FastAPI project"
readme = "README.md"
requires-python = ">=3.12"
dependencies = [
    "fastapi[standard]",
]

이제 FastAPI 애플리케이션을 실행할 수 있다:

$ uv run fastapi dev

uv run은 프로젝트 의존성을 자동으로 해결하고 잠근다(즉, pyproject.toml과 함께 uv.lock 파일을 생성한다). 가상 환경을 만들고 해당 환경에서 명령을 실행한다.

웹 브라우저에서 http://127.0.0.1:8000/?token=jessica를 열어 애플리케이션을 테스트한다.

배포

FastAPI 애플리케이션을 Docker로 배포하려면 다음과 같은 Dockerfile을 사용한다:

Dockerfile

FROM python:3.12-slim

# uv 설치
COPY --from=ghcr.io/astral-sh/uv:latest /uv /uvx /bin/

# 애플리케이션을 컨테이너로 복사
COPY . /app

# 애플리케이션 의존성 설치
WORKDIR /app
RUN uv sync --frozen --no-cache

# 애플리케이션 실행
CMD ["/app/.venv/bin/fastapi", "run", "app/main.py", "--port", "80", "--host", "0.0.0.0"]

Docker 이미지를 빌드하려면 다음 명령어를 실행한다:

$ docker build -t fastapi-app .

로컬에서 Docker 컨테이너를 실행하려면 다음 명령어를 사용한다:

$ docker run -p 8000:80 fastapi-app

브라우저에서 http://127.0.0.1:8000/?token=jessica로 이동해 애플리케이션이 정상적으로 실행되는지 확인한다.

Tip

Docker와 uv를 함께 사용하는 방법에 대한 자세한 내용은 Docker 가이드를 참조한다.