Jump to solution
Verify

urllib3 requests/dev version of urllib3 don't play nice together in tox (Fix)

Fixed
Spec
Package
urllib3
Fixed In
1.25
Python
2.7
Verdict
Status
Fixed
Safe for prod
No
Risk
Medium
Last verified
2026-02-09
Own content ratio
0.47
#1182 ai llm tls Updated: 2026-02-13
Issue #1182

The Fix

pip install urllib3==1.25

Based on closed urllib3/urllib3 issue #1182 · 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
@@ -2,3 +2,4 @@ sphinx alabaster +requests>=2.0,<2.16
repro.py
$ tox -e docs GLOB sdist-make: /Users/alexwlchan/repos/urllib3/setup.py docs create: /Users/alexwlchan/repos/urllib3/.tox/docs docs installdeps: -r/Users/alexwlchan/repos/urllib3/docs/requirements.txt docs inst: /Users/alexwlchan/repos/urllib3/.tox/dist/urllib3-dev.zip docs installed: alabaster==0.7.10,appdirs==1.4.3,asn1crypto==0.22.0,Babel==2.4.0,backports.ssl-match-hostname==3.5.0.1,certifi==2017.4.17,cffi==1.10.0,chardet==3.0.3,coverage==3.7.1,cryptography==1.8.2,docutils==0.13.1,enum34==1.1.6,funcsigs==1.0.2,idna==2.5,imagesize==0.7.1,ipaddress==1.0.18,Jinja2==2.9.6,MarkupSafe==1.0,mock==1.3.0,ndg-httpsclient==0.4.2,nose==1.3.7,nose-exclude==0.4.1,packaging==16.8,pbr==3.0.1,pkginfo==1.4.1,pluggy==0.3.1,psutil==4.3.1,py==1.4.33,pycparser==2.17,Pygments==2.2.0,pyOpenSSL==17.0.0,pyparsing==2.2.0,PySocks==1.5.6,pytz==2017.2,requests==2.16.5,six==1.10.0,snowballstemmer==1.2.1,Sphinx==1.6.2,sphinxcontrib-websupport==1.0.1,tornado==4.2.1,tox==2.1.1,twine==1.5.0,typing==3.6.1,urllib3===dev,virtualenv==15.1.0 docs runtests: PYTHONHASHSEED='3695751977' docs runtests: commands[0] | rm -rf /Users/alexwlchan/repos/urllib3/docs/_build docs runtests: commands[1] | make -C /Users/alexwlchan/repos/urllib3/docs html sphinx-build -b html -d _build/doctrees '-W' . _build/html Running Sphinx v1.6.2 making output directory... Exception occurred: File "/Users/alexwlchan/repos/urllib3/.tox/docs/lib/python2.7/site-packages/requests/__init__.py", line 53, in <module> major, minor, patch = urllib3_version ValueError: need more than 1 value to unpack The full traceback has been saved in /var/folders/jy/351n9lnj5l3f07rtf2xybxx00000gn/T/sphinx-err-dn6eJg.log, if you want to report the issue to the developers. Please also report this if it was a user error, so that a better error message can be provided next time. A bug report can be filed in the tracker at <https://github.com/sphinx-doc/sphinx/issues>. Thanks! make: *** [html] Error 1 ERROR: InvocationError: '/usr/bin/make -C /Users/alexwlchan/repos/urllib3/docs html' ________________________________________________________________________________ summary _________________________________________________________________________________ ERROR: docs: commands failed
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 is not suitable if you require the latest development version of requests.\n\nOption C — Workaround\nin requests itself?\nWhen NOT to use: This fix is not suitable if you require the latest development version of requests.\n\n

