Version: iperf 3.x (not backward-compatible with iperf 2.x)
Purpose: Network bandwidth measurement — TCP, UDP, SCTP
Model: Client → Server (server must be running first)
Default port: 5201 (iperf3) / 5001 (iperf2)
Quick Start
# Server
iperf3 -s
# Client (basic TCP test)
iperf3 -c <server_ip>
# UDP test
iperf3 -c <server_ip> -u
# Reverse mode (server sends, client receives)
iperf3 -c <server_ip> -R
# Bidirectional
iperf3 -c <server_ip> --bidir
Server Options
| Short | Long | Default | Description |
|---|
-s | --server | — | Run in server mode |
-D | --daemon | off | Run as daemon |
-I | --pidfile=FILE | — | Write PID to file |
-1 | --one-off | off | Handle one client, then exit |
-p | --port=N | 5201 | Listen on port N |
-B | --bind=ADDR | all | Bind to specific IP/interface |
| --idle-timeout=N | — | Seconds idle before server exits |
Client Options
Connection
| Short | Long | Default | Description |
|---|
-c | --client=HOST | — | Connect to HOST |
-p | --port=N | 5201 | Server port |
-B | --bind=ADDR | auto | Bind to local IP |
| --cport=N | auto | Bind to local port |
| --connect-timeout=MS | — | Connection timeout (ms) |
-4 | --version4 | — | Force IPv4 |
-6 | --version6 | — | Force IPv6 |
-S | --tos=N | 0 | Set IP TOS / DSCP field |
Test Parameters
| Short | Long | Default | Description |
|---|
-t | --time=N | 10 | Duration in seconds |
-n | --bytes=N | — | Bytes to transmit (overrides -t) |
-k | --blockcount=N | — | Blocks to transmit (overrides -t, -n) |
-l | --length=N | 128K (TCP) / 1460 (UDP) | Read/write buffer length |
-P | --parallel=N | 1 | Number of parallel streams |
-R | --reverse | off | Reverse mode (server → client) |
| --bidir | off | Bidirectional test |
-w | --window=N | auto | TCP window / socket buffer size |
-M | --set-mss=N | auto | Set TCP maximum segment size |
-N | --no-delay | off | Disable Nagle (low-latency) |
-i | --interval=N | 1 | Report interval (seconds, 0 = disable) |
Protocol
| Short | Long | Description |
|---|
| (default) | TCP test |
-u | --udp | UDP test |
| --sctp | SCTP test |
Bandwidth Control
| Short | Long | Default | Description |
|---|
-b | --bitrate=N[KMG] | 0 (TCP) / 1M (UDP) | Target bitrate |
| --pacing-timer=N | 1000 µs | Pacing timer for -b |
| --fq-rate=N[KMG] | 0 | Fair-queue rate (Linux) |
Suffixes: K = Kbits/s · M = Mbits/s · G = Gbits/s. Append / for bytes: 10M/ = 10 MB/s
Output Control
| Short | Long | Default | Description |
|---|
-f | --format=[kmgtKMGT] | auto | k/m/g/t (bits) · K/M/G/T (bytes) |
-V | --verbose | off | Detailed output |
-J | --json | off | JSON output |
| --logfile=FILE | — | Log to file |
| --timestamps[=FMT] | off | Add timestamps |
| --get-server-output | off | Include server-side results |
Advanced
| Short | Long | Default | Description |
|---|
-Z | --zerocopy | off | Zero-copy (sendfile) — reduces CPU |
-O | --omit=N | 0 | Omit first N seconds (TCP warmup) |
-T | --title=STR | — | Prefix output with title |
-C | --congestion=ALGO | system default | TCP congestion algorithm |
-A | --affinity=N | — | Set CPU affinity |
UDP-Specific Metrics
| Metric | Description |
|---|
| Bitrate | Actual throughput |
| Jitter | Packet delay variation (ms) |
| Lost/Total | Packets lost vs. sent |
| Loss % | Packet loss percentage |
| Out-of-Order | Packets received out of order |
Output Columns
| Column | Description |
|---|
Interval | Time window |
Transfer | Data transferred |
Bitrate | Throughput |
Retr | TCP retransmissions |
Cwnd | TCP congestion window size |
Jitter | Packet delay variation (UDP) |
Lost/Total | Packet loss (UDP) |
JSON Output
iperf3 -c server -J | jq '.end.sum_sent.bits_per_second'
| Path | Description |
|---|
.start.connected[0] | Connection info |
.intervals[N].sum | Per-interval summary |
.end.sum_sent | Total sender stats |
.end.sum_received | Total receiver stats |
.end.cpu_utilization_percent | CPU usage |
.end.sender_tcp_congestion | Congestion algorithm |
TCP Congestion Algorithms (-C)
| Algorithm | Description |
|---|
cubic | Default on Linux — good for most networks |
bbr | Google BBR — optimized for high BDP paths |
reno | Classic loss-based |
htcp | High-speed variant |
vegas | Delay-based |
dctcp | Data Center TCP (ECN-based) |
List available: sysctl net.ipv4.tcp_available_congestion_control
Common Recipes
# === Basic Tests ===
# TCP throughput (10s default)
iperf3 -c server
# TCP 60s, omit 5s warmup
iperf3 -c server -t 60 -O 5
# UDP at 500 Mbps
iperf3 -c server -u -b 500M
# UDP jitter/loss at 10 Mbps for 30s
iperf3 -c server -u -b 10M -t 30
# === Parallel & Bidirectional ===
# 4 parallel streams (saturate link)
iperf3 -c server -P 4
# Bidirectional simultaneous
iperf3 -c server --bidir
# Reverse (measure download)
iperf3 -c server -R
# === Window & Buffer Tuning ===
# TCP window 4MB (high-latency path)
iperf3 -c server -w 4M
# Jumbo frame MSS
iperf3 -c server -M 8960
# === Performance ===
# Zero-copy (reduce CPU)
iperf3 -c server -Z
# Set CPU affinity
iperf3 -c server -A 0
# Compare congestion algorithms
iperf3 -c server -C cubic -t 30 -T "CUBIC"
iperf3 -c server -C bbr -t 30 -T "BBR"
# === Specific Scenarios ===
# Verify Gigabit link (~940 Mbps)
iperf3 -c server -t 30 -P 4 -O 3
# Test 10G link
iperf3 -c server -P 8 -Z -t 30 -O 5
# Test WiFi download
iperf3 -c server -R -t 30
# Test VPN throughput
iperf3 -c vpn-server -t 60 -P 2 -O 5
# Test jumbo frames (MTU 9000)
iperf3 -c server -u -b 1G -l 8972
# Simulate WAN bandwidth
iperf3 -c server -b 50M -t 30
# === Output ===
# JSON output
iperf3 -c server -J > results.json
# JSON + server output
iperf3 -c server -J --get-server-output > results.json
# Format as Megabytes
iperf3 -c server -f M
# Log to file
iperf3 -c server --logfile /tmp/iperf.log
# Quick health check (JSON, extract Mbps)
iperf3 -c server -t 5 -J | jq '.end.sum_received.bits_per_second / 1000000 | round'
# === Multiple Ports (parallel server instances) ===
iperf3 -s -p 5201 &
iperf3 -s -p 5202 &
iperf3 -s -p 5203 &
iperf3 vs iperf2
| Feature | iperf3 | iperf2 |
|---|
| Default port | 5201 | 5001 |
| JSON output | Yes (-J) | No |
| Bidirectional | Yes (--bidir) | Yes (-d) |
| Reverse | Yes (-R) | No |
| Multi-client server | No (single client) | Yes |
| SCTP | Yes | No |
| Zero-copy | Yes (-Z) | No |
| Congestion algo | Yes (-C) | No |
| Multicast | No | Yes |
| Omit warmup | Yes (-O) | No |
| Protocol compatible | No | No |
Key: iperf3 handles one client at a time. For concurrent tests, run multiple server instances on different ports.
Troubleshooting
| Symptom | Cause | Fix |
|---|
unable to connect | Server not running / firewall | Check process, open port 5201 |
| Very low TCP throughput | Small window / high RTT | Increase -w window |
| High retransmissions | Congestion / packet loss | Check cable/switch, try -C bbr |
| UDP loss > 1% | Exceeds link capacity | Reduce -b bitrate |
busy error | Another client connected | Wait or use different -p port |
| CPU-bound | Software overhead | Use -Z zero-copy, -A affinity |
| Inconsistent results | TCP warmup | Use -O 3 to omit warmup |
Firewall Rules
# Linux (firewalld)
firewall-cmd --add-port=5201/tcp --permanent
firewall-cmd --add-port=5201/udp --permanent
firewall-cmd --reload
# Windows
netsh advfirewall firewall add rule name="iperf3" dir=in action=allow protocol=tcp localport=5201
netsh advfirewall firewall add rule name="iperf3-udp" dir=in action=allow protocol=udp localport=5201
Size Suffixes
| Suffix | Meaning (bitrate -b) | Meaning (size -w, -l, -n) |
|---|
K | Kbits/s (1000) | KBytes (1024) |
M | Mbits/s (1000²) | MBytes (1024²) |
G | Gbits/s (1000³) | GBytes (1024³) |
Append / to -b for bytes: -b 10M/ = 10 MB/s = 80 Mbps
Source: man iperf3(1) · iperf.fr · github.com/esnet/iperf