Install & Compatibility
Where this runs
tested against v2.33.0.20260712 · pip install
no network on importno background threads
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
muslpy 3.10–3.910 runs
installs and imports cleanly · install 0.0s · import 0.344s · 21.2MB
glibcpy 3.10–3.910 runs
installs and imports cleanly · install 2.2s · import 0.324s · 22MB
19MB installed
● package 19MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
requests
✓ import requests
✗ import requests-stubs
This quickstart demonstrates a basic `requests.get` call with type hints. When `types-requests` is installed, a type checker (like Mypy or Pyright) will use the stub files to validate the types of `url`, `params`, and the return values from `requests.get` and `response.json()` without needing explicit annotations for the `requests` library itself.
import requests
from typing import Dict, Any
def fetch_data(url: str, params: Dict[str, str] = {}) -> Dict[str, Any]:
"""Fetches JSON data from a URL with type hints provided by types-requests."""
try:
response = requests.get(url, params=params)
response.raise_for_status() # Raises HTTPError for bad responses (4xx or 5xx)
return response.json()
except requests.exceptions.HTTPError as e:
print(f"HTTP error occurred: {e}")
raise
except requests.exceptions.RequestException as e:
print(f"An error occurred during the request: {e}")
raise
# Example usage:
if __name__ == "__main__":
base_url = "https://httpbin.org/get"
query_params = {"key1": "value1", "key2": "value2"}
try:
data = fetch_data(base_url, query_params)
print("Fetched data:")
print(data)
except Exception:
print("Failed to fetch data.")
Debug
Known issues
breakingVersion incompatibility with `urllib3` prior to types-requests 2.31.0.7. Versions of `types-requests` from `2.31.0.7` onwards require `urllib3>=2`. If your `requests` installation depends on an older `urllib3<2`, installing a newer `types-requests` will cause type checking issues due to conflicting stub dependencies.fixFor projects that *must* use `urllib3<2`, pin `types-requests<2.31.0.7`. For `urllib3>=2` environments, use `types-requests>=2.31.0.7`. Consider aligning your `requests` and `types-requests` version bounds for compatibility.
affects: <2.31.0.7 (compatible with urllib3<2), >=2.31.0.7 (compatible with urllib3>=2)
gotchaInstalling `types-requests` does not install `requests` itself. This package only provides type annotations for the `requests` library. The `requests` library must be installed separately for your code to run at runtime.fixEnsure you have both `pip install requests` and `pip install types-requests` if you want both runtime functionality and type checking in your environment.
affects: All
gotchaStub package versioning does not always directly mirror the runtime package version. While the first three parts of `types-requests`'s version generally align with `requests` (e.g., `types-requests==2.33.0.YYYYMMDD` is for `requests~=2.33.0`), the final part is a daily release date from the Typeshed repository. Minor stub updates can introduce new type-checking errors even if the runtime `requests` package has not changed.fixPinning `types-requests` to an exact version (e.g., `types-requests==2.33.0.20260327`) in your `requirements.txt` can prevent unexpected type-checking failures, though it means you might miss beneficial stub bug fixes. Alternatively, use version ranges for both `requests` and `types-requests` to manage compatibility.
affects: All
gotchaDo not attempt to import `types_requests` directly in your Python code. Stub packages are automatically discovered by type checkers and are not meant for direct runtime import. Attempting to import it will result in a `ModuleNotFoundError` during program execution.fixAlways `import requests` in your code. The type checker will correctly associate this import with the installed `types-requests` stubs.
affects: All
Upgrade
Version history
2.33.0.20260712latest on PyPI · released Jul 12, 2026
Audit
Dependencies
requestsrequiredProvides runtime functionality for which these stubs offer type hints. Must be installed alongside types-requests for type checking to be useful.
urllib3>=2requiredtypes-requests versions >=2.31.0.7 require urllib3>=2. This can cause conflicts if the installed requests library explicitly pins an older urllib3 version.