{"id":592,"library":"types-requests","title":"Typing Stubs for requests","description":"types-requests provides static type annotations for the popular `requests` HTTP library. It allows type checkers like Mypy and Pyright to analyze code using `requests` for type correctness. This package, part of the larger Typeshed project, aims to provide accurate annotations for `requests~=2.33.0` and is frequently updated, often daily, from the Typeshed repository.","status":"active","version":"2.33.0.20260327","language":"python","source_language":"en","source_url":"https://github.com/python/typeshed","tags":["typing","stubs","type hints","requests","typeshed"],"install":[{"cmd":"pip install types-requests","lang":"bash","label":"Install only stubs"},{"cmd":"pip install requests types-requests","lang":"bash","label":"Install requests and its stubs"}],"dependencies":[{"reason":"Provides runtime functionality for which these stubs offer type hints. Must be installed alongside types-requests for type checking to be useful.","package":"requests","optional":false},{"reason":"types-requests versions >=2.31.0.7 require urllib3>=2. This can cause conflicts if the installed requests library explicitly pins an older urllib3 version.","package":"urllib3>=2","optional":false}],"imports":[{"note":"types-requests is a stub package for the 'requests' library. You install it separately for your type checker, but you import 'requests' in your code. The type checker automatically discovers the installed stubs. Do not attempt to import 'types_requests' directly; it will result in a ModuleNotFoundError.","wrong":"import types_requests","symbol":"requests","correct":"import requests"},{"note":"Similar to the main 'requests' import, the types for Session and other sub-modules are provided by the installed stubs.","symbol":"requests.Session","correct":"import requests\nsession: requests.Session = requests.Session()"}],"quickstart":{"code":"import requests\nfrom typing import Dict, Any\n\ndef fetch_data(url: str, params: Dict[str, str] = {}) -> Dict[str, Any]:\n    \"\"\"Fetches JSON data from a URL with type hints provided by types-requests.\"\"\"\n    try:\n        response = requests.get(url, params=params)\n        response.raise_for_status() # Raises HTTPError for bad responses (4xx or 5xx)\n        return response.json()\n    except requests.exceptions.HTTPError as e:\n        print(f\"HTTP error occurred: {e}\")\n        raise\n    except requests.exceptions.RequestException as e:\n        print(f\"An error occurred during the request: {e}\")\n        raise\n\n# Example usage:\nif __name__ == \"__main__\":\n    base_url = \"https://httpbin.org/get\"\n    query_params = {\"key1\": \"value1\", \"key2\": \"value2\"}\n    try:\n        data = fetch_data(base_url, query_params)\n        print(\"Fetched data:\")\n        print(data)\n    except Exception:\n        print(\"Failed to fetch data.\")","lang":"python","description":"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."},"warnings":[{"fix":"For 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.","message":"Version 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.","severity":"breaking","affected_versions":"<2.31.0.7 (compatible with urllib3<2), >=2.31.0.7 (compatible with urllib3>=2)"},{"fix":"Ensure you have both `pip install requests` and `pip install types-requests` if you want both runtime functionality and type checking in your environment.","message":"Installing `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.","severity":"gotcha","affected_versions":"All"},{"fix":"Pinning `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.","message":"Stub 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.","severity":"gotcha","affected_versions":"All"},{"fix":"Always `import requests` in your code. The type checker will correctly associate this import with the installed `types-requests` stubs.","message":"Do 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.","severity":"gotcha","affected_versions":"All"}],"env_vars":null,"last_verified":"2026-05-12T16:23:45.578Z","next_check":"2026-06-26T00:00:00.000Z","problems":[{"fix":"Install the 'types-requests' package using pip: `pip install types-requests`","cause":"The 'types-requests' package, which provides static type annotations for the 'requests' library, is not installed in the environment where the type checker (e.g., Mypy or Pyright) is being run.","error":"Cannot find implementation or library stub for module named 'requests'"},{"fix":"Remove any `import types_requests` statements. Instead, import `requests` as usual (e.g., `import requests` or `from requests import get`), ensuring that `types-requests` is installed in your environment for type checking tools.","cause":"The 'types-requests' package provides stub files for type checkers and is not intended to be imported directly into Python code. The 'requests' library itself should be imported.","error":"ModuleNotFoundError: No module named 'types_requests'"},{"fix":"Safely handle the `Optional` return type by checking for `None` before accessing the data, or provide a default value. For example: \n```python\nimport requests\n\nresponse = requests.get('https://api.example.com/data')\ndata = response.json()\n\nif data is not None:\n    value = data.get('key')\n    print(value)\nelse:\n    print('No JSON data or invalid JSON.')\n\n# Or, provide a default empty dict:\nsafe_data = response.json() or {}\nvalue = safe_data.get('key')\nprint(value)\n```","cause":"This Mypy error occurs when attempting to access keys or methods on the result of `response.json()` without checking if it's `None`. The `json()` method's type annotation correctly indicates it might return `None` if the response body is empty or not valid JSON.","error":"error: Item \"None\" of \"Optional[Any]\" has no attribute \"get\""}],"ecosystem":"pypi","meta_description":null,"install_score":100,"install_tag":"verified","quickstart_score":0,"quickstart_tag":"stale","pypi_latest":"2.33.0.20260508","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.52,"mem_mb":9.7,"disk_size":"21.3M"},{"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":"18.8M"},{"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.56,"mem_mb":9.6,"disk_size":"21.2M"},{"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":2.1,"import_time_s":0.35,"mem_mb":9.7,"disk_size":"22M"},{"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.6,"import_time_s":null,"mem_mb":null,"disk_size":"19M"},{"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.4,"mem_mb":9.6,"disk_size":"22M"},{"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.67,"mem_mb":10.8,"disk_size":"23.3M"},{"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":"20.8M"},{"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.79,"mem_mb":10.8,"disk_size":"23.3M"},{"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":2.1,"import_time_s":0.58,"mem_mb":10.8,"disk_size":"24M"},{"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":null,"mem_mb":null,"disk_size":"21M"},{"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.57,"mem_mb":10.7,"disk_size":"24M"},{"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.62,"mem_mb":11.3,"disk_size":"15.1M"},{"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":"12.7M"},{"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.67,"mem_mb":11.2,"disk_size":"15.1M"},{"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.9,"import_time_s":0.63,"mem_mb":11.3,"disk_size":"16M"},{"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.5,"import_time_s":null,"mem_mb":null,"disk_size":"13M"},{"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.68,"mem_mb":11.2,"disk_size":"16M"},{"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.6,"mem_mb":11.6,"disk_size":"14.9M"},{"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":"12.4M"},{"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.65,"mem_mb":11.6,"disk_size":"14.7M"},{"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":2,"import_time_s":0.59,"mem_mb":11.6,"disk_size":"15M"},{"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":null,"mem_mb":null,"disk_size":"13M"},{"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.64,"mem_mb":11.6,"disk_size":"15M"},{"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.47,"mem_mb":9.4,"disk_size":"20.5M"},{"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":"18.3M"},{"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.51,"mem_mb":9.5,"disk_size":"20.6M"},{"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":2.5,"import_time_s":0.42,"mem_mb":9.4,"disk_size":"21M"},{"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":null,"mem_mb":null,"disk_size":"19M"},{"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.41,"mem_mb":9.5,"disk_size":"21M"},{"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-23","tag":"stale","tag_description":"widespread failures or data too old to trust","results":[{"runtime":"python:3.10-alpine","exit_code":1},{"runtime":"python:3.10-slim","exit_code":1},{"runtime":"python:3.11-alpine","exit_code":1},{"runtime":"python:3.11-slim","exit_code":1},{"runtime":"python:3.12-alpine","exit_code":1},{"runtime":"python:3.12-slim","exit_code":1},{"runtime":"python:3.13-alpine","exit_code":1},{"runtime":"python:3.13-slim","exit_code":1},{"runtime":"python:3.9-alpine","exit_code":1},{"runtime":"python:3.9-slim","exit_code":1}]}}