iperf3 Bandwidth Test

iperf3 cheatsheet — measure network bandwidth between two hosts. iperf3 -s (server), iperf3 -c host (client), iperf3 -u UDP, iperf3 -P parallel. Network speed testing.

5 min read

What it is

A command-line tool for measuring network bandwidth performance between two endpoints. Use it to diagnose network bottlenecks or verify throughput.

Installation

Linux

sudo apt update && sudo apt install iperf3  # Debian/Ubuntu
sudo yum install iperf3                    # CentOS/RHEL/Fedora

macOS

brew install iperf3

Windows

Download the pre-compiled binaries from the iperf3 releases page. Extract the zip file and run iperf3.exe from the command prompt or PowerShell.

Core Concepts

Client: The machine initiating the test and sending/receiving data.
Server: The machine listening for connections from the client and sending/receiving data.
TCP: The default protocol. Provides reliable, ordered delivery. Tests throughput.
UDP: Connectionless protocol. Tests packet loss and jitter in addition to throughput.

Commands / Usage

Setting up the Server

To start iperf3 in server mode, listening for incoming connections:

iperf3 -s

Starts iperf3 as a server, listening on the default port 5201.

iperf3 -s -p 5001

Starts iperf3 as a server, listening on port 5001 instead of the default.

iperf3 -s -D

Starts iperf3 as a server in daemon mode (runs in the background).

iperf3 -s -1

Starts iperf3 as a server and exits after the first client connects and finishes its test.

Running the Client (Testing Bandwidth)

To run iperf3 as a client and connect to a server:

iperf3 -c 192.168.1.100

Runs iperf3 as a client, connecting to the server at 192.168.1.100 using TCP for 10 seconds.

iperf3 -c 192.168.1.100 -p 5001

Runs iperf3 as a client, connecting to the server at 192.168.1.100 on port 5001.

iperf3 -c 192.168.1.100 -t 30

Runs the test for 30 seconds instead of the default 10.

iperf3 -c 192.168.1.100 -i 5

Reports statistics every 5 seconds during the test.

iperf3 -c 192.168.1.100 -f K

Displays bandwidth in Kilobits/sec (K). Other options: m (Megabits/sec), g (Gigabits/sec).

iperf3 -c 192.168.1.100 -R

Reverses the test mode. The client sends data to the server. Useful for testing upload speeds.

UDP Tests

To test UDP bandwidth, packet loss, and jitter:

iperf3 -c 192.168.1.100 -u

Runs a UDP test. By default, it sends UDP packets at a rate of 1 Mbit/sec.

iperf3 -c 192.168.1.100 -u -b 100M

Runs a UDP test, attempting to send at a rate of 100 Mbit/sec.

iperf3 -c 192.168.1.100 -u -b 100M -t 20

Runs a UDP test at 100 Mbit/sec for 20 seconds.

iperf3 -c 192.168.1.100 -u -b 100M -m

Runs a UDP test and includes jitter and packet loss in the report.

Advanced Client Options

iperf3 -c 192.168.1.100 --get-server-port

Asks the server for its listening port without starting a data transfer.

iperf3 -c 192.168.1.100 -P 4

Runs 4 parallel TCP streams. Useful for saturating higher bandwidth links.

iperf3 -c 192.168.1.100 --forceflush

Forces flushing of output buffers, useful in certain scripting scenarios.

iperf3 -c 192.168.1.100 -o output.txt

Writes the test output to the specified file.

iperf3 -c 192.168.1.100 -J

Outputs results in JSON format, suitable for programmatic parsing.

Server-Side Options

iperf3 -s --server-port 5001

An alternative way to specify the server port.

iperf3 -s --state-info

Prints state information about active client connections.

iperf3 -s --forcebind

Forces binding to the server address, even if it’s already in use (use with caution).

Common Patterns

Basic Server Setup and Client Test

On the server machine:
```
iperf3 -s
```
On the client machine:
```
iperf3 -c <server_ip_address>
```
- Replace <server_ip_address> with the actual IP of the server.

Testing Upload Speed

On the server machine:
```
iperf3 -s
```
On the client machine:
```
iperf3 -c <server_ip_address> -R
```
- The -R flag makes the client act as the sender.

Testing UDP Packet Loss and Jitter

On the server machine:
```
iperf3 -s
```
On the client machine:
```
iperf3 -c <server_ip_address> -u -b 100M -m
```
- -u for UDP, -b 100M to target 100 Mbps, -m for detailed jitter/loss.

Running Tests in Parallel

To better saturate high-bandwidth links, use multiple parallel streams:

On the server machine:
```
iperf3 -s
```
On the client machine:
```
iperf3 -c <server_ip_address> -P 8
```
- This runs 8 parallel TCP streams. Adjust -P as needed.

Saving Results to a File

iperf3 -c <server_ip_address> -o ~/iperf_results.txt

Saves the output of the client test to ~/iperf_results.txt.

Scripting with JSON Output

iperf3 -c <server_ip_address> -J > results.json

Runs the test and saves the results in JSON format to results.json for easy parsing by scripts.

Gotchas

Firewalls: Ensure that port 5201 (or the custom port you use) is open on the server’s firewall.
Client vs. Server: Remember to run iperf3 -s on one machine and iperf3 -c <server_ip> on the other. It’s a common mistake to run iperf3 -c on both.
NAT: If testing across different networks (e.g., Internet), Network Address Translation (NAT) can interfere. Ensure proper port forwarding if necessary.
UDP Rate: When using UDP (-u), the -b flag specifies the target bandwidth. The actual throughput might be lower due to network congestion or limitations. iperf3 will report the actual achieved rate and packet loss.
TCP Window Size: For very high-speed networks (10 Gbps+), the default TCP window size might become a bottleneck. iperf3 often auto-adjusts, but manual tuning might be required in specific scenarios (e.g., using iperf3 -window <size>).
Parallel Streams (-P): While useful, too many parallel streams can saturate the server’s CPU or the client’s network interface, leading to inaccurate results. Start with a few and increase cautiously.
Daemon Mode (-D): When running the server in daemon mode, remember that it will continue running in the background. You’ll need to find and kill the process manually if you want to stop it (e.g., pkill iperf3 on Linux/macOS).