Python wrapper for the iperf3 library. The module consists of two classes, Client and Server, that inherit from the base class IPerf3. They provide a nice (if i say so myself) and pythonic way to interact with the iperf3 utility.

At the moment the module redirects stdout and stderr to a pipe and returns the received data back after each or call. In later releases there will be an option to toggle this on or off.

A user should never have to utilise the IPerf3 class directly, this class provides common settings for the Client and Server classes.

To get started quickly see the Examples page.


class iperf3.Client(*args, **kwargs)[source]

An iperf3 client connection.

This opens up a connection to a running iperf3 server

Basic Usage:

>>> import iperf3

>>> client = iperf3.Client()
>>> client.duration = 1
>>> client.server_hostname = ''
>>> client.port = 5201
{'intervals': [{'sum': {...

Target bandwidth in bits/sec


The test blksize.


The test bulksize.

Deprecated argument, use blksize instead to ensure consistency with iperf3 C libary


The test duration in seconds.


The number of streams to use.


The iperf3 instance protocol

valid protocols are ‘tcp’ and ‘udp’

Return type:str

Toggles direction of test

Return type:bool

Run the current test client.

Return type:instance of TestResult

The server hostname to connect to.

Accepts DNS entries or IP addresses.

Return type:string

Toggle zerocopy.

Use the sendfile() system call for “Zero Copy” mode. This uses much less CPU. This is not supported on all systems.

Note there isn’t a hook in the libiperf library for getting the current configured value. Relying on zerocopy.setter function

Return type:bool


class iperf3.Server(*args, **kwargs)[source]

An iperf3 server connection.

This starts an iperf3 server session. The server terminates after each succesful client connection so it might be useful to run in a loop.

The C function iperf_run_server is called in a seperate thread to make sure KeyboardInterrupt(aka ctrl+c) can still be captured

Basic Usage:

>>> import iperf3

>>> server = iperf3.Server()
{'start': {...

Run the iperf3 server instance.

Return type:instance of TestResult


class iperf3.TestResult(result)[source]

Class containing iperf3 test results.

  • text – The raw result from libiperf as text
  • json – The raw result from libiperf asjson/dict
  • error – Error captured during test, None if all ok
  • time – Start time
  • timesecs – Start time in seconds
  • system_info – System info
  • version – Iperf Version
  • local_host – Local host ip
  • local_port – Local port number
  • remote_host – Remote host ip
  • remote_port – Remote port number
  • reverse – Test ran in reverse direction
  • protocol – ‘TCP’ or ‘UDP’
  • num_streams – Number of test streams
  • blksize
  • omit
  • duration – Test duration in seconds
  • local_cpu_total – The local total CPU load
  • local_cpu_user – The local user CPU load
  • local_cpu_system – The local system CPU load
  • remote_cpu_total – The remote total CPU load
  • remote_cpu_user – The remote user CPU load
  • remote_cpu_system – The remote system CPU load

TCP test specific

  • tcp_mss_default
  • retransmits – amount of retransmits (Only returned from client)
  • sent_bytes – Sent bytes
  • sent_bps – Sent bits per second
  • sent_kbps – sent kilobits per second
  • sent_Mbps – Sent Megabits per second
  • sent_kB_s – Sent kiloBytes per second
  • sent_MB_s – Sent MegaBytes per second
  • received_bytes – Received bytes
  • received_bps – Received bits per second
  • received_kbps – Received kilobits per second
  • received_Mbps – Received Megabits per second
  • received_kB_s – Received kiloBytes per second
  • received_MB_s – Received MegaBytes per second

UDP test specific

  • bytes
  • bps
  • jitter_ms
  • kbps
  • Mbps
  • kB_s
  • MB_s
  • packets
  • lost_packets
  • lost_percent
  • seconds


class iperf3.IPerf3(role, verbose=True, lib_name=None)[source]

The base class used by both the iperf3 Server and Client


You should not use this class directly


The bind address the iperf3 instance will listen on

use * to listen on all available IPs :rtype: string


Set/reset iperf test defaults.


Returns the version of the libiperf library

Return type:string

Toggles json output of libiperf

Turning this off will output the iperf3 instance results to stdout/stderr

Return type:bool

The port the iperf3 server is listening on


The iperf3 instance role

valid roles are ‘c’=client and ‘s’=server

Return type:‘c’ or ‘s’

Runs the iperf3 instance.

This function has to be instantiated by the Client and Server instances

Return type:NotImplementedError

Toggles verbose output for the iperf3 instance

Return type:bool