Как установить и запустить FastAPI

Чтобы установить FastAPI, создайте виртуальное окружение и выполните pip install "fastapi[standard]". Запустить сервер можно командой fastapi dev main.py — приложение откроется по адресу http://127.0.0.1:8000, а документация API — на /docs.

python -m venv .venv
.venv\Scripts\activate          # Windows
source .venv/bin/activate       # macOS / Linux
pip install "fastapi[standard]"
fastapi dev main.py

Ниже — каждый шаг подробно: проверка Python, установка, первый файл приложения, три способа запуска сервера, настройка хоста и порта и решения типичных ошибок. Команды проверены на FastAPI 0.143 и Python 3.12.

Что нужно перед установкой

Актуальные версии FastAPI требуют Python 3.10 или новее. Проверьте версию:

python --version      # Windows (или py --version)
python3 --version     # macOS / Linux

Если команда не найдена или версия ниже 3.10, сначала установите Python. Как узнать версию другими способами — в статье как проверить версию Python.

Дальше в статье для краткости используется python. На macOS и Linux подставляйте python3, если python указывает на старую версию или отсутствует.

Создайте папку проекта и виртуальное окружение

Устанавливать FastAPI в системный Python не стоит: у каждого проекта должны быть свои версии пакетов. Создайте папку и виртуальное окружение в ней:

mkdir fastapi-app
cd fastapi-app
python -m venv .venv

Активируйте окружение.

Windows (PowerShell или cmd):

.venv\Scripts\activate

macOS / Linux:

source .venv/bin/activate

После активации в начале строки терминала появится (.venv). Все следующие команды выполняйте в активированном окружении. Если PowerShell пишет, что выполнение сценариев отключено, или вы хотите разобраться, как работают окружения, — смотрите статью про виртуальное окружение venv.

Установите FastAPI

pip install "fastapi[standard]"

Что входит в разные варианты установки:

Команда	Что ставится
pip install "fastapi[standard]"	FastAPI, Uvicorn, команда fastapi (dev, run), HTTPX для тестов, email-validator, python-multipart, pydantic-settings и другие
pip install fastapi	только фреймворк с Pydantic и Starlette — без сервера и без рабочей команды fastapi
pip install "fastapi[standard-no-fastapi-cloud-cli]"	как standard, но без утилиты для облачного сервиса FastAPI Cloud

Для начала берите fastapi[standard] — в нём есть всё, что используется в учебниках. Кавычки вокруг имени пакета нужны в zsh (оболочка по умолчанию в macOS): без них она пытается разобрать квадратные скобки как шаблон файлов. В PowerShell, cmd и bash кавычки не мешают, поэтому их удобно писать всегда.

Если вы поставили «голый» fastapi, команда fastapi dev подскажет, что делать:

To use the fastapi command, please install "fastapi[standard]":

	pip install "fastapi[standard]"

Проверьте установку:

python -c "import fastapi; print(fastapi.__version__)"
# → 0.143.0

fastapi --version
# → FastAPI CLI version: 0.0.32
# → FastAPI Cloud CLI version: 0.26.0

Номера версий у вас могут быть новее. Чтобы зафиксировать зависимости проекта, сохраните их в файл: pip freeze > requirements.txt. Подробнее об установке пакетов — в статье про pip.

Создайте файл main.py

В папке проекта создайте файл main.py:

from fastapi import FastAPI

app = FastAPI()


@app.get("/")
def root():
    return {"message": "Привет, FastAPI!"}


@app.get("/items/{item_id}")
def read_item(item_id: int, q: str | None = None):
    return {"item_id": item_id, "q": q}

Здесь два эндпоинта: корневой / и /items/{item_id} с параметром пути и необязательным query-параметром q. Что означает каждая строка и как развивать приложение дальше — в руководстве по FastAPI.

Запустите сервер: fastapi dev

fastapi dev main.py

Вывод в терминале (пути и номера процессов у вас будут свои):

 ⚡️ Starting FastAPI in development mode

 🐍 Using import string: main:app

 🌐 Server started at http://127.0.0.1:8000
    Documentation at http://127.0.0.1:8000/docs

  Logs:

INFO:     Will watch for changes in these directories: ['C:\\projects\\fastapi-app']
INFO:     Uvicorn running on http://127.0.0.1:8000 (Press CTRL+C to quit)
INFO:     Started reloader process [29612] using WatchFiles
INFO:     Started server process [30272]
INFO:     Waiting for application startup.
INFO:     Application startup complete.

