Нужен ли Gunicorn для FastAPI сегодня и когда выбрать Uvicorn

Почему в продакшене FastAPI часто не нужен Gunicorn: Uvicorn и fastapi run дают супервизор, многопроцессность и авто‑перезапуск; когда выбрать Gunicorn

Раньше в продакшене FastAPI чаще всего запускали в связке Gunicorn + Uvicorn. Теперь рекомендации изменились. В Uvicorn появился встроенный супервизор для многопроцессного режима, FastAPI обновил инструменты, а популярный Docker‑образ с Gunicorn признан устаревшим. Если вы сомневаетесь, нужен ли вам ещё Gunicorn и равнозначны ли команды fastapi run и gunicorn, в этом материале — короткий, по делу, разбор.

Минимальный пример по мотивам вопроса

Предположим, у нас есть небольшое FastAPI‑приложение в файле server.py. Цель — показать способы запуска, а не логику приложения.

# server.py
from fastapi import FastAPI

svc = FastAPI()

@svc.get("/health")
async def healthcheck():
    return {"ok": True}

Два варианта запуска с несколькими воркерами могут выглядеть так:

# Запуск через FastAPI CLI, который оборачивает Uvicorn
fastapi run --workers 4 server.py

# Запуск через Gunicorn с классом воркера Uvicorn
gunicorn server:svc -w 4 -k uvicorn.workers.UvicornWorker

Что изменилось и почему это важно

Начиная с Uvicorn 0.30 (май 2024), встроенный супервизор напрямую управляет многопроцессной работой. Он умеет поднимать несколько процессов через --workers, автоматически перезапускать упавшие воркеры и ограничивать число запросов параметром --limit-max-requests для борьбы с утечками. Вскоре после этого Docker‑образ tiangolo/uvicorn-gunicorn-fastapi был помечен как устаревший со следующим обоснованием:

Теперь, когда Uvicorn умеет управлять воркерами через --workers, включая перезапуск «упавших», в Gunicorn нет необходимости.

Начиная с FastAPI 0.110, fastapi run — это тонкая обёртка над новым супервизором Uvicorn. Сам Uvicorn больше не рекомендует использовать связку с Gunicorn. В итоге в большинстве случаев базовой рекомендацией стал «чистый» Uvicorn или fastapi run.

Нужен ли современному FastAPI Gunicorn?

Нет. Начиная с Uvicorn 0.30 вам не нужен Gunicorn для управления воркерами. Супервизор Uvicorn закрывает основные продакшен‑возможности, ради которых долгое время собирали комбинированный стек.

Равнозначны ли fastapi run и gunicorn?

Нет. Это разные реализации, даже если обе умеют запускать несколько воркеров для одного приложения. FastAPI CLI делегирует запуск встроенному супервизору Uvicorn, тогда как Gunicorn использует собственный мастер‑процесс и класс uvicorn.workers.UvicornWorker. Одна практическая ниша, где Gunicorn по‑прежнему выделяется, — интеграция с systemd. Он поддерживает наследование слушающих сокетов от .socket‑юнитов systemd и реализует sd_notify при запуске как Type=notify. Если эти возможности для вас критичны, Gunicorn остаётся уместным выбором.

Рекомендованный способ запуска FastAPI сегодня

В большинстве случаев используйте напрямую Uvicorn или FastAPI CLI. Оба опираются на супервизор Uvicorn, появившийся в версии 0.30, и обеспечивают многопроцессный режим с автоматическим перезапуском воркеров.

# Напрямую через Uvicorn
uvicorn server:svc --workers 4

# Через FastAPI CLI (тонкая обёртка над супервизором Uvicorn)
fastapi run --workers 4 server.py

Если у вас есть конкретные требования по systemd — активация сокетов или sd_notify, — используйте Gunicorn с воркером Uvicorn.

Почему это важно

Базовые практики эксплуатации изменились. Стек можно упростить, отказавшись от лишнего процесс‑менеджера, если его уникальные функции вам не нужны. Деприкация Docker‑образа tiangolo/uvicorn-gunicorn-fastapi и курс FastAPI на супервизор Uvicorn показывают направление для типичных продакшен‑развёртываний, оставляя пространство для окружений, где важны возможности systemd.

Итоги

В современных развёртываниях FastAPI, как правило, не нужен Gunicorn: в Uvicorn 0.30 появился супервизор с --workers, авто‑перезапуском и лимитированием запросов. fastapi run использует тот же супервизор, поэтому это удобный выбор по умолчанию. Запуск через Gunicorn с uvicorn.workers.UvicornWorker устроен иначе и по‑прежнему уместен, если вам нужны особенности systemd — активация сокетов и sd_notify. Выбирайте более простой путь, когда он закрывает задачи, а Gunicorn держите под рукой для случаев, где его интеграция с systemd — решающий аргумент.