The Fix
Switches the dependency from brotlipy to brotlicffi for CPython, improving performance.
Based on closed urllib3/urllib3 issue #2040 · 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%.
@@ -51,10 +51,6 @@ jobs:
experimental: false
nox-session: test-pypy
- - python-version: 3.7
- os: ubuntu-latest
- experimental: false
Option A — Apply the official fix\nSwitches the dependency from brotlipy to brotlicffi for CPython, improving performance.\nWhen NOT to use: This fix is not applicable if maintaining compatibility with PyPy is required.\n\n
Why This Fix Works in Production
- Trigger: [v2] Change "brotli" extra to depend on brotli instead of brotlipy (/brotlicffi) for CPython
- Mechanism: The library was using brotlipy for CPython, which is less performant than Google's brotli bindings
- 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 library was using brotlipy for CPython, which is less performant than Google's brotli bindings
- Production symptom (often without a traceback): [v2] Change "brotli" extra to depend on brotli instead of brotlipy (/brotlicffi) for CPython
Proof / Evidence
- GitHub issue: #2040
- Fix PR: https://github.com/urllib3/urllib3/pull/2099
- Reproduced locally: No (not executed)
- Last verified: 2026-02-11
- Confidence: 0.80
- Did this fix it?: Yes (upstream fix exists)
- Own content ratio: 0.69
Discussion
High-signal excerpts from the issue thread (symptoms, repros, edge-cases).
“This work can proceed now that brotlicffi is released: https://pypi.org/project/brotlicffi”
“@sethmlarson Thanks for renaming brotlipy to brotlicffi! Should we wait for a release before tackling this?”
“Closed in https://github.com/urllib3/urllib3/pull/2099”
Failure Signature (Search String)
- [v2] Change "brotli" extra to depend on brotli instead of brotlipy (/brotlicffi) for CPython
- There are also plans to rename brotlipy to `brotlicffi` in order to resolve the name conflict with Google's brotli bindings: https://github.com/python-hyper/brotlipy/issues/145
Copy-friendly signature
Failure Signature
-----------------
[v2] Change "brotli" extra to depend on brotli instead of brotlipy (/brotlicffi) for CPython
There are also plans to rename brotlipy to `brotlicffi` in order to resolve the name conflict with Google's brotli bindings: https://github.com/python-hyper/brotlipy/issues/145
Error Message
Signature-only (no traceback captured)
Error Message
-------------
[v2] Change "brotli" extra to depend on brotli instead of brotlipy (/brotlicffi) for CPython
There are also plans to rename brotlipy to `brotlicffi` in order to resolve the name conflict with Google's brotli bindings: https://github.com/python-hyper/brotlipy/issues/145
What Broke
Performance degradation in Brotli compression due to suboptimal library choice.
Why It Broke
The library was using brotlipy for CPython, which is less performant than Google's brotli bindings
Fix Options (Details)
Option A — Apply the official fix
Switches the dependency from brotlipy to brotlicffi for CPython, improving performance.
Fix reference: https://github.com/urllib3/urllib3/pull/2099
Last verified: 2026-02-11. Validate in your environment.
When NOT to Use This Fix
- This fix is not applicable if maintaining compatibility with PyPy is required.
Did This Fix Work in Your Case?
Quick signal helps us prioritize which fixes to verify and improve.
Prevention
- Add a CI check that diffs key outputs after upgrades (OpenAPI schema snapshots, JSON payload shapes, CLI output).
- Upgrade behind a canary and run integration tests against the canary before 100% rollout.
Related Issues
No related fixes found.
Sources
We don’t republish the full GitHub discussion text. Use the links above for context.