Why This Fix Works in Production

  • Trigger: Exception occurred:
  • Mechanism: The unbundling of dependencies from requests caused urllib3 to present an incompatible version number
  • Why the fix works: Pins out all unvendored Requests releases for the documentation build, resolving the issue with version conflicts. (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 2.7 in real deployments (not just unit tests).
  • The unbundling of dependencies from requests caused urllib3 to present an incompatible version number
  • Production symptom (often without a traceback): Exception occurred:

Proof / Evidence

  • GitHub issue: #1182
  • Fix PR: https://github.com/urllib3/urllib3/pull/1185
  • First fixed release: 1.25
  • 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.47

Discussion

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

Jump to Sources Open on GitHub
“As an example of what the above means, it becomes impossible for us to build docs for urllib3 v2.0 until after it's released, because it…”
@Lukasa · 2017-05-28 · confirmation · source
“This seems like a problem with our tox installation, possibly the results of a dependency issue? Seems like it must be pretty recent given that…”
@Lukasa · 2017-05-28 · source
“Oh god. Why are we importing Requests in the docs build?”
@Lukasa · 2017-05-28 · source
“> Why are we importing Requests in the docs build? You’re not, Sphinx is.”
@alexwlchan · 2017-05-28 · source

Failure Signature (Search String)

  • Exception occurred:
  • ValueError: need more than 1 value to unpack
Copy-friendly signature
signature.txt
Failure Signature ----------------- Exception occurred: ValueError: need more than 1 value to unpack

Error Message

Signature-only (no traceback captured)
error.txt
Error Message ------------- Exception occurred: ValueError: need more than 1 value to unpack

Minimal Reproduction

repro.py
$ tox -e docs GLOB sdist-make: /Users/alexwlchan/repos/urllib3/setup.py docs create: /Users/alexwlchan/repos/urllib3/.tox/docs docs installdeps: -r/Users/alexwlchan/repos/urllib3/docs/requirements.txt docs inst: /Users/alexwlchan/repos/urllib3/.tox/dist/urllib3-dev.zip docs installed: alabaster==0.7.10,appdirs==1.4.3,asn1crypto==0.22.0,Babel==2.4.0,backports.ssl-match-hostname==3.5.0.1,certifi==2017.4.17,cffi==1.10.0,chardet==3.0.3,coverage==3.7.1,cryptography==1.8.2,docutils==0.13.1,enum34==1.1.6,funcsigs==1.0.2,idna==2.5,imagesize==0.7.1,ipaddress==1.0.18,Jinja2==2.9.6,MarkupSafe==1.0,mock==1.3.0,ndg-httpsclient==0.4.2,nose==1.3.7,nose-exclude==0.4.1,packaging==16.8,pbr==3.0.1,pkginfo==1.4.1,pluggy==0.3.1,psutil==4.3.1,py==1.4.33,pycparser==2.17,Pygments==2.2.0,pyOpenSSL==17.0.0,pyparsing==2.2.0,PySocks==1.5.6,pytz==2017.2,requests==2.16.5,six==1.10.0,snowballstemmer==1.2.1,Sphinx==1.6.2,sphinxcontrib-websupport==1.0.1,tornado==4.2.1,tox==2.1.1,twine==1.5.0,typing==3.6.1,urllib3===dev,virtualenv==15.1.0 docs runtests: PYTHONHASHSEED='3695751977' docs runtests: commands[0] | rm -rf /Users/alexwlchan/repos/urllib3/docs/_build docs runtests: commands[1] | make -C /Users/alexwlchan/repos/urllib3/docs html sphinx-build -b html -d _build/doctrees '-W' . _build/html Running Sphinx v1.6.2 making output directory... Exception occurred: File "/Users/alexwlchan/repos/urllib3/.tox/docs/lib/python2.7/site-packages/requests/__init__.py", line 53, in <module> major, minor, patch = urllib3_version ValueError: need more than 1 value to unpack The full traceback has been saved in /var/folders/jy/351n9lnj5l3f07rtf2xybxx00000gn/T/sphinx-err-dn6eJg.log, if you want to report the issue to the developers. Please also report this if it was a user error, so that a better error message can be provided next time. A bug report can be filed in the tracker at <https://github.com/sphinx-doc/sphinx/issues>. Thanks! make: *** [html] Error 1 ERROR: InvocationError: '/usr/bin/make -C /Users/alexwlchan/repos/urllib3/docs html' ________________________________________________________________________________ summary _________________________________________________________________________________ ERROR: docs: commands failed

Environment

  • Python: 2.7
  • urllib3: 2.0

What Broke

Building documentation fails due to version conflicts between urllib3 and requests.

Why It Broke

The unbundling of dependencies from requests caused urllib3 to present an incompatible version number

Fix Options (Details)

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

pip install urllib3==1.25

When NOT to use: This fix is not suitable if you require the latest development version of requests.

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

Option C — Workaround Temporary workaround

in requests itself?

When NOT to use: This fix is not suitable if you require the latest development version of requests.

Use only if you cannot change versions today. Treat this as a stopgap and remove once upgraded.

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

First fixed release: 1.25

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

Get updates

We publish verified fixes weekly. No spam.

Subscribe

When NOT to Use This Fix

  • This fix is not suitable if you require the latest development version of requests.

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.
  • Add a TLS smoke test that performs a real handshake in CI (include CA bundle validation and hostname checks).
  • Alert on handshake failures by error string and endpoint to catch cert/CA changes quickly.

Version Compatibility Table

VersionStatus
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.

Source & Disclaimer: Analysis derived from GitHub Issue #1182. Not affiliated with the library maintainers. Verify before production use.