The Fix
Upgrade to version 0.18.0 or later.
Based on closed Kludex/starlette issue #1265 · 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%.
@@ -6,7 +6,7 @@ Starlette also includes a `StaticFiles` class for serving files in a given direc
* `directory` - A string or [os.Pathlike][pathlike] denoting a directory path.
-* `packages` - A list of strings of python packages.
+* `packages` - A list of strings or list of tuples of strings of python packages.
* `html` - Run in HTML mode. Automatically loads `index.html` for directories if such file exist.
Option A — Upgrade to fixed release\nUpgrade to version 0.18.0 or later.\nWhen NOT to use: Do not use this fix if you require the original hardcoded behavior for compatibility.\n\n
Why This Fix Works in Production
- Trigger: I want to be able to serve static files from arbitrary locations within a python package but I can't because currently it looks in a `statics` folder which is…
- Mechanism: The StaticFiles class hardcoded the directory to 'statics', limiting flexibility
- Why the fix works: Adds the ability to specify a directory when using the `packages` argument in StaticFiles, addressing issue #1265. (first fixed release: 0.18.0).
- 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
- The StaticFiles class hardcoded the directory to 'statics', limiting flexibility
- Production symptom (often without a traceback): I want to be able to serve static files from arbitrary locations within a python package but I can't because currently it looks in a `statics` folder which is hardcoded.
Proof / Evidence
- GitHub issue: #1265
- Fix PR: https://github.com/kludex/starlette/pull/1350
- First fixed release: 0.18.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.59
Discussion
High-signal excerpts from the issue thread (symptoms, repros, edge-cases).
“Hi folks, we're considering #1350 and the following API to address this use case… That is, we'll be able to specify a root directory to…”
“That's already supported. Check the docs here: https://www.starlette.io/staticfiles/”
“> That's already supported. > > Check the docs here: https://www.starlette.io/staticfiles/ I don’t think it is. I want to use the package argument but specify…”
“> The line https://github.com/encode/starlette/blob/master/starlette/staticfiles.py#L56 prevents me to use a symbolic link for my static files... @stephane In my case, i added check_dir=FALSE in StaticFiles constructor…”
Failure Signature (Search String)
- I want to be able to serve static files from arbitrary locations within a python package but I can't because currently it looks in a `statics` folder which is hardcoded.
- I've considered changing the location of my packaged files to `statics` but this will have knock on effects across other systems, and `statics` itself is non-standard as far as I
Copy-friendly signature
Failure Signature
-----------------
I want to be able to serve static files from arbitrary locations within a python package but I can't because currently it looks in a `statics` folder which is hardcoded.
I've considered changing the location of my packaged files to `statics` but this will have knock on effects across other systems, and `statics` itself is non-standard as far as I can tell.
Error Message
Signature-only (no traceback captured)
Error Message
-------------
I want to be able to serve static files from arbitrary locations within a python package but I can't because currently it looks in a `statics` folder which is hardcoded.
I've considered changing the location of my packaged files to `statics` but this will have knock on effects across other systems, and `statics` itself is non-standard as far as I can tell.
What Broke
Users cannot serve static files from custom directories, causing deployment issues.
Why It Broke
The StaticFiles class hardcoded the directory to 'statics', limiting flexibility
Fix Options (Details)
Option A — Upgrade to fixed release Safe default (recommended)
Upgrade to version 0.18.0 or later.
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/1350
First fixed release: 0.18.0
Last verified: 2026-02-09. Validate in your environment.
When NOT to Use This Fix
- Do not use this fix if you require the original hardcoded behavior for compatibility.
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.