How to set a Netcat connection timeout on Linux

Slow TCP probes and quiet sessions can stall shell scripts. OpenBSD nc on Linux lets you set Netcat connection and idle timeouts so control returns after a chosen interval. These timeouts do not limit how long a listener waits for its first incoming connection.

OpenBSD nc uses -w for connection attempts that cannot complete and for established sessions that stop reading or writing. Pair it with -zv when the job is only to test whether a TCP port accepts a connection, or use it without -z when a real session should close after being idle.

The examples below use netcat-openbsd on Ubuntu 26.04. Nmap Ncat also accepts -w for connect timeout, but its idle timeout is --idle-timeout or -i, so confirm the implementation before copying the same command into automation.

1. Confirm that the installed nc command reports OpenBSD netcat.

   $ nc -h
   OpenBSD netcat (Debian patchlevel 1.234-1)
   usage: nc [-46CDdFhklNnrStUuvZz] [-I length] [-i interval] [-M ttl]
   	  [-m minttl] [-O length] [-P proxy_username] [-p source_port]
   	  [-q seconds] [-s sourceaddr] [-T keyword] [-V rtable] [-W recvlimit]
   	  [-w timeout] [-X proxy_protocol] [-x proxy_address[:port]]
   	  [destination] [port]
   ##### snipped #####
   		-w timeout	Timeout for connects and final net reads

   Ncat also lists -w, so the flag alone does not identify the implementation. The remaining examples apply unchanged only when the first line names OpenBSD netcat.

2. Set a two-second timeout on a connection to a host and port that do not answer.

   $ nc -vz -w 2 192.0.2.10 443
   nc: connect to 192.0.2.10 port 443 (tcp) timed out: Operation now in progress

   192.0.2.10 and 443 stand in for your own host and port, and that address is reserved for documentation. A target that silently drops the attempt shows this message after about two seconds. A port that accepts the connection prints succeeded!, and a closed port is refused at once, so neither one waits for -w.

3. Start a quiet local listener in a second terminal.

   $ nc -lk 127.0.0.1 8080

   OpenBSD nc ignores -w with -l, so nc -l -w 3 127.0.0.1 8080 can still wait forever for the first incoming connection. Use a separate process supervisor or shell-level timeout when listener lifetime must be capped.

   Related: How to create a TCP listener with Netcat
   Related: How to keep a Netcat listener open for multiple connections

4. Check that a port accepting connections succeeds with the same timeout.

   $ nc -vz -w 2 127.0.0.1 8080
   Connection to 127.0.0.1 8080 port [tcp/http-alt] succeeded!

   -z opens no data stream, while -v prints the connection result. A timed-out or refused connection exits nonzero, so scripts can branch on the exit status.

   Related: How to test a TCP port with Netcat

5. Connect to the quiet listener with a three-second idle timeout.

   $ nc -v -w 3 127.0.0.1 8080
   Connection to 127.0.0.1 8080 port [tcp/http-alt] succeeded!

   nc reports the connection, then exits by itself and returns to the prompt after about three idle seconds.

6. Stop the temporary listener in the second terminal with Ctrl-C.