iPerf3 is the standard tool for answering one of the most common questions in networking: how much throughput can this path actually deliver? Speed test sites measure your path to someone else's server. iPerf3 measures the exact path you care about, between two machines you control. Every capture in this guide comes from a live Cisco Modeling Labs topology - a Linux client, two IOS XE routers running OSPF, and an iperf3 server - so the numbers you see are what the tool really prints. This article is part of our complete iPerf guide.
How iPerf3 Works
iPerf3 uses a client-server model. One machine runs as the server and listens on TCP port 5201. The other runs as the client, connects, and pushes as much traffic as it can (TCP) or exactly as much as you tell it to (UDP) for 10 seconds by default. Both sides then report what was sent and what actually arrived.
That last distinction matters. The sender reports what it handed to the network. The receiver reports what survived the trip. On a healthy path the two numbers are nearly identical; when they diverge, the network is dropping or delaying traffic in between (that gap is your first troubleshooting clue).
Step 1: Install iPerf3
On Debian and Ubuntu:
sudo apt install iperf3On Red Hat family systems use dnf install iperf3, on macOS brew install iperf3, and on Windows grab the binary and run it from a terminal. Version parity matters less than it used to, but keep both ends on iperf 3.x - iPerf3 does not interoperate with iPerf2 (see iPerf2 vs iPerf3 for why they are separate tools).
Step 2: Start the Server
iperf3 -sThat is the whole job. The server binds to port 5201 on all interfaces and waits:
-----------------------------------------------------------
Server listening on 5201 (test #1)
-----------------------------------------------------------An iPerf3 server handles exactly one test at a time. A second client connecting mid-test gets refused (we cover daemon mode, custom ports, and that busy error in running an iPerf3 server).
Step 3: Run the Client
From the other machine, point -c at the server's IP. Here is a real run from our lab client (10.0.10.10) to the server (10.0.20.10), crossing two routed hops:
client:~$ iperf3 -c 10.0.20.10
Connecting to host 10.0.20.10, port 5201
[ 5] local 10.0.10.10 port 39290 connected to 10.0.20.10 port 5201
[ ID] Interval Transfer Bitrate Retr Cwnd
[ 5] 0.00-1.00 sec 4.12 MBytes 34.6 Mbits/sec 7 72.1 KBytes
[ 5] 1.00-2.00 sec 4.00 MBytes 33.6 Mbits/sec 6 59.4 KBytes
[ 5] 2.00-3.00 sec 4.25 MBytes 35.6 Mbits/sec 12 43.8 KBytes
[ 5] 5.00-6.00 sec 4.38 MBytes 36.7 Mbits/sec 0 93.3 KBytes
[ 5] 9.00-10.01 sec 4.00 MBytes 33.3 Mbits/sec 10 39.6 KBytes
- - - - - - - - - - - - - - - - - - - - - - - - -
[ ID] Interval Transfer Bitrate Retr
[ 5] 0.00-10.01 sec 41.2 MBytes 34.6 Mbits/sec 83 sender
[ 5] 0.00-10.01 sec 40.9 MBytes 34.2 Mbits/sec receiver
Reading the Output
One line per second by default. Transfer is data moved in that interval; Bitrate is the rate. The final sender and receiver lines are the numbers to quote.
TCP segments resent because they were lost or reordered. 83 retransmits over 10 seconds here tells us the path drops some packets under load. Zero is ideal; a climbing count means congestion or loss.
How much unacknowledged data TCP is willing to keep in flight. Watch it grow, then get cut when loss occurs (43.8 KBytes right after those 12 retransmits). This is TCP congestion control working in real time.
Sender = handed to the network (41.2 MB). Receiver = actually delivered (40.9 MB). The receiver line is the truth about the path.
The Flags You Will Actually Use
-t 30Run for 30 seconds instead of 10. Longer tests smooth out TCP slow start and give steadier numbers.-RReverse mode: the server sends, the client receives. Tests the download direction without touching the far machine.-u -b 50MUDP at a fixed 50 Mbit/sec, reporting jitter and loss. See iPerf3 UDP testing.-P 4Four parallel streams. Often reveals per-flow limits; see parallel streams and window size.-i 5Report every 5 seconds instead of every 1. Less noise on long tests.-f MPrint MBytes/sec instead of Mbits/sec (capital M = bytes, lowercase m = bits).-p 5202Use a different port. The server must be started with the same -p.-JJSON output for scripts and monitoring pipelines.Testing the Other Direction with -R
By default the client sends. Add -R and the server sends instead, which is how you test download speed from the client's point of view:
client:~$ iperf3 -c 10.0.20.10 -R
Reverse mode, remote host 10.0.20.10 is sending
[ ID] Interval Transfer Bitrate
[ 5] 0.00-1.00 sec 3.75 MBytes 31.4 Mbits/sec
[ 5] 4.00-5.00 sec 4.00 MBytes 33.6 Mbits/sec
- - - - - - - - - - - - - - - - - - - - - - - - -
[ 5] 0.00-10.02 sec 39.1 MBytes 32.8 Mbits/sec 83 sender
[ 5] 0.00-10.00 sec 38.8 MBytes 32.5 Mbits/sec receiver
Run both directions before drawing conclusions. Asymmetric results are common (policing on one direction, duplex issues, asymmetric routing) and testing only one way hides half the story.
JSON Output for Automation
Add -J and iPerf3 emits the entire test as structured JSON, ideal for feeding monitoring systems or CI checks:
client:~$ iperf3 -c 10.0.20.10 -J
{
"start": {
"version": "iperf 3.18",
"tcp_mss_default": 1448,
...
"intervals": [{
"streams": [{
"bytes": 4325376,
"bits_per_second": 34566124.48,
"retransmits": 9,
"snd_cwnd": 53576,
Pipe it to jq '.end.sum_received.bits_per_second' and you have a one-line throughput check you can alert on.
A Sensible First Test, Step by Step
- Confirm reachability first:
ping -c 3 10.0.20.10. Note the round-trip time; you will want it later if throughput looks low. - Start the server:
iperf3 -son the far machine. - Run 30 seconds of TCP:
iperf3 -c 10.0.20.10 -t 30. - Run the reverse direction: add
-R. - If numbers disappoint, do not guess. Follow the method in troubleshooting slow throughput with iPerf3.
Key Takeaways
iPerf3 is a two-command tool: iperf3 -s on one end, iperf3 -c <server> on the other. Trust the receiver-side summary line, not the sender's. Retr and Cwnd are not decoration - they tell you whether TCP is hitting loss and how much data it dares keep in flight. Always test both directions, and reach for -J the moment you want to script it. For the full picture of what iPerf can do (UDP, parallel streams, version differences, server hardening), start at the iPerf complete guide.
