How to fix a ReadTimeout error in Python requests
A ReadTimeout means the connection was established but the server did not finish sending data within the read window you allowed.
The usual remedy is a longer read timeout — but only after you rule out the possibility that the site is deliberately stalling your client. This guide shows how the two-value timeout works, how to reproduce the error on purpose, and how to decide whether to raise the value or investigate blocking.
What ReadTimeout actually tells you
The requests library splits a request into phases. The connect phase covers opening the socket to the host; the read phase covers waiting for the server to deliver bytes after the connection exists. A ReadTimeout is raised in the second phase, which is why the error can appear even when the host is reachable and DNS resolves fine.
That distinction matters for diagnosis. If the server never accepts the connection, you get a different exception. If it accepts the connection but then goes quiet, you get ReadTimeout. Treat the exception name as a pointer to the phase that stalled, not as a verdict about the site's health.
The timeout tuple, field by field
Passing a single number to timeout applies it to both phases. Passing a tuple lets you set them independently, and the order is fixed: connect first, read second. In the reproduction example below, the connect allowance is 5 seconds and the read allowance is 0.1 seconds — deliberately too short for a normal page load, which is what forces the error.
A quick map of the two positions:
- First tuple element (connect_timeout): how long to wait for the TCP connection to be established.
- Second tuple element (read_timeout): how long to wait for the server to send data once connected.
Both values are expressed in seconds. If you only care about the read phase, you still have to supply the connect value in the first position.
Reproducing the error on purpose
The snippet below is the intentional-failure version: a very small read timeout against a normal site. Running it is a useful sanity check that your exception handling catches the right class before you tune anything in production. The captured code module is reproduced exactly as supplied.
Deciding whether to raise the read timeout
Before you increase the value, work through this checklist:
- Is the host reachable at all? A connection refusal or DNS failure points elsewhere, not at the read phase.
- Does the same URL succeed from a different network or with a longer timeout? If yes, the server is simply slow for your path.
- Are you seeing 403s, captchas, or empty bodies on other requests to the same host? That pattern suggests the site is treating your client as unwanted traffic rather than being slow.
- Is the endpoint known to do heavy server-side work (reports, exports, search over large datasets)? Long read windows are normal there.
Only when the answer to the blocking question is negative does raising the read timeout make sense. The second captured snippet shows the corrected shape: a 6-second connect allowance and a 10-second read allowance.
ReadTimeout versus the neighbouring requests errors
ReadTimeout is one of several exceptions that look similar in a traceback but point at different stages. ConnectTimeout fires when the socket never opens in time. SSLError fires during the TLS handshake. MissingSchema fires before any network call, when the URL lacks a scheme. TooManyRedirects fires when the redirect chain exceeds the configured limit. Knowing which one you have saves you from raising timeouts that were never the problem.
Where to go next
The related question pages cover the other common requests exceptions, and the Requests tutorial walks through a full scraping workflow if you are building beyond a single call.
| Tuple position | Field name | Phase covered | Example value in the reproduction snippet | Example value in the fix snippet |
|---|---|---|---|---|
| First | connect_timeout | Opening the connection to the host | 5 | 6 |
| Second | read_timeout | Waiting for the server to send data after connecting | 0.1 | 10 |
Values are the exact numbers used in the two supplied snippets, both expressed in seconds. They are illustrative of the error and its fix, not recommended defaults for any particular site.
| Exception | Stage where it fires | Typical first check |
|---|---|---|
| ReadTimeout | After connection, while waiting for response data | Is the server slow, or is your client being stalled? |
| ConnectTimeout | While opening the connection | Is the host reachable and the port open? |
| SSLError | During the TLS handshake | Is the certificate chain valid and trusted? |
| MissingSchema | Before any network call | Does the URL include http:// or https://? |
| TooManyRedirects | During redirect following | Is the redirect chain looping? |
Stage descriptions are a plain-language summary of what each named exception indicates; the exact internal behaviour of the library is defined by its own documentation.
Frequently asked questions
What is the difference between a connect timeout and a read timeout in requests?
The connect value limits how long requests waits to establish the connection to the host. The read value limits how long it waits for the server to send data once connected. When you pass a tuple, the connect value comes first and the read value second.
Why does my request fail with ReadTimeout even though the site loads in a browser?
A browser is usually willing to wait much longer than a short programmatic timeout, and it may be served from a cache or a different network path. A read timeout of a fraction of a second, like the 0.1 seconds in the reproduction example, will fail on pages a browser opens comfortably.
Should I just set a very large read timeout to make the error go away?
Not without checking for blocking first. If the site is deliberately withholding data from your client, a longer timeout only makes each failed request slower. Confirm the host responds normally to other clients before you extend the read window.
Can I set only the read timeout and leave connect at the default?
The tuple form requires both positions. If you want to change only the read phase, supply a connect value you are comfortable with in the first position and your new read value in the second.