The Fix
Upgrade to version 0.18.0 or later.
Based on closed Kludex/uvicorn issue #1526 · PR/commit linked
@@ -196,9 +196,26 @@ For more information, see the [settings documentation](settings.md).
### Running programmatically
-To run uvicorn directly from your application...
+There are several ways to run uvicorn directly from your application.
repro.py
Use the following options to configure Uvicorn, when running from the command line.
If you're running programmatically, using uvicorn.run(...), then use equivalent keyword arguments, eg. uvicorn.run("example:app", port=5000, reload=True, access_log=False). Please note that in this case, if you use reload=True or workers=NUM, you should put uvicorn.run into if __name__ == '__main__' clause in the main module.
You can also configure Uvicorn using environment variables with the prefix UVICORN_. For example, in case you want to run the app on port 5000, just set the environment variable UVICORN_PORT to 5000.
!!! note
CLI options and the arguments for uvicorn.run() take precedence over environment variables.
Also note that UVICORN_* prefixed settings cannot be used from within an environment configuration file. Using an environment configuration file with the --env-file flag is intended for configuring the ASGI application that uvicorn runs, rather than configuring uvicorn itself.
verify
Re-run the minimal reproduction on your broken version, then apply the fix and re-run.
fix.md
Option A — Upgrade to fixed release\nUpgrade to version 0.18.0 or later.\nWhen NOT to use: This fix is not applicable if the documentation does not require clarification.\n\n
Why This Fix Works in Production
- Trigger: I think we also need to change the introduction paragraphs in [Settings](https://www.uvicorn.org/settings/):
- Mechanism: Improved wording in the documentation for running Uvicorn programmatically
- Why the fix works: Improved wording in the documentation for running Uvicorn programmatically. (first fixed release: 0.18.0).
Why This Breaks in Prod
- Improved wording in the documentation for running Uvicorn programmatically
- Production symptom (often without a traceback): I think we also need to change the introduction paragraphs in [Settings](https://www.uvicorn.org/settings/):
Proof / Evidence
- GitHub issue: #1526
- Fix PR: https://github.com/encode/uvicorn/pull/1525
- First fixed release: 0.18.0
- Reproduced locally: No (not executed)
- Last verified: 2026-02-09
- Confidence: 0.95
- Did this fix it?: Yes (upstream fix exists)
- Own content ratio: 0.38
Discussion
High-signal excerpts from the issue thread (symptoms, repros, edge-cases).
“I think we should mention who takes precedence as well 🤔”
“A simple visual representation of what takes precedence would give developers a quick understanding. Since we have multiple levels of precedence, writing would become too…”
Failure Signature (Search String)
- I think we also need to change the introduction paragraphs in [Settings](https://www.uvicorn.org/settings/):
- You can also configure Uvicorn using environment variables with the prefix UVICORN_. For example, in case you want to run the app on port 5000, just set the environment variable
Copy-friendly signature
signature.txt
Failure Signature
-----------------
I think we also need to change the introduction paragraphs in [Settings](https://www.uvicorn.org/settings/):
You can also configure Uvicorn using environment variables with the prefix UVICORN_. For example, in case you want to run the app on port 5000, just set the environment variable UVICORN_PORT to 5000.
Error Message
Signature-only (no traceback captured)
error.txt
Error Message
-------------
I think we also need to change the introduction paragraphs in [Settings](https://www.uvicorn.org/settings/):
You can also configure Uvicorn using environment variables with the prefix UVICORN_. For example, in case you want to run the app on port 5000, just set the environment variable UVICORN_PORT to 5000.
Minimal Reproduction
repro.py
Use the following options to configure Uvicorn, when running from the command line.
If you're running programmatically, using uvicorn.run(...), then use equivalent keyword arguments, eg. uvicorn.run("example:app", port=5000, reload=True, access_log=False). Please note that in this case, if you use reload=True or workers=NUM, you should put uvicorn.run into if __name__ == '__main__' clause in the main module.
You can also configure Uvicorn using environment variables with the prefix UVICORN_. For example, in case you want to run the app on port 5000, just set the environment variable UVICORN_PORT to 5000.
!!! note
CLI options and the arguments for uvicorn.run() take precedence over environment variables.
Also note that UVICORN_* prefixed settings cannot be used from within an environment configuration file. Using an environment configuration file with the --env-file flag is intended for configuring the ASGI application that uvicorn runs, rather than configuring uvicorn itself.
Why It Broke
Improved wording in the documentation for running Uvicorn programmatically
Fix Options (Details)
Option A — Upgrade to fixed release Safe default (recommended)
Upgrade to version 0.18.0 or later.
When NOT to use: This fix is not applicable if the documentation does not require clarification.
Use when you can deploy the upstream fix. It is usually lower-risk than long-lived workarounds.
Fix reference: https://github.com/encode/uvicorn/pull/1525
First fixed release: 0.18.0
Last verified: 2026-02-09. Validate in your environment.
When NOT to Use This Fix
- This fix is not applicable if the documentation does not require clarification.
Verify Fix
verify
Re-run the minimal reproduction on your broken version, then apply the fix and re-run.
Did This Fix Work in Your Case?
Quick signal helps us prioritize which fixes to verify and improve.
Prevention
- Capture the exact failing error string in logs and tests so you can reproduce via a minimal script.
- Pin production dependencies and upgrade only with a reproducible test that hits the failing path.
Version Compatibility Table
| Version | Status |
|---|---|
| 0.18.0 | Fixed |
Related Issues
No related fixes found.
Sources
We don’t republish the full GitHub discussion text. Use the links above for context.