Say plainly that raising the worker count is the wrong way to scale

The setting is documented as a last resort rather than an option alongside running more containers. Extra workers require everything extra replicas require, a client-server vector database, Redis, PostgreSQL and a single instance running migrations, and give none of what replicas give back: they share one container, so they share its memory limit and its fate, cannot be restarted one at a time and cannot be spread across machines.

The warning sits on the variable's own entry, on the scaling guide where it was presented as a simpler alternative, and in the Redis guide beside the multi-worker example, since that is where someone reads the value and copies it.

Author: Classic298

docs/getting-started/advanced-topics/scaling.md

@@ -135,18 +135,20 @@ Use Kubernetes, Docker Swarm, or similar platforms to manage multiple replicas:
 - Set `ENABLE_DB_MIGRATIONS=false` on all replicas except one designated "primary" pod to prevent migration race conditions: see [Updates and Migrations](/troubleshooting/multi-replica#updates-and-migrations) for the safe procedure
 - Scale up/down by adjusting your replica count
 
-### Option B: Multiple Workers per Container
+### Option B: Multiple Workers per Container (Last Resort)
 
-For simpler setups (e.g., a single powerful server), increase `UVICORN_WORKERS`:
+On a single machine with no orchestrator at all, you can raise `UVICORN_WORKERS`:
 
 ```
 UVICORN_WORKERS=4
 ```
 
-This spawns multiple application processes inside a single container. You still need PostgreSQL and Redis when using this approach.
+:::warning This is the weakest way to scale
+
+Prefer more containers even on one machine: Docker Compose runs replicas on a single host perfectly well, and gets you restarts one at a time and a per-container memory limit.
+
+Extra workers cost you everything replicas cost, PostgreSQL, Redis and a client-server vector database are all still required, and return none of the benefit. They share one container, so they share its memory limit and die with it, and they cannot be spread across machines when one stops being enough.
 
-:::info
-Container orchestration is generally preferred because it provides automatic restarts, rolling updates, and more granular resource control. Multiple workers inside a single container is a simpler alternative when orchestration isn't available.
 :::
 
 ### Offload HTTP Compression to the Load Balancer

docs/reference/env-configuration.mdx

@@ -8246,11 +8246,13 @@ For most deployments, the default browser cookie-based session management is suf
 - Default: `1`
 - Description: Controls the number of worker processes that Uvicorn spawns to handle requests. Each worker runs its own instance of the application in a separate process.
 
-:::info
+:::warning Raising this is the worst way to scale Open WebUI
+
+Leave it at `1` and add containers instead: more replicas in Docker Compose, or more pods through Kubernetes and the Helm chart, behind a load balancer.
 
-When deploying in orchestrated environments like Kubernetes or using Helm charts, it's recommended to keep UVICORN_WORKERS set to 1. Container orchestration platforms already provide their own scaling mechanisms through pod replication, and using multiple workers inside containers can lead to resource allocation issues and complicate horizontal scaling strategies.
+Extra workers demand everything extra replicas demand, a client-server vector database, Redis, PostgreSQL and a single instance running migrations, and give you none of what replicas give you in return. They all sit in one container, so they share its memory limit and its fate: the container is a single point of failure, cannot be restarted one worker at a time, and cannot be spread across machines.
 
-If you use UVICORN_WORKERS, you also need to ensure that related environment variables for scalable multi-worker setups are set accordingly.
+If you do raise it, set the related variables for multi-worker deployments as well; the rest of this entry covers what breaks without them.
 
 :::
 

docs/tutorials/integrations/redis.md

@@ -516,6 +516,12 @@ UVICORN_WORKERS="4"  # Adjust based on your CPU cores
 REDIS_URL="redis://redis:6379/0"  # Required when UVICORN_WORKERS > 1
 ```
 
+:::warning Prefer more containers over more workers
+
+Raising `UVICORN_WORKERS` is the weakest way to scale Open WebUI. It requires the same external services as running several containers, Redis included, while leaving every worker inside one container that shares a single memory limit and fails as a unit. Run replicas with Docker Compose, Kubernetes or the Helm chart instead, keeping one worker each. See [Scaling Open WebUI](/getting-started/advanced-topics/scaling).
+
+:::
+
 :::danger
 
 **Critical: Redis Required for UVICORN_WORKERS > 1**