Python Requests head() Method

The Python Requests head() method sends an HTTP HEAD request to a specified URL. A HEAD request is similar to a GET request, but it only retrieves the headers and not the body of the response.

This is useful for checking resource metadata such as size or modification date, without downloading the entire content. The typical use cases include checking if a resource exists or retrieving header information before deciding to make a full GET request.

The syntax and optional parameters for requests.head() are similar to those for requests.get() which allows customization with headers, authentication, timeouts and more.

Syntax

Following is the syntax and parameters of Python Requests head() method −

requests.head()

Parameter

This function does not take any parameters.

Return value

This method returns the response object.

Example 1

Following is the basic example which sends a simple HEAD request to the specified URL and prints the status code and headers by using the python requests head() method −

import requests
response = requests.head('https://www.tutorialspoint.com/')
print(response.status_code)
print(response.headers) 

Output

403
{'Cache-Control': 'max-age=2592000', 'Content-Type': 'text/html; charset=iso-8859-1', 'Date': 'Mon, 24 Jun 2024 10:34:00 GMT', 'Expires': 'Wed, 24 Jul 2024 10:34:00 GMT', 'Server': 'Apache/2.4.59 (Ubuntu)', 'Strict-Transport-Security': 'max-age=63072000; includeSubDomains', 'X-Content-Type-Options': 'nosniff', 'X-Frame-Options': 'SAMEORIGIN', 'X-Version': 'OCT-10 V1', 'Transfer-Encoding': 'chunked', 'Connection': 'close'}

Example 2

If we want to send a HEAD request with parameters using the requests module in Python we can pass the parameters through the URL query string using the params parameter. Here this example includes URL parameters in the HEAD request −

import requests

# Define the URL
url = 'https://httpbin.org/headers'

# Define the parameters
params = {'param1': 'value1', 'param2': 'value2'}

# Send the HEAD request with parameters
response = requests.head(url, params=params)

# Print the response status code
print('Status Code:', response.status_code)

# Print the response headers
print('Response Headers:', response.headers)

Output

Status Code: 200
Response Headers: {'Date': 'Mon, 24 Jun 2024 10:39:18 GMT', 'Content-Type': 'application/json', 'Content-Length': '235', 'Connection': 'keep-alive', 'Server': 'gunicorn/19.9.0', 'Access-Control-Allow-Origin': '*', 'Access-Control-Allow-Credentials': 'true'}

Example 3

When sending a HEAD request using the requests module in Python it's important to handle potential errors that may occur during the request process. Here's an example of how to handle errors when making a HEAD request −

import requests

# Define the URL
url = 'https://httpbin.org/headers'

# Define the parameters
params = {'param1': 'value1', 'param2': 'value2'}

try:
    # Send the HEAD request with parameters
    response = requests.head(url, params=params)

    # Check if the request was successful (status code 2xx)
    if response.ok:
        # Print the response headers
        print('Response Headers:', response.headers)
    else:
        # Print an error message with the status code
        print('Error:', response.status_code)

except requests.Timeout:
    # Handle timeout error
    print('Timeout Error: Request timed out.')

except requests.RequestException as e:
    # Handle other request exceptions
    print('Request Exception:', e)

Output

Response Headers: {'Date': 'Mon, 24 Jun 2024 10:42:30 GMT', 'Content-Type': 'application/json', 'Content-Length': '235', 'Connection': 'keep-alive', 'Server': 'gunicorn/19.9.0', 'Access-Control-Allow-Origin': '*', 'Access-Control-Allow-Credentials': 'true'}