Curl Close Connection Header Example

The command

curl -i --http1.1 -H "Connection: close" https://httpbin.org/get

What the flags do

Proving the connection was closed

Give one curl command two URLs on the same host and count connections. Normally the first transfer opens one and the second opens none, because it travels on the connection already there. Add the header and both transfers report a new connection. The write-out string is printed once per transfer, so the two numbers appear on separate lines.

# reused: prints 1, then 0
curl -s --http1.1 -o /dev/null -o /dev/null -w "new connections: %{num_connects}\n" \
  https://httpbin.org/get https://httpbin.org/headers

# closed each time: prints 1, then 1
curl -s --http1.1 -o /dev/null -o /dev/null -w "new connections: %{num_connects}\n" \
  -H "Connection: close" https://httpbin.org/get https://httpbin.org/headers

When the header matters

Each curl process begins with no open connections, so a shell loop that starts curl again and again gets a fresh one every time regardless. There the header only lets the server release its socket at once instead of waiting for an idle timer. It earns its place when a single command makes many requests: a URL range, several URLs, or --parallel.

That makes it a way to reproduce what a client without connection pooling would do. Two uses are common: watching how a load balancer spreads brand-new connections, and ruling out the intermittent "empty reply" errors that happen when a server drops an idle connection just as the client reuses it.

# five requests in one process, each on its own connection
curl -s --http1.1 -H "Connection: close" -o /dev/null \
  -w "%{remote_ip} connect=%{time_connect}s\n" "https://httpbin.org/get?n=[1-5]"

Proxies, servers and HTTP/2

The header is hop-by-hop: it governs only the link between you and the next machine. Behind a CDN or reverse proxy, your connection to the proxy closes while the proxy's pooled connection to the origin carries on, and the origin never learns you asked. Servers send the header on their own initiative too, after a set number of requests or during a shutdown, and curl obeys by opening a new connection for the next URL.

HTTP/2 and HTTP/3 manage connections inside the protocol, and the header has no meaning there. Verbose output may still list it among the request lines, so do not take that as proof it had an effect; force --http1.1 and look for the server's own reply.

curl -v --http1.1 -o /dev/null -H "Connection: close" https://httpbin.org/get 2>&1 \
  | grep -i -E "^< connection|closing connection"

Common mistakes

• It is not a timeout. The header ends the connection after a response; it does nothing about a response that never arrives. Use --max-time for that.
• Closing every connection is slow at volume. Each request repeats the TCP and TLS handshakes, which often cost more than the request itself.
• A proxy may answer on the server's behalf. Seeing the header echoed back tells you about the nearest hop only.

Related curl examples

More under Headers

• Curl Content-Type Example
• Curl User Agent Example
• Curl Send Cookies Example
• Curl No Cache Example
• Curl Custom Headers Example

References

• curl man page: -H — Adding the Connection request header.
• MDN: Connection — The hop-by-hop header and why HTTP/2 forbids it.

These links leave api-tester.com, which is independent of the projects they point to.

FAQ