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.
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>
Blocking a user prevents them from interacting with repositories, such as opening or commenting on pull requests or issues. Learn more about blocking a user.
📋 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)
f822d89Update env.py4c9a791Update env.py2c1d0e3Update start.sh65b5c6cUpdate start_windows.batf17befcUpdate __init__.py📊 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:
devbranch.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
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.