iperf3: measuring real TCP, UDP and SCTP bandwidth between two hosts

What iperf3 measures, and who actually needs it

iperf3 answers a narrow question: how much bandwidth can two IP endpoints push between each other right now, with the parameters you choose. The README describes it as a tool for "active measurement of the maximum achievable bandwidth on IP networks", with tuning of timing, protocols and buffers, and per-test reporting of throughput, loss and other parameters. That is different from asking whether a link is up. A ping tells you reachability and latency; iperf3 tells you what a TCP stream or a UDP flow actually achieves across the path.

The intended audience is network engineers and researchers. The README states that one of the primary uses is as a component of the perfSONAR network measurement system, and that it is used standalone by ESnet and other R&E networks. It has also been adopted in the broader networking community and inside commercial products. If you are debugging a WAN circuit, validating a new switch, or checking whether a wireless link delivers what the vendor promised, you are the target user. If you just want to know whether your home internet is fast, a browser speed test is simpler and tests a different thing.

Client, server, and control channel: how an iperf3 test is structured

An iperf3 run has two processes. One side runs as a server and listens; the other runs as a client and connects to it. The client drives the test parameters, and the server reports its own view of the results back over the same connection. This is why you cannot test against an arbitrary host: the far end must be running iperf3, or something that speaks its protocol.

The protocol choice matters for what the numbers mean. TCP tests measure what a congestion-controlled stream achieves, which is what most applications experience. UDP tests send at a rate you specify and report loss and jitter, which is closer to what a real-time media flow sees. SCTP is also supported. The README notes that iperf3 supports tuning of parameters related to timing, protocols and buffers, and that the manual page is the most up-to-date reference for the flags. Treat the man page as the source of truth; the README is a summary.

One design decision is worth calling out. The README says that with default options, iperf is meant to show "typical well designed application performance", and explains this as avoiding artificial enhancements that work only for testing, such as splice()'ing data to /dev/null. Flags for extreme best-case optimizations exist but must be explicitly enabled, including -Z for a zero-copy sendfile() method and -A for CPU affinity. That is a defensible default: a number produced with zero-copy and pinned CPUs is not the number your application will see.

Installing iperf3 and running a first test

The README lists no prerequisites for building. The documented build sequence is a standard autotools flow, and the README notes that if configure fails you should try running ./bootstrap.sh first.

./configure; make; make install

If you would rather not build from source, the README points to binary downloads at https://downloads.es.net/pub/iperf/, and the source is at https://github.com/esnet/iperf.git. Distribution packages are not described in the README, so check your platform's package manager separately rather than assuming a version.

Start the server on the machine that will receive traffic. The README does not give a literal server invocation, but it documents that iperf3 includes a manual page listing all of the command-line options, and that the manual page is the most up-to-date reference to the various flags and parameters. Read it before you type anything, because the README does not enumerate the flags itself.

For sample command line usage, the README points to https://fasterdata.es.net/performance-testing/network-troubleshooting-tools/iperf/. That page, not the README, is where the concrete client and server invocations live.

For machine-readable output, the README mentions optional JSON output as one of the features iperf3 added relative to the original iperf. The exact flag is documented in the manual page. Read it before scripting anything.

Where iperf3 gives you a misleading number

The biggest failure mode is not a bug, it is interpretation. A single TCP stream between two hosts is limited by congestion control and by the receiver's window, so a result that looks low may say nothing about the link's capacity. Testing with parallel streams is the usual way to separate the two, but the README does not walk through that reasoning; it points to a fasterdata.es.net troubleshooting page for sample usage. If you report a single-stream number as "the link speed", you are likely wrong.

Version mismatch is a second trap. The README states plainly that iperf3 is not backwards compatible with the original iperf, and that iperf2 and iperf3, while both measuring network performance, are not compatible with each other and are in separate development. A client and server that are not both iperf3 will not interoperate. The README also says the projects are in active, but separate, development as of early 2026, so "iperf" in a package name does not tell you which one you installed.

Platform support is narrower than the download page suggests. Primary development takes place on Ubuntu Linux, FreeBSD and macOS, and the README calls these the only officially supported platforms. OpenBSD, NetBSD, Android, Solaris and other Linux distributions have been reported to work, but that is a report, not a support commitment. If you hit a problem on an unsupported platform, the README's bug-report guidance asks for version and platform details and notes the developers might be able to help anyway.

How iperf3 differs from netperf and nuttcp

The README names nuttcp and netperf directly, saying iperf3 has features found in those tools that were missing from the original iperf, and gives zero-copy mode and optional JSON output as examples. That is the honest comparison point: these are peers, not alternatives in a different category.

The practical difference is packaging and ecosystem. iperf3 is developed by ESnet and Lawrence Berkeley National Laboratory and is a component of perfSONAR, which matters if you are already inside a research network measurement deployment. If your environment standardizes on netperf or nuttcp, switching buys you JSON output and a smaller code base, and the README describes iperf3 as a rewrite from scratch with the goal of a smaller, simpler code base and a library version usable by other programs. That library angle is the real differentiator: if you want to embed bandwidth measurement in your own program rather than shell out to a binary, iperf3 was designed with that in mind. The README does not document the library API, so you would need to read the source and the manual page.

Licence, maintenance and the cost of upgrading

The README states that iperf3 is released under a three-clause BSD license, and the copyright section names the Regents of the University of California through Lawrence Berkeley National Laboratory, with a notice that the software is owned by the U.S. Department of Energy and carries a government licence. The repository metadata reports the licence as NOASSERTION, which means the automated classifier could not map the LICENSE file to a standard identifier. Read the LICENSE file itself rather than trusting either label. This is a description of what the documents say, not legal advice.

Upgrade cost is low but not zero. The release cadence visible in the repository is roughly two to three releases a year: 3.19.1 in July 2025, 3.20 in November 2025 and 3.21 in April 2026. The last push to the repository was on 2026-07-10. Because client and server must both be iperf3, a version skew between two ends of a test is the thing to watch during an upgrade. Upgrade both ends together when you can.

Support expectations are explicit. The README asks that usage and code questions go to the mailing lists rather than the issue tracker, that bug reports include the iperf3 version, the platform and exact command-line arguments, and that suspected security issues go to [email protected]. A set of known issues is maintained at https://software.es.net/iperf/dev.html#known-issues rather than in the README.

Editorial conclusion

Adopt iperf3 if you need an active throughput measurement between two hosts you control, especially inside a research or enterprise network where the JSON output can feed a pipeline. Do not adopt it if you need passive monitoring of live traffic, or if one end of the path cannot run a server process. Before trusting a number, verify that both ends are running the same iperf3 version, because iperf3 is not backwards compatible with the original iperf and the manual page, not the README, is the reference for flags.

Frequently asked questions

Official sources

1. esnet/iperf on GitHub
2. Issues
3. Project website
4. README
5. Releases