urllib3 `python_requires` prevents install of recent

The Fix

pip install urllib3==1.25

Based on closed urllib3/urllib3 issue #2761 · 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%.

Jump to Verify Open PR/Commit

@@ -52,6 +52,7 @@
                 ],
       requires=[],
+      python_requires=">=2.6, !=3.0.*, !=3.1.*, !=3.2.*, !=3.3.*, <4",
       tests_require=[
           # These are a less-specific subset of dev-requirements.txt, for the

repro.py

poetry add urllib3@latest
Using version ^1.26.12 for urllib3

Updating dependencies
Resolving dependencies... (0.0s)

The current project's Python requirement (>=3.9) is not compatible with some of the required packages Python requirement:
  - urllib3 requires Python >=2.7, !=3.0.*, !=3.1.*, !=3.2.*, !=3.3.*, !=3.4.*, !=3.5.*, <4, so it will not be satisfied for Python >=4

Because urllib3 (1.26.12) requires Python >=2.7, !=3.0.*, !=3.1.*, !=3.2.*, !=3.3.*, !=3.4.*, !=3.5.*, <4
 and no versions of urllib3 match >1.26.12,<2.0.0, urllib3 is forbidden.
So, because aoc-cj depends on urllib3 (^1.26.12), version solving failed.

  • Check your dependencies Python requirement: The Python requirement can be specified via the `python` or `markers` properties
    
    For urllib3, a possible solution would be to set the `python` property to ">=3.9,<4"

    https://python-poetry.org/docs/dependency-specification/#python-restricted-dependencies,
    https://python-poetry.org/docs/dependency-specification/#using-environment-markers

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\npip install urllib3==1.25\nWhen NOT to use: This fix should not be applied if the library needs to support Python 4 or later.\n\n

Why This Fix Works in Production

Trigger: So, because aoc-cj depends on urllib3 (^1.26.12), version solving failed.
Mechanism: Added a python_requires argument to setuptools to prevent installation on incompatible Python versions.
Why the fix works: Added a python_requires argument to setuptools to prevent installation on incompatible Python versions. (first fixed release: 1.25).

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.9.15 in real deployments (not just unit tests).
Production symptom (often without a traceback): So, because aoc-cj depends on urllib3 (^1.26.12), version solving failed.

Proof / Evidence

GitHub issue: #2761
Fix PR: https://github.com/urllib3/urllib3/pull/1309
First fixed release: 1.25
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.41

Discussion

High-signal excerpts from the issue thread (symptoms, repros, edge-cases).

Jump to Sources Open on GitHub

“### Subject re: https://github.com/urllib3/urllib3/pull/1309#issuecomment-356650894 I no longer see the suggestion of including <4 in the link referenced earlier in that PR (content relocated to https://packaging.python.org/en/latest/guides”

Issue thread · issue description · source

Failure Signature (Search String)

So, because aoc-cj depends on urllib3 (^1.26.12), version solving failed.
As a result of this change, I've been quietly stuck on `urllib3 v1.22` without even realizing it.

Copy-friendly signature

signature.txt

Failure Signature
-----------------
So, because aoc-cj depends on urllib3 (^1.26.12), version solving failed.
As a result of this change, I've been quietly stuck on `urllib3 v1.22` without even realizing it.

Error Message

Signature-only (no traceback captured)

error.txt

Error Message
-------------
So, because aoc-cj depends on urllib3 (^1.26.12), version solving failed.
As a result of this change, I've been quietly stuck on `urllib3 v1.22` without even realizing it.

Minimal Reproduction

repro.py

poetry add urllib3@latest
Using version ^1.26.12 for urllib3

Updating dependencies
Resolving dependencies... (0.0s)

The current project's Python requirement (>=3.9) is not compatible with some of the required packages Python requirement:
  - urllib3 requires Python >=2.7, !=3.0.*, !=3.1.*, !=3.2.*, !=3.3.*, !=3.4.*, !=3.5.*, <4, so it will not be satisfied for Python >=4

Because urllib3 (1.26.12) requires Python >=2.7, !=3.0.*, !=3.1.*, !=3.2.*, !=3.3.*, !=3.4.*, !=3.5.*, <4
 and no versions of urllib3 match >1.26.12,<2.0.0, urllib3 is forbidden.
So, because aoc-cj depends on urllib3 (^1.26.12), version solving failed.

  • Check your dependencies Python requirement: The Python requirement can be specified via the `python` or `markers` properties
    
    For urllib3, a possible solution would be to set the `python` property to ">=3.9,<4"

    https://python-poetry.org/docs/dependency-specification/#python-restricted-dependencies,
    https://python-poetry.org/docs/dependency-specification/#using-environment-markers

Environment

Python: 3.9.15
urllib3: 1.22

What Broke

Users are stuck on older urllib3 versions due to dependency resolution failures in Poetry.

Fix Options (Details)

Option A — Upgrade to fixed release Safe default (recommended)

pip install urllib3==1.25

When NOT to use: This fix should not be applied if the library needs to support Python 4 or later.

Use when you can deploy the upstream fix. It is usually lower-risk than long-lived workarounds.

Fix reference: https://github.com/urllib3/urllib3/pull/1309

First fixed release: 1.25

Last verified: 2026-02-09. Validate in your environment.

When NOT to Use This Fix

This fix should not be applied if the library needs to support Python 4 or later.

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

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.

Version Compatibility Table

Version	Status
1.25	Fixed

Related Issues

No related fixes found.

Cluster: urllib3:configuration-error urllib3 hub urllib3 best practices All hubs All clusters

Related clusters: Data consistency SSL handshake Other

Sources

We don’t republish the full GitHub discussion text. Use the links above for context.

urllib3 `python_requires` prevents install of recent urllib3 when using Poetry (Fix)