Skip to content

Timeouts in Python requests

Timeouts in Python requests Cover Image

In this tutorial, you’ll learn how to use timeouts in the Python requests library, when working with any type of HTTP request being made. By default, the requests library will not time out any request you make, which can result in your programming running indefinitely if a server doesn’t respond.

By the end of this tutorial, you’ll have learned:

  • How to set timeouts in requests
  • How to set unique timeouts for connecting and reading in Python requests
  • How to catch and handle timeout errors in Python requests

How Does Python requests Handle Timeouts?

By default, the Python requests library does not set a timeout for any request it sends. This is true for GET, POST, and PUT requests. While this can prevent unexpected errors, it can result in your request running indefinitely.

Because of this, it’s important to set a timeout to prevent unexpected behavior. Remember, the Python requests library will not timeout by default, unless explicitly instructed.

How to Set a Timeout for Python requests

In order to set a timeout in an HTTP request made via the requests library, you can use the timeout parameter. The parameter accepts either an integer or a floating point value, which describes the time in seconds.

It’s important to note that this behavior is different from many other HTTP request libraries, such as those in JavaScript. In other libraries or languages, this behavior tends to be expressed in milliseconds.

Let’s take a look at an example of how we can send a GET request with a timeout:

# Setting a Timeout on a GET Request with an Integer
import requests
resp = requests.get('', timeout=3)

In the example above, we set a timeout of 3 seconds. We used an integer to represent the time of our timeout. If we wanted to be more precise, we could also pass in a floating point value:

# Setting a Timeout on a GET Request with a Floating Point Value
import requests
resp = requests.get('', timeout=3.5)

By passing in a single value, we set a timeout for the request. If we wanted to set different timeouts for connecting and reading a request, we can pass in a tuple of values.

How to Set Timeouts for Connecting and Reading in Python requests

In some cases, you’ll want to set different timeouts for making a connection and for reading results. This can easily be done using the timeout parameter in the requests library. Similar to the example above, this can be applied to any type of request being made.

Let’s see how we can pass in different timeout limits for connecting and reading requests in the Python requests library:

# Setting Different Timeouts for Connecting and Reading Requests
import requests
resp = requests.get('', timeout=(1, 2))

In the example above, we set the request to timeout after 1 second for connecting and 2 seconds for reading the request.

In the following section, you’ll learn how to catch and handle errors that arise due to requests timing out.

How to Catch and Handle Timeout Errors in Python requests

When applying a timeout, it’s important to note that this is not a time limit on the entire response. Instead, it raises an exception if no bytes have been received on the underlying socket.

If the request does not receive any bytes within the specified timeout limit, a Timeout error is raised. Let’s see what this looks like:

# Raising a Timeout Error in a Python requests GET Request
import requests
resp = requests.get('', timeout=0.0001)

# Raises:
# ConnectTimeoutError(<urllib3.connection.HTTPSConnection object at 0x7fbc988f59a0>, 'Connection to timed out. (connect timeout=0.0001)')

In order to prevent your program from crashing, you need to handle the exception using a try-except block. Let’s see how this can be done:

# Handling a Timeout Error
import requests
from requests.exceptions import ConnectTimeout

    requests.get('', timeout=0.0001)
except ConnectTimeout:
    print('Request has timed out')

# Returns:
# Request has timed out

We can see in the code above that the error was handled safely. In order to do this, we:

  1. Imported the error from the exceptions module of the requests library
  2. We created a try-except block to handle the ConnectTimeout error.

Frequently Asked Questions

What is the default timeout for Python requests?

None. There is no default timeout for Python requests, unless explicitly set using the timeout parameter.

How do you set a timeout for requests made in Python?

You set a timeout (in seconds) using the timeout= parameter when making HTTP requests in the Python requests library.

What is the best time to set for a timeout for requests made in Python?

While there is no best set value for timeouts for HTTP requests made in Python, a good practice is to set them under 500ms. This allows your application to provide a better user experience and to process more requests.


In this tutorial, you learned how to handle timeouts in the Python requests library. You first learned how the Python requests library handles timeouts. Then, you learned how to set timeouts when making HTTP requests, both using integers and floating point values. Then, you learned how to specify specific timeouts for connecting and reading requests. Finally, you learned how to handle timeout exceptions in the Python requests library.

Additional Resources

To learn more about related topics, check out the tutorials below:

Nik Piepenbreier

Nik is the author of and has over a decade of experience working with data analytics, data science, and Python. He specializes in teaching developers how to use Python for data science using hands-on tutorials.View Author posts

Leave a Reply

Your email address will not be published. Required fields are marked *