[GH-ISSUE #23473] bug: open-webui serve deadlocks on Windows due to uvicorn workers=1 spawn #106990

New Issue

GiteaMirror · 2026-05-18T05:30:49-05:00

GiteaMirror commented

2026-05-18 05:30:49 -05:00

Originally created by @yamadanoitou on GitHub (Apr 7, 2026).
Original GitHub issue: https://github.com/open-webui/open-webui/issues/23473

Check Existing Issues

I have searched the existing issues and discussions.
I am using the latest version of Open WebUI.

Installation Method

Pip Install

Open WebUI Version

0.8.12

Ollama Version (if applicable)

No response

Operating System

Windows 11

Browser (if applicable)

No response

Confirmation

I have read and followed all instructions in README.md.
I am using the latest version of both Open WebUI and Ollama.
I have included the browser console logs.
I have included the Docker container logs.
I have listed steps to reproduce the bug in detail.

Description

open-webui serve hangs indefinitely on Windows (pip install, non-Docker). The last log line is:

open_webui.utils.plugin:install_frontmatter_requirements - No requirements found in frontmatter.

After that, the process is alive but all threads are in Wait state. No error, no traceback — it just silently deadlocks. This affects every Windows pip-install user.

Root Cause

In open_webui/__init__.py, the serve() function calls:

uvicorn.run(
    'open_webui.main:app',   # string import target
    workers=UVICORN_WORKERS,  # defaults to 1
    ...
)

On Windows, passing workers= (even workers=1) causes uvicorn to use its Multiprocess manager, which spawns a child process via Python's multiprocessing.spawn. The child re-imports open_webui.main, and the heavy module-level initialization (SQLAlchemy, sentence-transformers, alembic migrations, etc.) deadlocks in the spawned subprocess.

On Linux/macOS this is not an issue because fork is available.

Proof

# This HANGS on Windows:
uvicorn.run('open_webui.main:app', host='127.0.0.1', port=8080,
            workers=1)

# This WORKS on Windows (starts in ~20 seconds):
import open_webui.main
uvicorn.run(open_webui.main.app, host='127.0.0.1', port=8080)

Suggested Fix

In __init__.py, either:

Option A — Pass the app object directly instead of a string (already imported on line 68):

import open_webui.main  # noqa: F401  (line 68, already exists)

uvicorn.run(
    open_webui.main.app,  # object, not string
    host=host,
    port=port,
    forwarded_allow_ips='*',
)

Option B — Omit workers when it equals 1:

kwargs = dict(host=host, port=port, forwarded_allow_ips='*')
if UVICORN_WORKERS > 1:
    kwargs['workers'] = UVICORN_WORKERS
uvicorn.run('open_webui.main:app', **kwargs)

Environment

OS: Windows 11 (10.0.26200)
Python: 3.11.9
Open WebUI: 0.8.12
uvicorn: 0.41.0

#13848 — same symptom (Windows, pip install, hangs on startup), no resolution

Additional Information

Current workaround: bypass open-webui serve entirely and launch via a Python script that passes the app object directly to uvicorn.run().

Originally created by @yamadanoitou on GitHub (Apr 7, 2026). Original GitHub issue: https://github.com/open-webui/open-webui/issues/23473 ### Check Existing Issues - [x] I have searched the existing issues and discussions. - [x] I am using the latest version of Open WebUI. ### Installation Method Pip Install ### Open WebUI Version 0.8.12 ### Ollama Version (if applicable) _No response_ ### Operating System Windows 11 ### Browser (if applicable) _No response_ ### Confirmation - [x] I have read and followed all instructions in `README.md`. - [x] I am using the latest version of **both** Open WebUI and Ollama. - [x] I have included the browser console logs. - [x] I have included the Docker container logs. - [x] I have listed steps to reproduce the bug in detail. ### Description `open-webui serve` hangs indefinitely on Windows (pip install, non-Docker). The last log line is: ``` open_webui.utils.plugin:install_frontmatter_requirements - No requirements found in frontmatter. ``` After that, the process is alive but all threads are in Wait state. No error, no traceback — it just silently deadlocks. This affects **every** Windows pip-install user. ### Root Cause In `open_webui/__init__.py`, the `serve()` function calls: ```python uvicorn.run( 'open_webui.main:app', # string import target workers=UVICORN_WORKERS, # defaults to 1 ... ) ``` On Windows, passing `workers=` (even `workers=1`) causes uvicorn to use its `Multiprocess` manager, which spawns a child process via Python's `multiprocessing.spawn`. The child re-imports `open_webui.main`, and the heavy module-level initialization (SQLAlchemy, sentence-transformers, alembic migrations, etc.) deadlocks in the spawned subprocess. On Linux/macOS this is not an issue because `fork` is available. ### Proof ```python # This HANGS on Windows: uvicorn.run('open_webui.main:app', host='127.0.0.1', port=8080, workers=1) # This WORKS on Windows (starts in ~20 seconds): import open_webui.main uvicorn.run(open_webui.main.app, host='127.0.0.1', port=8080) ``` ### Suggested Fix In `__init__.py`, either: **Option A** — Pass the app object directly instead of a string (already imported on line 68): ```python import open_webui.main # noqa: F401 (line 68, already exists) uvicorn.run( open_webui.main.app, # object, not string host=host, port=port, forwarded_allow_ips='*', ) ``` **Option B** — Omit `workers` when it equals 1: ```python kwargs = dict(host=host, port=port, forwarded_allow_ips='*') if UVICORN_WORKERS > 1: kwargs['workers'] = UVICORN_WORKERS uvicorn.run('open_webui.main:app', **kwargs) ``` ### Environment - OS: Windows 11 (10.0.26200) - Python: 3.11.9 - Open WebUI: 0.8.12 - uvicorn: 0.41.0 ### Related #13848 — same symptom (Windows, pip install, hangs on startup), no resolution ### Additional Information Current workaround: bypass `open-webui serve` entirely and launch via a Python script that passes the app object directly to `uvicorn.run()`.

GiteaMirror closed this issue

2026-05-18 05:30:50 -05:00

GiteaMirror commented

2026-05-18 05:30:51 -05:00

@Classic298 commented on GitHub (Apr 7, 2026):

cannot reproduce on windows. works just fine with 1 uvicorn worker

did you test any of your suggested fixes?
did you confirm this is ACTUALLY the root cause?

I highly doubt it because working fine here

@Classic298 commented on GitHub (Apr 7, 2026): cannot reproduce on windows. works just fine with 1 uvicorn worker did you test any of your suggested fixes? did you confirm this is ACTUALLY the root cause? I highly doubt it because working fine here

GiteaMirror commented

2026-05-18 05:30:52 -05:00

@yamadanoitou commented on GitHub (Apr 7, 2026):

Yes, both fixes were tested and confirmed working on this machine before filing.

Reproduction (hangs)

> open-webui serve
INFO:     Started server process [28088]
INFO:     Waiting for application startup.
...
open_webui.utils.plugin:install_frontmatter_requirements:404 - No requirements found in frontmatter.
← hangs here indefinitely, all threads in Wait state

Fix verification (works)

# scripts/run_openwebui.py — passes app object directly, no workers param
import open_webui.main
import uvicorn

uvicorn.run(
    open_webui.main.app,  # object, not string
    host="127.0.0.1",
    port=3000,
    forwarded_allow_ips="*",
)

This starts successfully in ~20 seconds and serves requests. Switching back to open-webui serve reproduces the hang every time.

Environment details

Windows 11 Home 10.0.26200
Python 3.11.9
Open WebUI 0.8.12 (pip install via uv pip install open-webui)
uvicorn 0.41.0

Could you share your environment details? Specifically:

Are you using pip install or Docker on Windows?
Python version?
uvicorn version?
Windows version?

This may be environment-specific — possibly related to how multiprocessing.spawn interacts with the heavy module-level imports in open_webui.main on certain configurations.

Related: #13848 reports the exact same symptom (Windows, pip install, hangs on startup after install_frontmatter_requirements).

@yamadanoitou commented on GitHub (Apr 7, 2026): Yes, both fixes were tested and confirmed working on this machine before filing. ### Reproduction (hangs) ``` > open-webui serve INFO: Started server process [28088] INFO: Waiting for application startup. ... open_webui.utils.plugin:install_frontmatter_requirements:404 - No requirements found in frontmatter. ← hangs here indefinitely, all threads in Wait state ``` ### Fix verification (works) ```python # scripts/run_openwebui.py — passes app object directly, no workers param import open_webui.main import uvicorn uvicorn.run( open_webui.main.app, # object, not string host="127.0.0.1", port=3000, forwarded_allow_ips="*", ) ``` This starts successfully in ~20 seconds and serves requests. Switching back to `open-webui serve` reproduces the hang every time. ### Environment details - Windows 11 Home 10.0.26200 - Python 3.11.9 - Open WebUI 0.8.12 (pip install via `uv pip install open-webui`) - uvicorn 0.41.0 Could you share your environment details? Specifically: - Are you using pip install or Docker on Windows? - Python version? - uvicorn version? - Windows version? This may be environment-specific — possibly related to how `multiprocessing.spawn` interacts with the heavy module-level imports in `open_webui.main` on certain configurations. Related: #13848 reports the exact same symptom (Windows, pip install, hangs on startup after `install_frontmatter_requirements`).

GiteaMirror commented

2026-05-18 05:30:52 -05:00

@Classic298 commented on GitHub (Apr 7, 2026):

Pip install
Python 3.12
Uvicorn latest i just updated yesterday
Windows 11

I can't reproduce

@Classic298 commented on GitHub (Apr 7, 2026): Pip install Python 3.12 Uvicorn latest i just updated yesterday Windows 11 I can't reproduce

GiteaMirror commented

2026-05-18 05:30:53 -05:00

@yamadanoitou commented on GitHub (Apr 7, 2026):

On my end, I'm using Python 3.11.9, while you're on 3.12. I double-checked the uvicorn source code and realized that if workers=1, it doesn't use multiprocessing, so my initial analysis might have been off. My bad.

However, I can reproduce the bug here 100% of the time. Running open-webui serve causes it to hang, but passing the app object directly to uvicorn gets it running in about 20 seconds. It’s consistent every time.

The version gap between Python 3.11 and 3.12 might be the culprit. I'll try testing it on 3.12 on my side as well.

@yamadanoitou commented on GitHub (Apr 7, 2026): On my end, I'm using Python 3.11.9, while you're on 3.12. I double-checked the uvicorn source code and realized that if workers=1, it doesn't use multiprocessing, so my initial analysis might have been off. My bad. However, I can reproduce the bug here 100% of the time. Running open-webui serve causes it to hang, but passing the app object directly to uvicorn gets it running in about 20 seconds. It’s consistent every time. The version gap between Python 3.11 and 3.12 might be the culprit. I'll try testing it on 3.12 on my side as well.

GiteaMirror commented

2026-05-18 05:30:54 -05:00

@yamadanoitou commented on GitHub (Apr 7, 2026):

I ran the tests, and you were right—my apologies.
I tried open-webui serve on the same machine with the same settings using Python 3.12, and it launched without any issues. However, it consistently hangs on Python 3.11.9.

Here are the results:

Python 3.11.9 + open-webui serve: Hangs (100% reproducible)

Python 3.12.10 + open-webui serve: Launches normally

Python 3.11.9 + uvicorn.run(app_object): Launches normally (Workaround)

My initial analysis regarding the uvicorn workers parameter was incorrect. It seems like something related to the asyncio/event loop in Python 3.11 is causing issues on Windows.

Since the pyproject.toml specifies requires-python = ">=3.11", other 3.11 users might be affected by this. It would be great if we could either bump the minimum version to 3.12 or find a proper workaround for this specific combination.

@yamadanoitou commented on GitHub (Apr 7, 2026): I ran the tests, and you were right—my apologies. I tried open-webui serve on the same machine with the same settings using Python 3.12, and it launched without any issues. However, it consistently hangs on Python 3.11.9. Here are the results: Python 3.11.9 + open-webui serve: Hangs (100% reproducible) Python 3.12.10 + open-webui serve: Launches normally Python 3.11.9 + uvicorn.run(app_object): Launches normally (Workaround) My initial analysis regarding the uvicorn workers parameter was incorrect. It seems like something related to the asyncio/event loop in Python 3.11 is causing issues on Windows. Since the pyproject.toml specifies requires-python = ">=3.11", other 3.11 users might be affected by this. It would be great if we could either bump the minimum version to 3.12 or find a proper workaround for this specific combination.

GiteaMirror commented

2026-05-18 05:30:55 -05:00

@Classic298 commented on GitHub (Apr 7, 2026):

It would be more interesting why it works on .12 and not on .11 - if it's not the worker numbers then what is it

@Classic298 commented on GitHub (Apr 7, 2026): It would be more interesting why it works on .12 and not on .11 - if it's not the worker numbers then what is it

Sign in to join this conversation.

Branches Tags

1 Participants

Notifications

Due Date

No due date set.

Dependencies

No dependencies set.

Reference: github-starred/open-webui#106990