{"record":{"id":"195cd038c5e86651","repo":"pypa/pip","slug":"connection-timeout","errorCode":"connection-timeout","errorMessage":"Unable to fetch {url}","messagePattern":"Unable to fetch (.+?)","errorType":"exception","errorClass":"ConnectionTimeoutError","httpStatus":null,"severity":"error","filePath":"src/pip/_internal/network/utils.py","lineNumber":145,"sourceCode":"    else:\n        connect_timeout = read_timeout = timeout\n\n    if kind == \"connect\":\n        assert connect_timeout is not None\n        return connect_timeout\n    else:\n        assert read_timeout is not None\n        return read_timeout\n\n\ndef _raise_timeout_error(\n    reason: urllib3.exceptions.TimeoutError,\n    url: str,\n    host: str,\n    timeout: TimeoutValue,\n) -> NoReturn:\n    if isinstance(reason, urllib3.exceptions.ConnectTimeoutError):\n        raise ConnectionTimeoutError(\n            url, host, kind=\"connect\", timeout=_parse_timeout(timeout, \"connect\")\n        )\n    else:\n        raise ConnectionTimeoutError(\n            url, host, kind=\"read\", timeout=_parse_timeout(timeout, \"read\")\n        )\n\n\ndef raise_connection_error(\n    error: requests.ConnectionError | requests.Timeout,\n    *,\n    url: str,\n    timeout: TimeoutValue,\n) -> NoReturn:\n    \"\"\"Raise a specific error for a given connection error, if possible.\n\n    Note: requests.ConnectionError is the parent class of\n          requests.ProxyError, requests.SSLError, and requests.ConnectTimeout","sourceCodeStart":127,"sourceCodeEnd":163,"githubUrl":"https://github.com/pypa/pip/blob/f399c3718970b1b0e2478dac5296eb62679a9b86/src/pip/_internal/network/utils.py#L127-L163","documentation":"Raised as ConnectionTimeoutError (kind='connect') from _raise_timeout_error when urllib3 reports a ConnectTimeoutError: the TCP connection to the host did not complete within the configured connect timeout. The user-facing message is 'Unable to fetch {url}'.","triggerScenarios":"Pip requests a URL and the TCP handshake to the resolved host does not finish in time (SYN sent but no SYN-ACK, or host unreachable), causing urllib3.exceptions.ConnectTimeoutError to surface through raise_connection_error.","commonSituations":"Offline or captive-portal networks; very slow corporate links; firewall silently dropping packets; DNS resolves to a non-routable IP; default 15s timeout too short for a slow link.","solutions":["Raise the timeout: pip install --timeout 60 <pkg>.","Verify the host is reachable (curl, ping) and DNS resolves correctly.","Check firewall/proxy rules that may be dropping outbound HTTPS.","Retry; transient connect timeouts often succeed on a second attempt."],"exampleFix":"# before\npip install pkg\n\n# after\npip install --timeout 60 pkg","handlingStrategy":"retry","validationCode":"import socket\n\ndef host_connects(host: str, port: int = 443, timeout: float = 5.0) -> bool:\n    try:\n        with socket.create_connection((host, port), timeout=timeout):\n            return True\n    except OSError:\n        return False","typeGuard":null,"tryCatchPattern":"from pip._internal.exceptions import ConnectionTimeoutError\n\ntry:\n    run_pip_install([\"--timeout\", \"60\", \"pkg\"])\nexcept ConnectionTimeoutError:\n    run_pip_install([\"--timeout\", \"120\", \"pkg\"])","preventionTips":["Set a generous default timeout: 'pip config set global.timeout 60'.","Verify host reachability before large installs.","Retry transient connect timeouts."],"tags":["network","timeout","connection","connect-timeout"],"backgroundTag":null,"analyzedSha":"f399c3718970b1b0e2478dac5296eb62679a9b86","analyzedAt":"2026-08-08T23:01:42.227Z","contentChangedAt":null,"schemaVersion":2},"datasetVersion":"2026-09-23T08:17:48.524Z"}