Проверьте результат в браузере:

• http://127.0.0.1:8000/ → {"message":"Привет, FastAPI!"}
• http://127.0.0.1:8000/items/5?q=test → {"item_id":5,"q":"test"}
• http://127.0.0.1:8000/docs — интерактивная документация Swagger UI
• http://127.0.0.1:8000/redoc — та же документация в виде справочника

Режим fastapi dev включает автоперезагрузку: сохраните изменения в main.py, и сервер перезапустится сам. Остановить сервер — Ctrl+C.

Путь к файлу можно не указывать. Без аргумента fastapi dev ищет приложение по очереди в main.py, app.py, api.py, app/main.py, app/app.py, app/api.py, а внутри файла — переменную app или api.

Запуск через uvicorn

fastapi dev — обёртка над ASGI-сервером Uvicorn. Тот же результат даёт прямой запуск Uvicorn:

uvicorn main:app --reload

main:app читается так: модуль main (файл main.py), в нём переменная app. Если приложение лежит в app/main.py и называется application, команда будет uvicorn app.main:application --reload. Флаг --reload включает автоперезагрузку — без него изменения в коде не подхватятся.

Если команда uvicorn не находится, запускайте его через интерпретатор — так используется Python из активного окружения:

python -m uvicorn main:app --reload

Запуск из кода: python main.py

Запускать сервер кнопкой Run в PyCharm или VS Code удобнее, если main.py сам стартует Uvicorn. Добавьте в конец файла:

if __name__ == "__main__":
    import uvicorn

    uvicorn.run("main:app", host="127.0.0.1", port=8000, reload=True)

Теперь сервер запускается командой python main.py. Приложение передаётся строкой "main:app", а не объектом app: для режима reload=True Uvicorn требует строку импорта. Про другие способы запуска скриптов — в статье как запустить Python-скрипт.

fastapi run: запуск в продакшне

fastapi run main.py

Отличия от fastapi dev:

Параметр	fastapi dev	fastapi run
Автоперезагрузка	включена	выключена
Адрес по умолчанию	127.0.0.1	0.0.0.0 (все интерфейсы)
Порт по умолчанию	8000	8000
Несколько воркеров	нет	--workers 4

fastapi run подходит для сервера и Docker-контейнера. Перед приложением обычно ставят обратный прокси — Nginx или Traefik, — который обслуживает HTTPS и раздаёт статику. Эквивалент через Uvicorn: uvicorn main:app --host 0.0.0.0 --port 8000 --workers 4.

Как изменить хост и порт

Порт и адрес задаются одинаково для fastapi dev, fastapi run и uvicorn:

fastapi dev main.py --port 8080
fastapi dev main.py --host 0.0.0.0 --port 8080
uvicorn main:app --reload --host 0.0.0.0 --port 8080

• --host 127.0.0.1 — сервер доступен только с вашего компьютера (по умолчанию в fastapi dev и uvicorn).
• --host 0.0.0.0 — сервер слушает все сетевые интерфейсы: к нему можно обратиться с телефона в той же сети или из другого контейнера. В браузере при этом открывайте http://127.0.0.1:8080 или IP компьютера — адрес 0.0.0.0 в браузере не используют.
• Команда fastapi также читает порт из переменной окружения PORT, если опция --port не указана.

Частые ошибки

«‘uvicorn’ не является внутренней или внешней командой»

Полный текст в cmd: 'uvicorn' не является внутренней или внешней командой, исполняемой программой или пакетным файлом (в английской Windows — 'uvicorn' is not recognized as an internal or external command). В PowerShell — Имя "uvicorn" не распознано как имя командлета, функции, файла сценария или выполняемой программы (The term 'uvicorn' is not recognized as the name of a cmdlet...). В macOS с оболочкой zsh — zsh: command not found: uvicorn, в Linux с bash — uvicorn: command not found.

Причины и решения:

1. Не активировано виртуальное окружение. Активируйте его — в строке терминала должно быть (.venv).
2. Uvicorn не установлен. Вы поставили pip install fastapi без [standard]. Выполните pip install "fastapi[standard]".
3. Пакеты установлены в другой Python. Запускайте сервер через интерпретатор: python -m uvicorn main:app --reload. Этот вариант работает, даже если папка Scripts (или bin) не попала в PATH.

