How to Set Timeout in cURL

cURL is a popular tool to download files & data from remote websites. It provides tons of useful options including downloads that require user authentication. You can even use cURL in shell scripts and cronjobs to automate file transfer. Any kind of file transfer requires the downloading tool to connect to remote server and transfer data in chunks. Sometimes there may be a lot of delays in this process, due to various reasons. It may be because cURL is unable to establish connection with remote server, the file transfer is too slow due to network issues, or the file download takes too much time due its size. In such cases, it is useful to specify a timeout value so that cURL automatically terminates the file transfer after a specified amount of time. Otherwise, cURL will continue to wait forever, which is undesirable. In this article, we will learn how to set timeout in cURL.

How to Set Timeout in cURL

cURL allows you to specify two kinds of timeouts – one for connection establishment and the other for the entire file transfer process.

1. Setting Connection Timeout

Sometimes cURL may be unable to connect to remote server to download files. This may be because of server issues or network related problems. Nevertheless, cURL will continue to wait for connection establishment for a long time, which is unnecessary. So you can specify timeout for connection process so that if cURL is unable to connect within the time limit, it will terminate the process on its own. You can do this using –connect-timeout option. Here is the syntax for it.

$ curl --connect-timeout <duration> <URL>

Here is a simple example to specify connection timeout of 5 seconds.

$ curl --connect-timeout 5 https://google.com

You can specify the connection timeout in seconds or milliseconds. By default, the duration mentioned is taken to be seconds. If you want to specify duration of 5 seconds and 25 milliseconds, then here is the command for it.

$ curl --connect-timeout 5.25 https://google.com

2. Setting Max Timeout

Alternatively, you can also set the maximum timeout value for cURL operation. It will set the max duration for whole operation that included connection establishment and data transfer. If you are transferring multiple files it will include duration for connection & download of all files and not just one file. In short, it sets the duration from start to end of command execution. Here is the syntax for it.

$ curl --max-time <duration> <url>

Here is an example to set max duration of 20 seconds to download a file.

$ curl --max-time 20 https://github.com/test_user/file.zip

In the above example, if the total time to connect to server and download file exceeds 20 seconds, the cURL command will be automatically terminated.

In this article, we have learnt how to set timeout in cURL. It is very useful to deal with unexpected delays in remote connection and file transfer. It also allows you to terminate cURL commands automatically, whether you run them manually from terminal, or from within a shell script.

How to Set Timeout in cURL