Open WebUI через Python: uv и изолированное окружение

Иногда Open WebUI нужно запустить через Python без контейнеров. При этом хочется отделить его зависимости от системных библиотек и после остановки процесса вернуться к той же установке. В общей среде возможны конфликты версий. Другой путь к данным может открыть пустой экземпляр, а смена рабочей папки при запуске может потребовать повторного входа из-за нового ключа сессий. Это не удаляет учётную запись. Подготовим отдельное окружение через uv, выберем папки для пакетов и данных, затем проверим остановку и повторный запуск.

Запуск через Python можно выбрать вместо Docker; сравнение подходов есть в материале про выбор способа установки. Здесь пройдём один маршрут для локального компьютера с Ubuntu 24.04 (x86_64), стандартной оболочкой Bash и работой на процессоре (CPU) без видеокарты NVIDIA. Все команды выполним от имени обычного пользователя, а интерфейс откроем в браузере на той же машине. Для скачивания интерпретатора и пакетов понадобится доступ в интернет и свободное место на диске.

Разделим окружение приложения, данные и ключ сессий

Разберём роли компонентов. Python исполняет код, uv подбирает интерпретатор и устанавливает пакеты, папка .venv хранит окружение с библиотеками, а процесс open-webui serve обслуживает запросы браузера. Если не задать пути явно, при пакетном запуске база данных и файлы приложения могут оказаться глубоко внутри папки .venv (в подкаталоге site-packages/open_webui/data), а секретный ключ для подписи сессий создастся в том каталоге, откуда вы случайно вызвали команду.

Пакеты, данные и ключ сессий будем хранить раздельно в домашнем каталоге. Тогда пересоздание .venv не затронет внешнюю папку с чатами и настройками:

Виртуальное окружение изолирует библиотеки, но не ограничивает права процесса на файлы и сеть. Файл .webui_secret_key используется для подписи сеансов. Его содержимое не нужно открывать или выводить на экран. Будем запускать сервер из одной папки $HOME/open-webui-python, чтобы он находил прежний ключ.

Эти пути рассчитаны на новую установку. Пользователи, история и подключения к моделям из прежнего Docker-экземпляра сами в неё не перенесутся. Если $HOME/open-webui-python или $HOME/.local/share/open-webui-python уже содержат нужные данные, сначала разберитесь с ними. Ничего не удаляйте наугад.

В документации есть и установка через Conda. Если вы уже пользуетесь ею, это ещё один способ подготовить среду с нужным Python. В нашем маршруте после выбора uv Conda не требуется.

Подготовим uv и окружение Python 3.11

Open WebUI требует Python не ниже 3.11 и ниже 3.13. В официальном руководстве быстрого старта рекомендуется 3.11, также поддерживается 3.12. Здесь выберем 3.11. Менеджер uv от Astral найдёт подходящий интерпретатор или скачает сборку, поэтому устанавливать эту версию в системную среду Ubuntu заранее не нужно.

На дату чтения документации, 17 октября 2026 года, в рецепте выбраны версии: uv выпуска 0.13.1, Python 3.11 и пакет Open WebUI 0.12.3. Если uv ещё не установлен, поставим 0.13.1 через официальный установочный скрипт без sudo. Другую уже работающую версию переустанавливать поверх не обязательно:

curl -LsSf https://astral.sh/uv/0.13.1/install.sh | sh
uv --version

Если после установки команда uv не найдена, следуйте подсказке установщика для обновления PATH или откройте новое окно Bash. Затем повторите uv --version.

Создадим рабочую папку, внешний каталог данных и окружение .venv с Python 3.11:

mkdir -p "$HOME/open-webui-python" "$HOME/.local/share/open-webui-python"
cd "$HOME/open-webui-python"
uv venv --python 3.11 .venv
.venv/bin/python --version

mkdir -p создаст недостающие каталоги, но не проверит, пусты ли существующие. После перехода в $HOME/open-webui-python инструмент uv подготовит .venv с Python 3.11; патч-релиз он подберёт сам. Последняя команда проверяет интерпретатор именно этой среды. Убедитесь, что она показывает 3.11.x.

