iperf3: Usage, Options & Common CI Errors

iperf3 measures TCP/UDP throughput between a client and a server.

iperf3 benchmarks the network path between two endpoints. It is strictly client/server: one side runs -s, the other -c, and iperf3 is notoriously incompatible with the older iperf2.

What it does

iperf3 runs a server (-s) on one host and a client (-c) on another to measure achievable TCP or UDP throughput, jitter, and loss. It reports per-interval and summary bandwidth between the two.

Common usage

Terminal

iperf3 -s                                      # server side
iperf3 -c server.host                          # client side
iperf3 -c server.host -t 30 -P 4               # 30s, 4 parallel streams
iperf3 -c server.host -u -b 100M               # UDP at 100 Mbit/s
iperf3 -c server.host -R                        # reverse (download) test

Options

Flag	What it does
-s / -c <host>	Run as server / connect as client
-t <secs>	Test duration (client)
-P <N>	Number of parallel streams
-u -b <rate>	UDP mode at a target bitrate
-R	Reverse: server sends to client
-p <port>	Use a non-default port (default 5201)

Common errors in CI

"iperf3: error - unable to connect to server: Connection refused" means no -s server is listening (start it first, or the port/host is wrong). "the server is busy running a test. try again later" - iperf3 serves one client at a time by default; use -p with multiple servers or serialize. iperf3 is NOT wire-compatible with iperf2: pointing iperf3 -c at an iperf2 server gives "received an unknown control message". Firewalls/security groups blocking 5201 surface as a connect timeout.