The Fix
Upgrade to version 0.19.0 or later.
Based on closed Kludex/starlette issue #1474 · PR/commit linked
Production note: Most teams hit this during upgrades or environment changes. Roll out with a canary and smoke critical endpoints (health, OpenAPI/docs) before 100%.
@@ -39,7 +39,7 @@ def get_long_description():
install_requires=[
"anyio>=3.4.0,<4",
- "typing_extensions; python_version < '3.10'",
+ "typing_extensions>=3.10.0; python_version < '3.10'",
"contextlib2 >= 21.6.0; python_version < '3.7'",
repro.py
$ python -c "from starlette.applications import Starlette"
Traceback (most recent call last):
File "<string>", line 1, in <module>
File ".../lib/python3.8/site-packages/starlette/applications.py", line 3, in <module>
from starlette.datastructures import State, URLPath
File ".../lib/python3.8/site-packages/starlette/datastructures.py", line 8, in <module>
from starlette.concurrency import run_in_threadpool
File ".../lib/python3.8/site-packages/starlette/concurrency.py", line 10, in <module>
from typing_extensions import ParamSpec
ImportError: cannot import name 'ParamSpec' from 'typing_extensions' (.../lib/python3.8/site-packages/typing_extensions.py)
verify
Re-run: python -c "from starlette.applications import Starlette"
fix.md
Option A — Upgrade to fixed release\nUpgrade to version 0.19.0 or later.\nWhen NOT to use: This fix is not applicable if the application does not use typing-extensions.\n\n
Why This Fix Works in Production
- Trigger: $ python -c "from starlette.applications import Starlette"
- Mechanism: Starlette does not specify a minimum version for typing-extensions, leading to import errors with older versions
- Why the fix works: Specifies the minimum required version of typing-extensions as 3.10.0 in the setup.py file, addressing the issue of import errors with older versions. (first fixed release: 0.19.0).
Production impact:
- If left unfixed, the same config can fail only in production (env differences), causing startup failures or partial feature outages.
Why This Breaks in Prod
- Shows up under Python 3.8 in real deployments (not just unit tests).
- Starlette does not specify a minimum version for typing-extensions, leading to import errors with older versions
- Surfaces as: $ python -c "from starlette.applications import Starlette"
Proof / Evidence
- GitHub issue: #1474
- Fix PR: https://github.com/kludex/starlette/pull/1475
- First fixed release: 0.19.0
- Reproduced locally: No (not executed)
- Last verified: 2026-02-09
- Confidence: 0.85
- Did this fix it?: Yes (upstream fix exists)
- Own content ratio: 0.43
Discussion
High-signal excerpts from the issue thread (symptoms, repros, edge-cases).
“I can do a PR adding the minimum version (removing the ParamSpec requirement also seems fine, but is more than I'd want to get into).”
“@drasmuss mentions correctly that it needs >= 3.10 See https://github.com/python/typing/pull/774/files and..”
“Yup that's valid”
“I wonder how we should decide the minimum version. The typing_extensions project doesn't have changelog prior to version 0.4.0.”
Failure Signature (Search String)
- $ python -c "from starlette.applications import Starlette"
Error Message
Stack trace
error.txt
Error Message
-------------
$ python -c "from starlette.applications import Starlette"
Traceback (most recent call last):
File "<string>", line 1, in <module>
File ".../lib/python3.8/site-packages/starlette/applications.py", line 3, in <module>
from starlette.datastructures import State, URLPath
File ".../lib/python3.8/site-packages/starlette/datastructures.py", line 8, in <module>
from starlette.concurrency import run_in_threadpool
File ".../lib/python3.8/site-packages/starlette/concurrency.py", line 10, in <module>
from typing_extensions import ParamSpec
ImportError: cannot import name 'ParamSpec' from 'typing_extensions' (.../lib/python3.8/site-packages/typing_extensions.py)
Minimal Reproduction
repro.py
$ python -c "from starlette.applications import Starlette"
Traceback (most recent call last):
File "<string>", line 1, in <module>
File ".../lib/python3.8/site-packages/starlette/applications.py", line 3, in <module>
from starlette.datastructures import State, URLPath
File ".../lib/python3.8/site-packages/starlette/datastructures.py", line 8, in <module>
from starlette.concurrency import run_in_threadpool
File ".../lib/python3.8/site-packages/starlette/concurrency.py", line 10, in <module>
from typing_extensions import ParamSpec
ImportError: cannot import name 'ParamSpec' from 'typing_extensions' (.../lib/python3.8/site-packages/typing_extensions.py)
Environment
- Python: 3.8
What Broke
Importing Starlette fails due to an incompatible version of typing-extensions, causing application startup errors.
Why It Broke
Starlette does not specify a minimum version for typing-extensions, leading to import errors with older versions
Fix Options (Details)
Option A — Upgrade to fixed release Safe default (recommended)
Upgrade to version 0.19.0 or later.
When NOT to use: This fix is not applicable if the application does not use typing-extensions.
Use when you can deploy the upstream fix. It is usually lower-risk than long-lived workarounds.
Fix reference: https://github.com/kludex/starlette/pull/1475
First fixed release: 0.19.0
Last verified: 2026-02-09. Validate in your environment.
When NOT to Use This Fix
- This fix is not applicable if the application does not use typing-extensions.
Verify Fix
verify
Re-run: python -c "from starlette.applications import Starlette"
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.19.0 | Fixed |
Related Issues
No related fixes found.
Sources
We don’t republish the full GitHub discussion text. Use the links above for context.