github-starred/open-webui
2
0
Fork 0
mirror of https://github.com/open-webui/open-webui.git synced 2026-07-17 08:21:12 -05:00
Code Issues 2.4k Packages Projects Releases 129 Wiki Activity

[PR #12617] [MERGED] feat: UVICORN_WORKERS variable and docs #77864

New Issue
Closed
opened 2026-05-13 11:25:37 -05:00 by GiteaMirror · 0 comments
GiteaMirror commented 2026-05-13 11:25:37 -05:00
Owner
Copy Link

📋 Pull Request Information

Original PR: https://github.com/open-webui/open-webui/pull/12617
Author: @Classic298
Created: 4/8/2025
Status: ✅ Merged
Merged: 4/8/2025
Merged by: @tjbck

Base: dev ← Head: dev

📝 Commits (5)

📊 Changes

4 files changed (+25 additions, -3 deletions)

View changed files

📝 backend/open_webui/__init__.py (+8 -1)
📝 backend/open_webui/env.py (+14 -0)
📝 backend/start.sh (+1 -1)
📝 backend/start_windows.bat (+2 -1)

📄 Description

Pull Request Checklist

Before submitting, make sure you've checked the following:

  • Target branch: Please verify that the pull request targets the dev branch.
  • Description: Provide a concise description of the changes made in this pull request.
  • Changelog: Ensure a changelog entry following the format of Keep a Changelog is added at the bottom of the PR description.
  • Documentation: Have you updated relevant documentation Open WebUI Docs, or other documentation sources?
  • Dependencies: Are there any new dependencies? Have you updated the dependency versions in the documentation?
  • Testing: Have you written and run sufficient tests to validate the changes?
  • Code review: Have you performed a self-review of your code, addressing any coding standard issues and ensuring adherence to the project's coding standards?
  • Prefix: To clearly categorize this pull request, prefix the pull request title using one of the following:
    • feat: Introduces a new feature or enhancement to the codebase

Changelog Entry

Description

This PR adds support for running OpenWebUI with multiple Uvicorn worker processes via a new environment variable UVICORN_WORKERS. This enhancement improves scalability and performance on multi-core systems by allowing the application to handle more concurrent requests.

Why it is needed

  • As discussed in the discussion, the only other way to use multiple uvicorn workers is by manually editing the respective files (in the venv or in the docker) and this is NOT recommended for obvious reasons.
    • Furthermore, any edits and modifications to these files will be gone by the next time you update your open-webui (files get overwritten by new update).
  • Finally, using WEB_CONCURRENCY (the variable used by uvicorn) does not work by our tests (see disc.), because OpenWebUI is calling uvicorn directly in the __init__.py file -> variable needs to be passed directly, instead.

So, a proper solution is needed.

Documentation: https://github.com/open-webui/docs/pull/482

Solves

Solves this issue https://github.com/open-webui/open-webui/issues/12286
Solves this discussion https://github.com/open-webui/open-webui/discussions/12362
Solves this discussion https://github.com/open-webui/open-webui/discussions/9032

Relates to

Related to:
https://github.com/open-webui/open-webui/issues/10365#issuecomment-2784050405

Added

Added new environment variable UVICORN_WORKERS to control the number of Uvicorn worker processes
Added worker parameter to all server startup methods (start.sh, windows-start.bat, init.py)
Added validation and normalization of the worker count (ensuring it's at least 1 and defaults to 1)

Changed

Modified the serve() command in init.py to use the configured number of workers
Modified the dev() command to conditionally use multiple workers only when hot-reload is disabled
Updated bash and batch scripts to respect the UVICORN_WORKERS environment variable

Additional Information

The default value is 1 worker, if environment variable is not specified.
If a kubernetes/k8s/helm multi-node (multi pod) cluster is being used, it is advised to NOT change the UVICORN_WORKERS variable, i.e. leave it at it's default value, which is 1.
A pod should only run one uvicorn worker at a time.

Works with all startup methods: pip install startup (open-webui serve), bash script (start.sh), and Windows script (windows-start.bat)

Screenshots or Videos

N/A (Server-side enhancement with no visual changes)

🔄 This issue represents a GitHub Pull Request. It cannot be merged through Gitea due to API limitations.

## 📋 Pull Request Information **Original PR:** https://github.com/open-webui/open-webui/pull/12617 **Author:** [@Classic298](https://github.com/Classic298) **Created:** 4/8/2025 **Status:** ✅ Merged **Merged:** 4/8/2025 **Merged by:** [@tjbck](https://github.com/tjbck) **Base:** `dev` ← **Head:** `dev` --- ### 📝 Commits (5) - [`f822d89`](https://github.com/open-webui/open-webui/commit/f822d89350dc67a1c5adc399bbe216caf953b314) Update env.py - [`4c9a791`](https://github.com/open-webui/open-webui/commit/4c9a791b0640f5932d5c4219472a5580c403b046) Update env.py - [`2c1d0e3`](https://github.com/open-webui/open-webui/commit/2c1d0e385742d16f26b6e2eba23ec84826e51e1b) Update start.sh - [`65b5c6c`](https://github.com/open-webui/open-webui/commit/65b5c6c0c72b4ad30f76b54deb34e98dc5a3cf40) Update start_windows.bat - [`f17befc`](https://github.com/open-webui/open-webui/commit/f17befc853bee73d60354a1e62e78056dfed4a10) Update __init__.py ### 📊 Changes **4 files changed** (+25 additions, -3 deletions) <details> <summary>View changed files</summary> 📝 `backend/open_webui/__init__.py` (+8 -1) 📝 `backend/open_webui/env.py` (+14 -0) 📝 `backend/start.sh` (+1 -1) 📝 `backend/start_windows.bat` (+2 -1) </details> ### 📄 Description # Pull Request Checklist **Before submitting, make sure you've checked the following:** - [X] **Target branch:** Please verify that the pull request targets the `dev` branch. - [X] **Description:** Provide a concise description of the changes made in this pull request. - [X] **Changelog:** Ensure a changelog entry following the format of [Keep a Changelog](https://keepachangelog.com/) is added at the bottom of the PR description. - [X] **Documentation:** Have you updated relevant documentation [Open WebUI Docs](https://github.com/open-webui/docs), or other documentation sources? - [X] **Dependencies:** Are there any new dependencies? Have you updated the dependency versions in the documentation? - [ ] **Testing:** Have you written and run sufficient tests to validate the changes? - [X] **Code review:** Have you performed a self-review of your code, addressing any coding standard issues and ensuring adherence to the project's coding standards? - [X] **Prefix:** To clearly categorize this pull request, prefix the pull request title using one of the following: - **feat**: Introduces a new feature or enhancement to the codebase # Changelog Entry ### Description This PR adds support for running OpenWebUI with multiple Uvicorn worker processes via a new environment variable UVICORN_WORKERS. This enhancement improves scalability and performance on multi-core systems by allowing the application to handle more concurrent requests. **Why it is needed** - As discussed in [the discussion](https://github.com/open-webui/open-webui/discussions/9032), the only other way to use multiple uvicorn workers is by manually editing the respective files (in the venv or in the docker) and this is NOT recommended for obvious reasons. - Furthermore, **any edits and modifications to these files will be gone by the next time you update** your open-webui (files get overwritten by new update). - Finally, using WEB_CONCURRENCY (the variable used by uvicorn) does not work by our tests (see disc.), because OpenWebUI is calling uvicorn directly in the \_\_init\_\_.py file -> variable needs to be passed directly, instead. So, a proper solution is needed. Documentation: https://github.com/open-webui/docs/pull/482 ### Solves Solves this issue https://github.com/open-webui/open-webui/issues/12286 Solves this discussion https://github.com/open-webui/open-webui/discussions/12362 Solves this discussion https://github.com/open-webui/open-webui/discussions/9032 ### Relates to Related to: https://github.com/open-webui/open-webui/issues/10365#issuecomment-2784050405 ### Added Added new environment variable UVICORN_WORKERS to control the number of Uvicorn worker processes Added worker parameter to all server startup methods (start.sh, windows-start.bat, init.py) Added validation and normalization of the worker count (ensuring it's at least 1 and defaults to 1) ### Changed Modified the serve() command in init.py to use the configured number of workers Modified the dev() command to conditionally use multiple workers only when hot-reload is disabled Updated bash and batch scripts to respect the UVICORN_WORKERS environment variable ### Additional Information The default value is 1 worker, if environment variable is not specified. If a kubernetes/k8s/helm multi-node (multi pod) cluster is being used, it is advised to NOT change the UVICORN_WORKERS variable, i.e. leave it at it's default value, which is 1. A pod should only run one uvicorn worker at a time. Works with all startup methods: pip install startup (open-webui serve), bash script (start.sh), and Windows script (windows-start.bat) ### Screenshots or Videos N/A (Server-side enhancement with no visual changes) --- <sub>🔄 This issue represents a GitHub Pull Request. It cannot be merged through Gitea due to API limitations.</sub>
GiteaMirror added the pull-request label 2026-05-13 11:25:37 -05:00
Sign in to join this conversation.
No Branch/Tag Specified
Branches Tags
Labels
Clear labels
bug
confirmed
confirmed issue
core
documentation
enhancement
good first issue
help wanted
non-core
pull-request
Mirrored from GitHub Pull Request
 python
question
testing wanted
No Label pull-request
Milestone
No items
No Milestone
Projects
Clear projects
No project
Assignees
Clear assignees
GiteaMirror ninjasurge
No Assignees
1 Participants
Notifications
Due Date
No due date set.
Dependencies

No dependencies set.

Reference: github-starred/open-webui#77864
Delete Branch "%!s()"

Deleting a branch is permanent. Although the deleted branch may continue to exist for a short time before it actually gets removed, it CANNOT be undone in most cases. Continue?