С командой fastapi то же самое: если она не находится, используйте python -m fastapi dev main.py.

ModuleNotFoundError: No module named ‘fastapi’

Скрипт запущен не тем интерпретатором: например, редактор использует системный Python, а FastAPI установлен в .venv. Выберите интерпретатор окружения в настройках IDE или запускайте через python -m ... в активированном окружении. Разбор всех причин — в статье про ModuleNotFoundError.

Error loading ASGI app. Could not import module “main”

ERROR:    Error loading ASGI app. Could not import module "main".

Uvicorn не нашёл файл main.py. Проверьте, что вы в той папке, где он лежит (cd fastapi-app), и что имя модуля написано без опечаток и без .py: правильно main:app, неправильно main.py:app.

Attribute “app” not found in module “main”

ERROR:    Error loading ASGI app. Attribute "app" not found in module "main".

Переменная с приложением называется иначе. Если в коде application = FastAPI(), запускайте uvicorn main:application.

Could not find a default file to run

fastapi dev без аргументов не нашёл ни одного файла из списка по умолчанию. Укажите путь явно: fastapi dev src/server.py. Если не находится переменная приложения, добавьте --app application.

Порт уже занят

ERROR:    [Errno 10048] error while attempting to bind on address ('127.0.0.1', 8000): [winerror 10048] only one usage of each socket address (protocol/network address/port) is normally permitted

Так ошибка выглядит в Windows. В Linux вместо 10048 будет [Errno 98] и текст address already in use, в macOS — [Errno 48] с тем же текстом. На порту 8000 уже работает другой процесс, часто — забытый сервер в соседнем терминале. Остановите его или запустите приложение на другом порту: --port 8001.

zsh: no matches found: fastapi[standard]

Вы ввели имя пакета без кавычек в zsh. Повторите команду с кавычками: pip install "fastapi[standard]".

Чек-лист установки

• Python 3.10+ (python --version)
• создано и активировано виртуальное окружение — в терминале видно (.venv)
• выполнено pip install "fastapi[standard]"
• main.py содержит app = FastAPI() и хотя бы один эндпоинт
• fastapi dev main.py запускается, http://127.0.0.1:8000/docs открывается
• зависимости сохранены в requirements.txt

Частые вопросы

Как установить FastAPI в PyCharm или VS Code?

Откройте папку проекта и выберите интерпретатор из .venv: в PyCharm — Settings → Project → Python Interpreter, в VS Code — команда «Python: Select Interpreter». Затем выполните pip install "fastapi[standard]" во встроенном терминале редактора: он сам активирует выбранное окружение. Если редактор подчёркивает from fastapi import FastAPI как неизвестный модуль, чаще всего выбран не тот интерпретатор.

Можно ли установить FastAPI через uv?

Да. uv — менеджер пакетов и окружений, который заменяет venv и pip. В папке проекта выполните:

uv init --bare
uv add "fastapi[standard]"
uv run fastapi dev main.py

uv init --bare создаёт только pyproject.toml, uv add — окружение .venv и запись о зависимости, а uv run запускает команду внутри окружения, поэтому активировать его вручную не нужно.

Как обновить FastAPI или поставить конкретную версию?

Обновление до последней версии — pip install --upgrade "fastapi[standard]". Конкретная версия указывается после ==: pip install "fastapi[standard]==0.143.0". Перед обновлением рабочего проекта прочитайте список изменений в release notes FastAPI: до версии 1.0 изменения, ломающие совместимость, выходят и в минорных версиях.

Будет ли FastAPI работать на Python 3.9?

Последние версии — нет: начиная с FastAPI 0.129 (февраль 2026) нужен Python 3.10 или новее. На Python 3.9 pip сам выберет последнюю совместимую версию из ветки 0.128, но новые возможности и исправления туда уже не попадут. Лучше установить актуальный Python и создать окружение заново.

Итог

Установка FastAPI сводится к трём командам: создать окружение, активировать его и выполнить pip install "fastapi[standard]". Для разработки запускайте fastapi dev main.py, для сервера — fastapi run, а если команды не находятся, выручит python -m uvicorn main:app --reload.

Дальше переходите к руководству по FastAPI: параметры, модели, зависимости и тесты. Для описания данных запросов понадобится Pydantic.