В этом рецепте не нужны sudo pip, --system и изменение системного Python. Активация через source .venv/bin/activate тоже не обязательна. Как описано в документации стандартного модуля venv и руководстве uv, путь .venv/bin/python выбирает конкретный интерпретатор, а .venv/bin/open-webui запускает установленное в этой среде приложение. Эти пути будем использовать и в новом терминале.

В документации может встретиться и команда uvx (или проектный запуск uv run). Команда uvx предназначена для быстрого вызова утилит в отдельном временном или кэшированном окружении, которым управляет сам uv. Здесь мы создаём свою .venv и запускаем сервер одним и тем же исполняемым файлом.

Установим Open WebUI и проверим зависимости

Для Linux x86_64 без NVIDIA начнём с предварительного шага из руководства Open WebUI и справки uv по интеграции с PyTorch. Поставим torch для процессора из CPU-индекса PyTorch, чтобы по возможности не скачивать ненужные здесь библиотеки CUDA:

uv pip install --python .venv/bin/python torch --index-url https://download.pytorch.org/whl/cpu

Флаг --python .venv/bin/python указывает среду установки. Дополнительные библиотеки вроде torchvision или torchaudio, которые иногда встречаются в общих примерах по PyTorch, здесь добавлять не нужно.

Следом установим сам пакет open-webui версии 0.12.3 из PyPI и сразу выполним три проверочные команды для чтения состояния окружения:

uv pip install --python .venv/bin/python "open-webui==0.12.3"
uv pip show --python .venv/bin/python open-webui
uv pip check --python .venv/bin/python
uv pip show --python .venv/bin/python torch

Готовый wheel-архив open-webui уже содержит веб-интерфейс. Его конфигурация pyproject.toml регистрирует команду open-webui, поэтому Git, Node.js и сборка через npm здесь не нужны. Запись open-webui==0.12.3 фиксирует версию приложения, но не полный набор версий его зависимостей, как в lock-файле.

Посмотрим, как читать результаты проверочных команд uv pip show и uv pip check:

• Вызов uv pip show --python .venv/bin/python open-webui должен показать метаданные установленного пакета с версией 0.12.3.
• Команда uv pip check --python .venv/bin/python проверяет совместимость зависимостей в .venv. Если она сообщает о конфликте, сначала разберитесь с ним в этой среде и лишь затем запускайте сервер. Случайные старые советы из интернета могут относиться к другим версиям.
• Вызов uv pip show --python .venv/bin/python torch показывает установленную версию torch. При установке зависимостей Open WebUI менеджер может заменить ранее установленный CPU-пакет. Команды show и check сообщают о версии и совместимости, но не доказывают, что сохранилась CPU-сборка.

Установка пакета и проверка библиотек ещё не означают, что веб-сервер работает. Запустим его с явным каталогом данных и локальным адресом.

Запустим сервер и откроем локальный интерфейс

Перед запуском свяжем параметры команды с выбранными папками и адресом:

1. Рабочий каталог и ключ сессий. Если переменная WEBUI_SECRET_KEY не задана, приложение читает или создаёт .webui_secret_key в текущей рабочей папке (cwd), как предусмотрено в коде запуска Open WebUI. Это не каталог DATA_DIR. Поэтому перед каждым стартом перейдём в $HOME/open-webui-python.
2. Явный каталог данных DATA_DIR. В настройках окружения env.py путь к хранилищу (и базе SQLite webui.db) берётся из переменной DATA_DIR. Префикс DATA_DIR="$HOME/.local/share/open-webui-python" в строке запуска задаёт эту переменную для стартующего процесса. В нашем примере она укажет на внешнюю папку данных.
3. Локальный адрес и порт. Без дополнительных флагов команда open-webui serve в версии 0.12.3 по умолчанию слушает все сетевые интерфейсы (0.0.0.0) на порту 8080. Для браузера на той же машине зададим локальный адрес --host 127.0.0.1 и порт --port 8080. В прежних уроках с Docker наружу пробрасывался порт 3000; здесь обращаемся прямо к 8080.

Выполним переход в рабочую папку и запустим сервер:

