iperf3 is the go-to open-source tool for measuring real-world throughput, jitter, and packet loss between any two endpoints — from data-centre fabrics to home Wi-Fi links.
TCP · UDP · JSON output · Parallel streams · Linux · macOS · Windows
01 — What is iperf3?
iperf3 is a complete rewrite of the original iperf2, with a cleaner codebase, richer JSON output, and active maintenance. It operates in a client–server model: one host listens, the other connects and drives traffic.
If you only install one network diagnostic tool, make it iperf3 — bandwidth tests to jitter measurements in a single binary.
Key capabilities: measures TCP bandwidth and UDP jitter / packet loss, supports reverse mode, runs multiple parallel streams, outputs structured JSON, and works on Linux, macOS, Windows, and BSD.
02 — Installation
Debian / Ubuntu
sudo apt update && sudo apt install iperf3
RHEL / Fedora
# Fedora / RHEL 8+
sudo dnf install iperf3
# CentOS 7
sudo yum install iperf3
macOS
brew install iperf3
Windows
Download the pre-built binary from https://iperf.fr/iperf-download.php, extract, and run iperf3.exe from PowerShell or Command Prompt.
Verify
iperf3 --version
03 — Architecture
iperf3 uses a simple client–server model. One host listens, the other connects and drives the test.
┌──────────────────┐ ┌──────────────────┐
│ CLIENT │ ──── data flows ────► │ SERVER │
│ (initiates) │ ◄─── results / stats │ (listens) │
└──────────────────┘ └──────────────────┘
default port: 5201
| Role | Behaviour |
|---|---|
| Server | Listens on port 5201. Waits for a client. One client at a time by default. |
| Client | Connects to the server, negotiates test parameters, sends or receives data for the test duration. |
ℹ Port 5201 must be open in any firewall between the two hosts — both TCP and UDP if you plan to run UDP tests.
04 — Running the Server
Basic start
iperf3 -s
Server flags
| Flag | Description | Example |
|---|---|---|
| -s | Server mode | iperf3 -s |
| -p <port> | Custom listen port | iperf3 -s -p 9000 |
| -B <host> | Bind to a specific interface | iperf3 -s -B 192.168.1.10 |
| -D | Run as background daemon | iperf3 -s -D |
| -1 | Exit after one client | iperf3 -s -1 |
| --logfile <f> | Write output to file | iperf3 -s --logfile /var/log/iperf3.log |
| -J | JSON output | iperf3 -s -J |
Examples
# Listen on port 9000, log to file
iperf3 -s -p 9000 --logfile /tmp/iperf3_server.log
# Run as daemon
iperf3 -s -D
# Serve one test then exit
iperf3 -s -1
# Bind to a specific NIC
iperf3 -s -B 10.0.0.1
Firewall rules
# UFW
sudo ufw allow 5201/tcp
sudo ufw allow 5201/udp
# firewalld
sudo firewall-cmd --permanent --add-port=5201/tcp
sudo firewall-cmd --permanent --add-port=5201/udp
sudo firewall-cmd --reload
05 — Running the Client
Basic connection
iperf3 -c <server_ip>
Runs a 10-second TCP test and prints throughput results.
Client flags
| Flag | Description | Example |
|---|---|---|
| -c <host> | Client mode, connect to host | iperf3 -c 10.0.0.1 |
| -p <port> | Target server port | iperf3 -c 10.0.0.1 -p 9000 |
| -t <sec> | Test duration (default 10s) | iperf3 -c 10.0.0.1 -t 30 |
| -n <bytes> | Transmit fixed bytes | iperf3 -c 10.0.0.1 -n 1G |
| -P <n> | Parallel streams | iperf3 -c 10.0.0.1 -P 4 |
| -u | UDP mode | iperf3 -c 10.0.0.1 -u -b 100M |
| -b <bps> | Target bandwidth | iperf3 -c 10.0.0.1 -u -b 500M |
| -R | Reverse mode (server→client) | iperf3 -c 10.0.0.1 -R |
| --bidir | Simultaneous bidirectional | iperf3 -c 10.0.0.1 --bidir |
| -i <sec> | Report interval | iperf3 -c 10.0.0.1 -i 2 |
| -w <size> | TCP window / socket buffer | iperf3 -c 10.0.0.1 -w 512K |
| -J | JSON output | iperf3 -c 10.0.0.1 -J |
| -4 / -6 | Force IPv4 or IPv6 | iperf3 -c ::1 -6 |
| --dscp <val> | Set DSCP/TOS bits | iperf3 -c 10.0.0.1 --dscp 46 |
Examples
# 30-second TCP test
iperf3 -c 192.168.1.100 -t 30
# UDP at 500 Mbps for 20 seconds
iperf3 -c 192.168.1.100 -u -b 500M -t 20
# 4 parallel streams, 60s, JSON output
iperf3 -c 192.168.1.100 -P 4 -t 60 -J
# Reverse mode — measure download speed
iperf3 -c 192.168.1.100 -R -t 20
# Bidirectional test
iperf3 -c 192.168.1.100 --bidir -t 15
# Transmit exactly 10 GB
iperf3 -c 192.168.1.100 -n 10G
06 — TCP vs UDP
| TCP | UDP | |
|---|---|---|
| Primary metric | Throughput (Mbps / Gbps) | Jitter & packet loss |
| Bandwidth control | Auto — fills the pipe | Required with -b flag |
| Typical use case | File transfers, HTTP, bulk data | VoIP, video streaming, gaming |
| Key output fields | Bitrate, Retr, Cwnd | Bitrate, Jitter, Lost/Total |
⚠ For UDP tests, always set -b. Without it iperf3 defaults to 1 Mbps — far too low to stress most links.
07 — Reading the Output
TCP output
[ ID] Interval Transfer Bitrate Retr Cwnd
[ 5] 0.00-1.00 sec 1.10 GBytes 9.44 Gbits/sec 0 3.17 MBytes
[ 5] 0.00-10.00 sec 10.9 GBytes 9.36 Gbits/sec 0 sender
[ 5] 0.00-10.00 sec 10.9 GBytes 9.35 Gbits/sec receiver
| Field | Meaning |
|---|---|
| Interval | Time window for each report |
| Transfer | Data moved in the interval |
| Bitrate | Throughput in that interval |
| Retr | TCP retransmissions — high values indicate congestion or loss |
| Cwnd | TCP congestion window size |
| sender / receiver | Final summary row for each direction |
UDP output
[ ID] Interval Transfer Bitrate Jitter Lost/Total Datagrams
[ 5] 0.00-10.00 sec 119 MBytes 100 Mbits/sec 0.123 ms 12/86021 (0.014%)
Additional UDP fields: Jitter (ms) and Lost/Total with loss percentage.
JSON output
iperf3 -c 192.168.1.100 -J | python3 -m json.tool
08 — Advanced Usage
systemd service
Create /etc/systemd/system/iperf3.service:
[Unit]
Description=iperf3 server
After=network.target
[Service]
ExecStart=/usr/bin/iperf3 -s
Restart=always
[Install]
WantedBy=multi-user.target
sudo systemctl daemon-reload
sudo systemctl enable --now iperf3
Parse JSON in a script
#!/bin/bash
RESULT=$(iperf3 -c "$1" -J)
BPS=$(echo "$RESULT" | python3 -c \
"import json,sys; d=json.load(sys.stdin); print(d['end']['sum_received']['bits_per_second'])")
echo "Throughput: $BPS bps"
IPv6 testing
# Server
iperf3 -s -6
# Client
iperf3 -c ::1 -6 -t 10
09 — Troubleshooting
| Symptom | Cause & Fix |
|---|---|
| Connection refused | Server not running or port blocked — check firewall and confirm iperf3 -s is active |
| Very low / 0 throughput | Firewall dropping traffic — verify port 5201 is open for TCP and UDP |
| High Retr values | Network congestion or MTU mismatch — test jumbo frames with ping -s 9000 |
| server busy error | iperf3 handles one client at a time — wait, or restart the server |
| High UDP jitter | Check for packet loss; ensure -b matches the expected link speed |
| Permission denied | Ports below 1024 need root — use port 5201+ or run with sudo |
10 — Quick Reference
| Command | What it does |
|---|---|
| iperf3 -s | Start server on default port 5201 |
| iperf3 -s -p 9000 -D | Server on port 9000, background daemon |
| iperf3 -c <server> | Basic TCP test (10 seconds) |
| iperf3 -c <server> -t 30 -P 4 -J | TCP, 30s, 4 parallel streams, JSON output |
| iperf3 -c <server> -u -b 1G -t 20 | UDP test at 1 Gbps for 20 seconds |
| iperf3 -c <server> -R | Reverse mode — measure download speed |
| iperf3 -c <server> --bidir -t 15 | Simultaneous upload + download |
| iperf3 -c <server> -6 | Force IPv6 |
| iperf3 -c <server> -J > result.json | Save results to JSON file |
ℹ For the latest options, run
iperf3 --help or man iperf3.https://iperf.fr/iperf-servers.php