How to Use Iperf for Accurate Throughput MeasurementAccurate throughput measurement is essential for network troubleshooting, capacity planning, and performance verification. Iperf (and its actively maintained fork Iperf3) is one of the most popular tools for measuring network throughput because it is lightweight, flexible, and cross-platform. This article walks through why Iperf is useful, how it works, how to run precise tests, interpret results, and avoid common pitfalls. It also includes examples and recommended test methodologies to produce reliable, repeatable measurements.
What Iperf measures and when to use it
Iperf measures the maximum achievable bandwidth between two endpoints by generating traffic across a network connection and reporting throughput, jitter, packet loss (UDP), and other metrics. Use Iperf when you need to:
- Verify link capacity and performance.
- Compare baseline performance before/after changes.
- Troubleshoot throughput bottlenecks.
- Validate service-level agreements (SLAs).
- Test TCP vs UDP behavior and application-like traffic patterns.
Note: Iperf measures achievable raw throughput under the conditions you create; it does not simulate application-layer behavior unless you design tests to mimic that behavior.
Iperf vs Iperf3
Iperf3 is a rewrite with a cleaner codebase and JSON output support; it’s recommended for new deployments. While Iperf2 still exists and is used in some environments, Iperf3 provides easier parsing, better stability, and improved features. Throughout this article, examples use Iperf3; where commands differ, that will be noted.
Basic concepts and terminology
- Throughput: The amount of data successfully transferred per unit time (usually Mbps or Gbps).
- Bandwidth: The maximum data rate a link can carry (often used interchangeably with throughput).
- Latency: The time it takes a packet to travel from source to destination (affects certain TCP behaviors).
- Jitter: Variation in packet latency (important for real-time traffic; reported by UDP tests).
- Packet loss: Percentage of packets lost during transmission (critical for UDP and real-time apps).
- Client / Server: Iperf requires one machine running in server mode and another in client mode to generate/measure traffic.
Installing Iperf3
Iperf3 is available on Linux, macOS, and Windows.
Examples:
-
Debian/Ubuntu:
sudo apt update sudo apt install iperf3
-
CentOS/RHEL (use EPEL):
sudo yum install epel-release sudo yum install iperf3
-
macOS (Homebrew):
brew install iperf3
-
Windows: download prebuilt binaries from the project’s releases page or install via package managers like Chocolatey:
choco install iperf3
Basic usage
-
Start the server on one host:
iperf3 -s
-
Run a client from another host to connect to that server:
iperf3 -c <server-ip>
Default test is TCP, runs for 10 seconds, and reports throughput in bits/sec.
Producing accurate, repeatable measurements
Accurate throughput testing requires controlling variables and running multiple iterations. Follow these steps:
- Use a dedicated test environment when possible. Avoid running tests across busy production paths that introduce unrelated variability.
- Ensure both endpoints have sufficient CPU, memory, and NIC capacity. Monitor CPU utilization and interrupts during tests.
- Disable or account for firewall, intrusion detection, or traffic-shaping rules that may throttle or interfere.
- Use the same test conditions across runs (same packet size, duration, parallel streams, etc.).
- Run multiple repetitions and take the median or mean after discarding outliers.
Key command-line options for accurate tests
- -t, –time: set test duration in seconds (e.g., -t 60).
- -P, –parallel: number of parallel client streams (e.g., -P 4). Useful to saturate high-bandwidth links when a single TCP stream is limited by TCP windowing.
- -b, –bandwidth: for UDP tests set target bandwidth (e.g., -b 1G).
- -w, –window: set TCP window size (e.g., -w 512K) — affects achievable throughput across high-latency links.
- -u: run UDP test (measures packet loss, jitter, and achievable UDP rate).
- -R: reverse test direction (client receives, server sends).
- -J: output JSON (useful for scripting and consistent parsing).
- -f, –format: choose output units (K, M, G).
Example: 60-second TCP test with 4 parallel streams and a 512 KB socket buffer:
iperf3 -c <server-ip> -t 60 -P 4 -w 512K -f m
TCP vs UDP testing
- TCP tests show the achievable throughput using TCP’s congestion control; results depend on RTT, window size, and congestion.
- UDP tests let you specify a target bitrate and report packet loss and jitter, which is useful for real-time applications (VoIP, video).
UDP example sending 500 Mbps for 30s:
iperf3 -c <server-ip> -u -b 500M -t 30
Interpret UDP results by checking the sender-reported throughput, receiver-reported throughput, packet loss percentage, and jitter.
Handling high-bandwidth or high-latency links
- Increase test duration (e.g., 60s or more) to capture steady-state throughput.
- Use multiple parallel streams (-P) to overcome single-TCP-stream limits.
- Raise socket buffer size (-w) and adjust TCP congestion algorithm if needed.
- For very high rates, run iperf3 on machines with NICs/CPUs that can handle line-rate and ensure OS settings (e.g., large receive offload, interrupt coalescing) are tuned appropriately.
Example workflows
-
Baseline single-stream TCP test:
iperf3 -c 10.0.0.2 -t 30
-
Find max TCP throughput using parallel streams:
iperf3 -c 10.0.0.2 -t 60 -P 8 -w 1M
-
Measure UDP packet loss and jitter for real-time traffic:
iperf3 -c 10.0.0.2 -u -b 200M -t 30 -f m
-
Automated script-friendly run with JSON:
iperf3 -c 10.0.0.2 -t 30 -J > results.json
Interpreting results
- Look at reported transmit and receive throughput averages. Small differences can indicate measurement noise.
- For TCP, sustained throughput close to link capacity indicates healthy performance. If far below, check window sizes, latency, CPU, NIC offloads, and intermediate device shaping.
- For UDP, focus on packet loss and jitter as well as achieved Mbps. Any significant packet loss (>1–2%) can severely impact real-time apps.
- Use the JSON output to extract metrics programmatically and compare runs.
Common pitfalls and how to avoid them
- CPU or NIC saturation on endpoints: monitor host resources and offload settings.
- Single TCP stream limitations: use parallel streams or tune window size.
- Asymmetric paths or routing changes: ensure the return path is equivalent to the forward path.
- Inconsistent test conditions: standardize duration, stream count, and time of day.
- Interference from background traffic: test in controlled windows or isolate test VLANs.
Example troubleshooting checklist
- Confirm connectivity and appropriate MTU between endpoints.
- Run ping and traceroute to check latency and path.
- Verify no shaping/QoS is limiting test traffic.
- Check server and client CPU/memory and NIC statistics during tests.
- Adjust -w and -P parameters and re-run to see improvements.
Advanced topics
- Use iperf3’s JSON output for continuous integration and automated performance regression testing.
- Combine iperf3 with tc (Linux traffic control) to emulate shaped or latency-prone networks.
- Use packet captures (tcpdump/Wireshark) to analyze retransmissions, out-of-order packets, and TCP behavior during tests.
Summary
Iperf3 is a versatile and reliable tool for measuring network throughput when used thoughtfully. Control your environment, choose appropriate options (duration, parallel streams, window size), and run multiple trials to produce accurate and repeatable measurements. For UDP-sensitive applications, monitor jitter and packet loss as primary indicators of real-world performance.