cd "$HOME/open-webui-python"
DATA_DIR="$HOME/.local/share/open-webui-python" .venv/bin/open-webui serve --host 127.0.0.1 --port 8080

Сервер работает на переднем плане (foreground): этот терминал занят его процессом и показывает журнал инициализации и миграций. Закрытие вкладки браузера процесс не останавливает.

Дополнительно проверить готовность можно во втором терминале через необязательный запрос к /ready:

curl --fail --silent --show-error http://127.0.0.1:8080/ready

Успешный ответ от /ready (в коде приложения он возвращает JSON со статусом готовности) подтверждает, что процесс поднялся и база данных доступна, но не проверяет подключение языковых моделей.

Когда сервер завершит инициализацию, откройте в браузере на этой же Ubuntu-машине адрес http://127.0.0.1:8080. Поскольку мы не отключали авторизацию и указали свежую папку DATA_DIR, при первом открытии должен появиться экран регистрации администратора. Создайте здесь выделенную учебную учётную запись для проверки нашего экземпляра (подробно логику этого экрана мы разбирали в уроке про первую учебную учётную запись). Не используйте в учебных примерах свои реальные пароли от других сервисов; подключать модели, прописывать API-ключи или отправлять запросы в чат сейчас не нужно. Если вместо регистрации вы увидели уже настроенный интерфейс или неожиданное окно входа, остановитесь и проверьте адрес, путь к данным и то, какой экземпляр слушает порт 8080.

Теперь проверим, что после остановки сервера мы сможем вернуться ровно в тот же экземпляр, а не создадим пустую базу заново.

Остановим сервер и вернёмся в тот же экземпляр

В терминале с open-webui serve нажмите Ctrl+C. Дождитесь завершения процесса и возвращения приглашения Bash. При остановке процесса установленные в .venv пакеты, база данных в $HOME/.local/share/open-webui-python и файл ключа .webui_secret_key в рабочей папке остаются на диске нетронутыми.

Для повторного запуска сейчас или на следующий день устанавливать uv и пакеты заново не нужно. Вернитесь в ту же папку и повторите команду с тем же DATA_DIR:

cd "$HOME/open-webui-python"
DATA_DIR="$HOME/.local/share/open-webui-python" .venv/bin/open-webui serve --host 127.0.0.1 --port 8080

Дождитесь готовности сервера в терминале и снова откройте http://127.0.0.1:8080 в браузере. Разберём, как правильно интерпретировать то, что вы увидите на экране:

• Проверьте, что доступен вход в учебную учётную запись, созданную до остановки, а не повторная регистрация первого администратора.
• Если интерфейс открылся благодаря сохранённому сеансу, выйдите из аккаунта и войдите снова. Так вы проверите доступ к ранее созданной учётной записи по логину и паролю.
• Успешный вход подтверждает доступ к прежней учётной записи, но не доказывает, что используется тот же файл базы или .webui_secret_key. Изменение ключа, например при запуске из другой папки, может сделать старые сеансы недействительными. Оно не удаляет учётную запись и не мешает войти заново по паролю.

Ручной запуск не создаёт системную службу и не включает приложение после перезагрузки Ubuntu. Внешний DATA_DIR сохраняет данные при пересоздании .venv, но не заменяет резервную копию. Перед обновлением отдельно сохраните данные и файл ключа. Копирование одного webui.db во время работы сервера не является полным бэкапом каталога. Возврат старой версии пакета также не откатывает миграции схемы базы. Общие принципы разобраны в уроке про обновление и резервное копирование, но его команды относятся к Docker и не служат рецептом бэкапа этой Python-установки.

Если результат отличается от ожидаемого, не удаляйте папки. Сначала проверьте шаг, на котором возникла проблема.

Разберём частые ошибки запуска

По сообщению терминала или экрану браузера можно выбрать, что проверить сначала:

Если установка, открытие интерфейса и повторный вход прошли успешно, отдельный экземпляр готов к дальнейшей настройке. Пакеты находятся в .venv, данные в выбранном DATA_DIR, а ключ сессий в рабочей папке. Для возвращения к нему достаточно повторить сохранённую команду из того же каталога. Подключение моделей и автозапуск остаются отдельными задачами.