Do you actually know how fast your network is? Not what your switch spec sheet says — what it’s really doing between two hosts. iPerf3 is the tool sysadmins and homelab enthusiasts reach for when they need real answers, and in this video I’ll show you how to use it from the ground up.

We cover everything from installation to practical usage, including how to test WiFi vs wired, push a 10 gigabit ethernet connection, bind to a specific interface, and dial in your test parameters for accurate results.

What is iperf3?

So before we get into the actual commands, let me give you a quick overview of what iperf3 is and how it works — then we’ll get into hands-on examples, and after that I’ll cover some troubleshooting theory to help you understand where it fits in your workflow.

At its core, iperf3 is a client/server tool. You install it on two machines, run it in server mode on one end and client mode on the other, and it measures the bandwidth between them. Installation is straightforward — it’s just a package install on whatever distro you’re running, whether that’s apt, dnf, or whatever else you’re using.

And it’s not Linux-only either. iperf3 has builds available for Windows, macOS, and FreeBSD as well, so you can test between pretty much any combination of platforms. In this video I’ll be demonstrating on Linux, but the commands are identical — the only difference is how you install it.

Let me give you a real-world example of where this came in handy. A while back I upgraded my TrueNAS server to a 10 Gigabit NIC, but my file transfer speeds weren’t any faster than before. I ran iperf3 between my workstation and the server, and the results were showing speeds in the 1 Gigabit range — nowhere near 10G. That told me the bottleneck wasn’t the server itself, and after checking the path I found a 1G switch sitting between them. Swapped that out, ran iperf3 again, and confirmed I was actually getting 10G throughput. Problem solved.

That’s exactly the kind of thing iperf3 is good for — giving you a concrete number so you can either rule out the network or confirm it’s the problem and start narrowing down where.

Alright, let’s get into the actual examples.

Examples

Alright, let’s get into it. I’m going to walk through a real example using my workstation and my TrueNAS server, and we’ll use this to explore the most useful iperf3 options along the way.

First things first — iperf3 needs to be installed on both endpoints. On TrueNAS Scale, which is Debian-based, that’s just:

bash

sudo apt install iperf3

Now, I generally don’t like installing ad-hoc packages on an appliance like TrueNAS, but iperf3 is a small, self-contained utility that isn’t going to interfere with anything, so it’s fine here. Same command on my workstation, which is also running Debian.

Once it’s installed on both machines, the basic usage is simple — you run it in server mode on one end with -s, and connect to it from the other end with -c:

bash

# On the server
iperf3 -s

# On the client
iperf3 -c 192.168.1.10

It doesn’t matter which machine you designate as the server — pick whichever is more convenient.

So let’s run a test and see what we get. The speeds look okay, but not great — and my TrueNAS server has a 10G NIC, so I’d expect a lot more than this. The bottleneck here is actually my workstation’s built-in NIC, which tops out at 2.5Gbps. So that explains the result. I have a USB-C 10G adapter I can plug in, so let’s try that.

Even with the adapter plugged in, the speeds haven’t changed — and the reason is that iperf3 is still using the built-in 2.5G interface. We need to explicitly tell it which interface to use, and for that we use the -B option, binding to the IP address of the 10G adapter. Let’s first check what IP it was assigned:

bash

ip addr show

And now we can run the test binding to that interface:

bash

iperf3 -c 192.168.1.10 -B 192.168.1.20

And there we go — much faster. So -B is something to keep in mind any time you’re on a machine with multiple NICs and you want to make sure you’re testing the right one.

Now let’s look at a few other useful options. First, -t lets you set the test duration in seconds — the default is 5, but you can extend it:

bash

iperf3 -c 192.168.1.10 -t 30

Longer tests are useful for catching intermittent issues that wouldn’t show up in a 5-second window — things like a flaky cable or a switch that starts throttling under sustained load.

Next is -R for reverse mode, which flips the direction of the test. By default the client sends to the server — with -R, the server sends to the client instead, so you’re measuring from the client’s download perspective:

bash

iperf3 -c 192.168.1.10 -R

Upload and download speeds aren’t always symmetric, so it’s worth running both directions.

Then there’s -P for parallel streams. A single TCP stream often won’t saturate a fast link on its own due to how TCP’s congestion control works — on a 10G link especially, you’ll frequently get misleading results without this. Running multiple parallel streams gives you a more accurate picture:

bash

iperf3 -c 192.168.1.10 -P 4

The output will show each stream individually, plus a [SUM] line at the bottom — that’s the number you want.

Finally, the lowercase -p lets you specify a port. The default is 5201, but you can change it — useful if that port is blocked by a firewall, or if you want to run multiple iperf3 server instances on the same machine simultaneously:

bash

# Server on a custom port
iperf3 -s -p 5202

# Client connecting to that port
iperf3 -c 192.168.1.10 -p 5202

Those are the options you’ll reach for most often. There’s more in the man page if you want to dig deeper, but honestly those cover the vast majority of real-world use cases.

How iperf3 works in practice

Before we wrap up, I want to give you some practical guidance on how to actually use iperf3 findings in your troubleshooting process — because getting a number is only half the battle.

Think about the path, not just the endpoints

When you run an iperf3 test, you’re measuring the bandwidth of the entire path between two machines — not just the NICs on either end. There could be multiple switches, routers, or even a firewall in between, and any one of them can be the bottleneck. So if your results are slower than expected, the next question is: where in the path is the problem?

A network diagram is really helpful here. If you have one, pull it up and trace the path between your two endpoints. Then start narrowing it down by testing hop by hop — run iperf3 between your machine and the first switch, then the next device, and so on until you find where the speed drops off. Sometimes you don’t even need to run tests — just checking the spec sheet for each device in the path will tell you if something only supports 1G when everything else is 10G.

Results will never be exact — and that’s normal

Even on a healthy 10G network, you’re not going to see exactly 10Gbps. There’s always some overhead, and other factors can pull the numbers down — CPU load on either endpoint being a big one. If a machine’s CPU is saturated, it may not be able to drive the network interface at full speed, which can look like a network problem when it isn’t. So if your results seem low, it’s worth glancing at CPU utilization on both ends before concluding the network is to blame.

A real-world example: isolating a bottleneck

Here’s a good example of iperf3 helping narrow down a problem. At one point I noticed Syncthing transfers were unusually slow. I ran iperf3 between my workstation and the Syncthing VM and confirmed the speed was bad. But when I tested between my workstation and the underlying Proxmox host directly, speeds were fine. That told me the problem was specific to that VM, not the physical network. After some digging, I found that the Proxmox firewall was enabled on that VM — and the overhead it was adding was killing throughput. Disabled it, ran the test again, and speeds jumped back up immediately.

That’s exactly how iperf3 is meant to be used — not as a magic answer, but as a way to progressively isolate where the problem actually lives.

Make it a habit

It’s also worth running iperf3 periodically even when nothing seems wrong, just to establish a baseline. If you know what “normal” looks like on your network, you’ll have something to compare against when things do go sideways.

And if you want more troubleshooting strategies like this, check out my Linux Troubleshooting Strategies ebook — link is in the description.