Typing stubs for urllib3

1.26.25.14 verified Tue May 12 auth: no python install: verified quickstart: verified maintenance

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.

pip install 'urllib3<2' types-urllib3

Common errors

error Multiple definitions of name '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.

fix

Uninstall types-urllib3 using pip uninstall types-urllib3.

error No type hints found for "urllib3" ↓

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.

fix

Install types-urllib3 using pip install types-urllib3 to provide the necessary type stubs for urllib3 < 2.0.

error ERROR: Package 'types-urllib3' requires a different Python: X.Y.Z not in '>=3.7' ↓

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.

fix

Upgrade your Python environment to version 3.7 or newer, or use a Python environment that meets the package's requirements.

Warnings

breaking 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. ↓

fix Uninstall `types-urllib3` if `urllib3` is version 2.0.0 or higher: `pip uninstall types-urllib3`.

gotcha `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`. ↓

fix Ensure `urllib3` is installed alongside `types-urllib3`: `pip install urllib3 types-urllib3`.

gotcha 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. ↓

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.

Install

pip install mypy

Install compatibility verified last tested: 2026-05-12

python os / libc variant status wheel install import disk

3.10 alpine (musl) 'urllib3<2' wheel - 0.15s 18.8M

3.10 alpine (musl) mypy wheel - - 146.7M

3.10 alpine (musl) 'urllib3<2' - - 0.14s 18.8M

3.10 alpine (musl) mypy - - - -

3.10 slim (glibc) 'urllib3<2' wheel 1.7s 0.10s 19M

3.10 slim (glibc) mypy wheel 3.5s - 216M

3.10 slim (glibc) 'urllib3<2' - - 0.10s 19M

3.10 slim (glibc) mypy - - - -

3.11 alpine (musl) 'urllib3<2' wheel - 0.25s 20.8M

3.11 alpine (musl) mypy wheel - - 156.1M

3.11 alpine (musl) 'urllib3<2' - - 0.26s 20.8M

3.11 alpine (musl) mypy - - - -

3.11 slim (glibc) 'urllib3<2' wheel 1.7s 0.21s 21M

3.11 slim (glibc) mypy wheel 3.5s - 225M

3.11 slim (glibc) 'urllib3<2' - - 0.20s 21M

3.11 slim (glibc) mypy - - - -

3.12 alpine (musl) 'urllib3<2' wheel - 0.18s 12.7M

3.12 alpine (musl) mypy wheel - - 146.9M

3.12 alpine (musl) 'urllib3<2' - - 0.19s 12.7M

3.12 alpine (musl) mypy - - - -

3.12 slim (glibc) 'urllib3<2' wheel 1.6s 0.19s 13M

3.12 slim (glibc) mypy wheel 3.2s - 216M

3.12 slim (glibc) 'urllib3<2' - - 0.20s 13M

3.12 slim (glibc) mypy - - - -

3.13 alpine (musl) 'urllib3<2' wheel - 0.15s 12.4M

3.13 alpine (musl) mypy wheel - - 143.7M

3.13 alpine (musl) 'urllib3<2' - - 0.16s 12.3M

3.13 alpine (musl) mypy - - - -

3.13 slim (glibc) 'urllib3<2' wheel 1.6s 0.16s 13M

3.13 slim (glibc) mypy wheel 3.5s - 215M

3.13 slim (glibc) 'urllib3<2' - - 0.17s 13M

3.13 slim (glibc) mypy - - - -

3.9 alpine (musl) 'urllib3<2' wheel - 0.13s 18.3M

3.9 alpine (musl) mypy wheel - - 135.2M

3.9 alpine (musl) 'urllib3<2' - - 0.15s 18.3M

3.9 alpine (musl) mypy - - - -

3.9 slim (glibc) 'urllib3<2' wheel 1.9s 0.12s 19M

3.9 slim (glibc) mypy wheel 4.0s - 205M

3.9 slim (glibc) 'urllib3<2' - - 0.12s 19M

3.9 slim (glibc) mypy - - - -

Imports

PoolManager
```
from urllib3 import PoolManager
```

HTTPResponse

from urllib3.response import HTTPResponse

urllib3
wrong
```
import types_urllib3
```
correct
```
import urllib3
```
types-urllib3 is a stub-only package and is not imported directly at runtime; it provides type information for the `urllib3` library.

Quickstart verified last tested: 2026-04-24

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.

# mypy_example.py
import urllib3

# Ensure urllib3 < 2.0 is installed for types-urllib3 to be effective
# For urllib3 >= 2.0, its own inline types should be used.
http = urllib3.PoolManager()

def fetch_url(url: str) -> str:
    try:
        resp = http.request('GET', url)
        return resp.data.decode('utf-8')
    except urllib3.exceptions.MaxRetryError as e:
        return f"Error fetching URL: {e}"

if __name__ == '__main__':
    # Example usage - replace with a real URL or use a test server
    result = fetch_url('http://httpbin.org/status/200')
    print(result)
    # Run with mypy: mypy mypy_example.py