Оригинал: https://timofei-ermolaev.ru/courses/open-webui/drugie-sposoby/open-webui-python/ # Open WebUI через Python: uv и изолированное окружение Поможем запустить Open WebUI через uv в отдельном Python-окружении на Ubuntu, сохранить данные и проверить повторный запуск без Docker. [![Тимофей Ермолаев](https://timofei-ermolaev.ru/_astro/timofei-ermolaev-portrait.s0mCFw-J_Z1x8STQ.webp)]() [Тимофей Ермолаев]() Директор по информационным технологиям (CIO) **Опубликовано** 17 октября 2026 г. **Обновлено** 17 октября 2026 г. **На урок** 25 мин **Тема** [Другие способы развёртывания]() ## После урока вы сможете - Различать Python, uv, окружение пакетов и данные приложения - Устанавливать Open WebUI в отдельное окружение на Ubuntu - Запускать локальный экземпляр с явно заданным местом данных - Проверять остановку и повторный вход после запуска **Проверяемый результат:** Локальный Python-экземпляр Open WebUI открывается в браузере. После остановки и повторного запуска с прежними настройками доступна учебная учётная запись. Иногда 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` не затронет внешнюю папку с чатами и настройками: | Путь в файловой системе | Что здесь находится | Зачем это нужно при запуске и перезапуске | | --- | --- | --- | | `$HOME/open-webui-python/.venv` | Изолированный интерпретатор Python и установленные пакеты | Позволяет ставить и проверять зависимости приложения отдельно от системного Python | | `$HOME/.local/share/open-webui-python` | Внешний каталог `DATA_DIR` (включая базу `webui.db` и файлы) | Сохраняет учётные записи и настройки вне папки `.venv` между остановками сервера | | `$HOME/open-webui-python/.webui_secret_key` | Сгенерированный приложением файл секретного ключа сессий | Создаётся и читается в текущем рабочем каталоге запуска (`cwd`), если не задан через переменную | Виртуальное окружение изолирует библиотеки, но не ограничивает права процесса на файлы и сеть. Файл `.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-установки. Если результат отличается от ожидаемого, не удаляйте папки. Сначала проверьте шаг, на котором возникла проблема. ## Разберём частые ошибки запуска По сообщению терминала или экрану браузера можно выбрать, что проверить сначала: | Что наблюдается в терминале или браузере | Возможная причина | Что проверить и сделать | | --- | --- | --- | | Оболочка пишет `uv: command not found` | Каталог установки `uv` ещё не добавлен в `PATH` текущей сессии Bash | Открыть новое окно терминала или выполнить команду обновления `PATH`, которую показал установщик, и проверить `uv --version` | | Ошибка `No such file or directory` для `.venv/bin/python` или `.venv/bin/open-webui` | Команда вводится не из папки `$HOME/open-webui-python` или шаг `uv venv` был пропущен | Перейти в рабочий каталог через `cd "$HOME/open-webui-python"` и проверить наличие среды `.venv` | | `uv pip check` сообщает о несовместимых пакетах | В окружении возник конфликт версий зависимостей | Проверить вывод для этого же интерпретатора `--python .venv/bin/python` и устранить конфликт в среде до запуска сервера | | При старте `serve` появляется ошибка занятого порта `8080` (`Address already in use`) | На порту `8080` уже работает прошлый экземпляр Open WebUI или другая локальная программа | Не завершать неизвестные процессы вслепую; выяснить, что занимает порт, либо явно указать свободный порт (например, `--port 8081`) и открыть соответствующий адрес в браузере | | Страница `http://127.0.0.1:8080` не открывается | Сервер ещё не закончил инициализацию, был остановлен сочетанием `Ctrl+C` или завершился с ошибкой | Посмотреть последние строки в том окне терминала, где запущен `serve` (при разборе ошибок не публикуйте в сети полные логи с секретами) | | После перезапуска снова открывается экран создания первого администратора | Команда запущена без переменной `DATA_DIR`, с опечаткой в пути или вы подключились к другому экземпляру | Остановить сервер и запустить его с точным префиксом `DATA_DIR="$HOME/.local/share/open-webui-python"` | | Приложение просит снова ввести логин и пароль | Истёк сеанс или сервер был запущен из другого рабочего каталога (`cwd`), где создался новый `.webui_secret_key` | Не путать запрос входа с потерей базы: войти под своей учётной записью, а впредь всегда выполнять `cd "$HOME/open-webui-python"` перед стартом | Если установка, открытие интерфейса и повторный вход прошли успешно, отдельный экземпляр готов к дальнейшей настройке. Пакеты находятся в `.venv`, данные в выбранном `DATA_DIR`, а ключ сессий в рабочей папке. Для возвращения к нему достаточно повторить сохранённую команду из того же каталога. Подключение моделей и автозапуск остаются отдельными задачами. ## Материалы урока - [Open WebUI: Quick Start, Python docs.openwebui.com]() - [uv: Python-окружения docs.astral.sh]() ## Отметить прохождение Отметьте урок после того, как получили проверяемый результат из практической части. Урок пройден ![Тимофей Ермолаев](https://timofei-ermolaev.ru/_astro/timofei-ermolaev-portrait.s0mCFw-J_2r7Nkv.webp) ## Об авторе ### Тимофей Ермолаев Директор по информационным технологиям (CIO) Пишу о больших языковых моделях, автоматизации и применении ИИ в бизнесе. В статьях разделяю личный опыт, выводы исследований и практические рекомендации. [Подробнее об авторе]()