{"id":723,"library":"types-urllib3","title":"Typing stubs for urllib3","description":"This is a PEP 561 type stub package providing type annotations for the `urllib3` library. It enables type-checking tools like Mypy, Pyright, and PyCharm to statically analyze code that uses `urllib3`. The package version is 1.26.25.14, and it is released as needed to align with updates from the `typeshed` repository. Users of `urllib3` version 2.0.0 or newer should *not* install this package, as `urllib3` now includes inline type annotations.","status":"maintenance","version":"1.26.25.14","language":"python","source_language":"en","source_url":"https://github.com/python/typeshed/tree/main/stubs/urllib3","tags":["typing","stubs","type-checking","urllib3","mypy","typeshed"],"install":[{"cmd":"pip install 'urllib3<2' types-urllib3","lang":"bash","label":"Install for urllib3 < 2.0"},{"cmd":"pip install mypy","lang":"bash","label":"Install a type checker"}],"dependencies":[{"reason":"Provides type stubs for this library; `urllib3` must be installed for runtime functionality.","package":"urllib3","optional":false},{"reason":"Primary tool for utilizing type stubs; not a runtime dependency.","package":"mypy","optional":true}],"imports":[{"symbol":"PoolManager","correct":"from urllib3 import PoolManager"},{"symbol":"HTTPResponse","correct":"from urllib3.response import HTTPResponse"},{"note":"types-urllib3 is a stub-only package and is not imported directly at runtime; it provides type information for the `urllib3` library.","wrong":"import types_urllib3","symbol":"urllib3","correct":"import urllib3"}],"quickstart":{"code":"# mypy_example.py\nimport urllib3\n\n# Ensure urllib3 < 2.0 is installed for types-urllib3 to be effective\n# For urllib3 >= 2.0, its own inline types should be used.\nhttp = urllib3.PoolManager()\n\ndef fetch_url(url: str) -> str:\n    try:\n        resp = http.request('GET', url)\n        return resp.data.decode('utf-8')\n    except urllib3.exceptions.MaxRetryError as e:\n        return f\"Error fetching URL: {e}\"\n\nif __name__ == '__main__':\n    # Example usage - replace with a real URL or use a test server\n    result = fetch_url('http://httpbin.org/status/200')\n    print(result)\n    # Run with mypy: mypy mypy_example.py","lang":"python","description":"This example demonstrates how to use `urllib3` with the `types-urllib3` stubs for static type checking. After installing `urllib3<2`, `types-urllib3`, and `mypy`, save the code as `mypy_example.py`. Running `mypy mypy_example.py` will verify type correctness using the provided stubs. This setup is crucial for older `urllib3` versions that lack inline type hints."},"warnings":[{"fix":"Uninstall `types-urllib3` if `urllib3` is version 2.0.0 or higher: `pip uninstall types-urllib3`.","message":"Do not install `types-urllib3` if you are using `urllib3` version 2.0.0 or newer. `urllib3>=2.0.0` includes its own inline type annotations. Installing `types-urllib3` alongside `urllib3>=2.0.0` will cause type checkers (like Mypy) to ignore the accurate inline types of `urllib3` in favor of the potentially outdated stubs from `types-urllib3`, leading to incorrect type-checking results.","severity":"breaking","affected_versions":"urllib3 >= 2.0.0"},{"fix":"Ensure `urllib3` is installed alongside `types-urllib3`: `pip install urllib3 types-urllib3`.","message":"`types-urllib3` is a stub-only package and does not provide any runtime code or functionality. You must explicitly install the `urllib3` library itself to use its features in your application. `types-urllib3` only provides the type definitions for `urllib3`.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Pin `types-requests` to a compatible version (e.g., `<2.31.0.7` for `urllib3<2`) or upgrade `types-requests` and `urllib3` to compatible versions that use `urllib3`'s inline types directly.","message":"When using `types-requests`, be aware of potential dependency conflicts with `urllib3` versions. Earlier versions of `types-requests` might have implicitly depended on `types-urllib3`, which expected `urllib3<2`. This could lead to type-checking issues if your project uses `urllib3>=2.0.0` with a `types-requests` version that expects the older stub package.","severity":"gotcha","affected_versions":"types-requests < 2.31.0.7"}],"env_vars":null,"last_verified":"2026-05-12T18:17:39.857Z","next_check":"2026-06-26T00:00:00.000Z","problems":[{"fix":"Uninstall `types-urllib3` using `pip uninstall types-urllib3`.","cause":"This Mypy error occurs when both `urllib3` version 2.0 or newer (which includes inline type annotations) and the separate `types-urllib3` stub package are installed, leading to a conflict where Mypy finds duplicate type definitions for the `urllib3` module.","error":"Multiple definitions of name 'urllib3'"},{"fix":"Install `types-urllib3` using `pip install types-urllib3` to provide the necessary type stubs for `urllib3 < 2.0`.","cause":"This Mypy error indicates that type annotations for the `urllib3` library are missing, which typically happens when using `urllib3` versions older than 2.0 without the corresponding `types-urllib3` stub package installed.","error":"No type hints found for \"urllib3\""},{"fix":"Upgrade your Python environment to version 3.7 or newer, or use a Python environment that meets the package's requirements.","cause":"This error occurs when attempting to install `types-urllib3` on a Python version older than 3.7, which is not supported by the package.","error":"ERROR: Package 'types-urllib3' requires a different Python: X.Y.Z not in '>=3.7'"}],"ecosystem":"pypi","meta_description":null,"install_score":100,"install_tag":"verified","quickstart_score":80,"quickstart_tag":"verified","pypi_latest":"1.26.25.14","install_checks":{"last_tested":"2026-05-12","tag":"verified","tag_description":"installs cleanly on critical runtimes, fast import, recently tested","results":[{"runtime":"python:3.10-alpine","python_version":"3.10","os_libc":"alpine (musl)","variant":" $EXIT -eq 0 ","exit_code":0,"wheel_type":"wheel","failure_reason":null,"install_time_s":null,"import_time_s":0.15,"mem_mb":4.3,"disk_size":"18.8M"},{"runtime":"python:3.10-alpine","python_version":"3.10","os_libc":"alpine (musl)","variant":" $EXIT -eq 0 ","exit_code":0,"wheel_type":"wheel","failure_reason":null,"install_time_s":null,"import_time_s":null,"mem_mb":null,"disk_size":"146.7M"},{"runtime":"python:3.10-alpine","python_version":"3.10","os_libc":"alpine (musl)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":0.14,"mem_mb":4.3,"disk_size":"18.8M"},{"runtime":"python:3.10-alpine","python_version":"3.10","os_libc":"alpine (musl)","variant":"default","exit_code":1,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":null,"mem_mb":null,"disk_size":null},{"runtime":"python:3.10-slim","python_version":"3.10","os_libc":"slim (glibc)","variant":" $EXIT -eq 0 ","exit_code":0,"wheel_type":"wheel","failure_reason":null,"install_time_s":1.7,"import_time_s":0.1,"mem_mb":4.3,"disk_size":"19M"},{"runtime":"python:3.10-slim","python_version":"3.10","os_libc":"slim (glibc)","variant":" $EXIT -eq 0 ","exit_code":0,"wheel_type":"wheel","failure_reason":null,"install_time_s":3.5,"import_time_s":null,"mem_mb":null,"disk_size":"216M"},{"runtime":"python:3.10-slim","python_version":"3.10","os_libc":"slim (glibc)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":0.1,"mem_mb":4.3,"disk_size":"19M"},{"runtime":"python:3.10-slim","python_version":"3.10","os_libc":"slim (glibc)","variant":"default","exit_code":1,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":null,"mem_mb":null,"disk_size":null},{"runtime":"python:3.11-alpine","python_version":"3.11","os_libc":"alpine (musl)","variant":" $EXIT -eq 0 ","exit_code":0,"wheel_type":"wheel","failure_reason":null,"install_time_s":null,"import_time_s":0.25,"mem_mb":4.7,"disk_size":"20.8M"},{"runtime":"python:3.11-alpine","python_version":"3.11","os_libc":"alpine (musl)","variant":" $EXIT -eq 0 ","exit_code":0,"wheel_type":"wheel","failure_reason":null,"install_time_s":null,"import_time_s":null,"mem_mb":null,"disk_size":"156.1M"},{"runtime":"python:3.11-alpine","python_version":"3.11","os_libc":"alpine (musl)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":0.26,"mem_mb":4.7,"disk_size":"20.8M"},{"runtime":"python:3.11-alpine","python_version":"3.11","os_libc":"alpine (musl)","variant":"default","exit_code":1,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":null,"mem_mb":null,"disk_size":null},{"runtime":"python:3.11-slim","python_version":"3.11","os_libc":"slim (glibc)","variant":" $EXIT -eq 0 ","exit_code":0,"wheel_type":"wheel","failure_reason":null,"install_time_s":1.7,"import_time_s":0.21,"mem_mb":4.7,"disk_size":"21M"},{"runtime":"python:3.11-slim","python_version":"3.11","os_libc":"slim (glibc)","variant":" $EXIT -eq 0 ","exit_code":0,"wheel_type":"wheel","failure_reason":null,"install_time_s":3.5,"import_time_s":null,"mem_mb":null,"disk_size":"225M"},{"runtime":"python:3.11-slim","python_version":"3.11","os_libc":"slim (glibc)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":0.2,"mem_mb":4.7,"disk_size":"21M"},{"runtime":"python:3.11-slim","python_version":"3.11","os_libc":"slim (glibc)","variant":"default","exit_code":1,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":null,"mem_mb":null,"disk_size":null},{"runtime":"python:3.12-alpine","python_version":"3.12","os_libc":"alpine (musl)","variant":" $EXIT -eq 0 ","exit_code":0,"wheel_type":"wheel","failure_reason":null,"install_time_s":null,"import_time_s":0.18,"mem_mb":4.6,"disk_size":"12.7M"},{"runtime":"python:3.12-alpine","python_version":"3.12","os_libc":"alpine (musl)","variant":" $EXIT -eq 0 ","exit_code":0,"wheel_type":"wheel","failure_reason":null,"install_time_s":null,"import_time_s":null,"mem_mb":null,"disk_size":"146.9M"},{"runtime":"python:3.12-alpine","python_version":"3.12","os_libc":"alpine (musl)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":0.19,"mem_mb":4.6,"disk_size":"12.7M"},{"runtime":"python:3.12-alpine","python_version":"3.12","os_libc":"alpine (musl)","variant":"default","exit_code":1,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":null,"mem_mb":null,"disk_size":null},{"runtime":"python:3.12-slim","python_version":"3.12","os_libc":"slim (glibc)","variant":" $EXIT -eq 0 ","exit_code":0,"wheel_type":"wheel","failure_reason":null,"install_time_s":1.6,"import_time_s":0.19,"mem_mb":4.6,"disk_size":"13M"},{"runtime":"python:3.12-slim","python_version":"3.12","os_libc":"slim (glibc)","variant":" $EXIT -eq 0 ","exit_code":0,"wheel_type":"wheel","failure_reason":null,"install_time_s":3.2,"import_time_s":null,"mem_mb":null,"disk_size":"216M"},{"runtime":"python:3.12-slim","python_version":"3.12","os_libc":"slim (glibc)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":0.2,"mem_mb":4.6,"disk_size":"13M"},{"runtime":"python:3.12-slim","python_version":"3.12","os_libc":"slim (glibc)","variant":"default","exit_code":1,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":null,"mem_mb":null,"disk_size":null},{"runtime":"python:3.13-alpine","python_version":"3.13","os_libc":"alpine (musl)","variant":" $EXIT -eq 0 ","exit_code":0,"wheel_type":"wheel","failure_reason":null,"install_time_s":null,"import_time_s":0.15,"mem_mb":4.6,"disk_size":"12.4M"},{"runtime":"python:3.13-alpine","python_version":"3.13","os_libc":"alpine (musl)","variant":" $EXIT -eq 0 ","exit_code":0,"wheel_type":"wheel","failure_reason":null,"install_time_s":null,"import_time_s":null,"mem_mb":null,"disk_size":"143.7M"},{"runtime":"python:3.13-alpine","python_version":"3.13","os_libc":"alpine (musl)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":0.16,"mem_mb":4.6,"disk_size":"12.3M"},{"runtime":"python:3.13-alpine","python_version":"3.13","os_libc":"alpine (musl)","variant":"default","exit_code":1,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":null,"mem_mb":null,"disk_size":null},{"runtime":"python:3.13-slim","python_version":"3.13","os_libc":"slim (glibc)","variant":" $EXIT -eq 0 ","exit_code":0,"wheel_type":"wheel","failure_reason":null,"install_time_s":1.6,"import_time_s":0.16,"mem_mb":4.5,"disk_size":"13M"},{"runtime":"python:3.13-slim","python_version":"3.13","os_libc":"slim (glibc)","variant":" $EXIT -eq 0 ","exit_code":0,"wheel_type":"wheel","failure_reason":null,"install_time_s":3.5,"import_time_s":null,"mem_mb":null,"disk_size":"215M"},{"runtime":"python:3.13-slim","python_version":"3.13","os_libc":"slim (glibc)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":0.17,"mem_mb":4.5,"disk_size":"13M"},{"runtime":"python:3.13-slim","python_version":"3.13","os_libc":"slim (glibc)","variant":"default","exit_code":1,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":null,"mem_mb":null,"disk_size":null},{"runtime":"python:3.9-alpine","python_version":"3.9","os_libc":"alpine (musl)","variant":" $EXIT -eq 0 ","exit_code":0,"wheel_type":"wheel","failure_reason":null,"install_time_s":null,"import_time_s":0.13,"mem_mb":4.5,"disk_size":"18.3M"},{"runtime":"python:3.9-alpine","python_version":"3.9","os_libc":"alpine (musl)","variant":" $EXIT -eq 0 ","exit_code":0,"wheel_type":"wheel","failure_reason":null,"install_time_s":null,"import_time_s":null,"mem_mb":null,"disk_size":"135.2M"},{"runtime":"python:3.9-alpine","python_version":"3.9","os_libc":"alpine (musl)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":0.15,"mem_mb":4.5,"disk_size":"18.3M"},{"runtime":"python:3.9-alpine","python_version":"3.9","os_libc":"alpine (musl)","variant":"default","exit_code":1,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":null,"mem_mb":null,"disk_size":null},{"runtime":"python:3.9-slim","python_version":"3.9","os_libc":"slim (glibc)","variant":" $EXIT -eq 0 ","exit_code":0,"wheel_type":"wheel","failure_reason":null,"install_time_s":1.9,"import_time_s":0.12,"mem_mb":4.5,"disk_size":"19M"},{"runtime":"python:3.9-slim","python_version":"3.9","os_libc":"slim (glibc)","variant":" $EXIT -eq 0 ","exit_code":0,"wheel_type":"wheel","failure_reason":null,"install_time_s":4,"import_time_s":null,"mem_mb":null,"disk_size":"205M"},{"runtime":"python:3.9-slim","python_version":"3.9","os_libc":"slim (glibc)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":0.12,"mem_mb":4.5,"disk_size":"19M"},{"runtime":"python:3.9-slim","python_version":"3.9","os_libc":"slim (glibc)","variant":"default","exit_code":1,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":null,"mem_mb":null,"disk_size":null}]},"quickstart_checks":{"last_tested":"2026-04-24","tag":"verified","tag_description":"quickstart runs on critical runtimes, recently tested","results":[{"runtime":"python:3.10-alpine","exit_code":0},{"runtime":"python:3.10-slim","exit_code":0},{"runtime":"python:3.11-alpine","exit_code":0},{"runtime":"python:3.11-slim","exit_code":0},{"runtime":"python:3.12-alpine","exit_code":0},{"runtime":"python:3.12-slim","exit_code":0},{"runtime":"python:3.13-alpine","exit_code":0},{"runtime":"python:3.13-slim","exit_code":0},{"runtime":"python:3.9-alpine","exit_code":0},{"runtime":"python:3.9-slim","exit_code":0}]}}