Network benchmarks, from Python¶
iperf3-lib is a programmable network benchmarking and analysis library powered
by native libiperf through CFFI. Configure traffic, preserve the measurements,
compare results, and run finite sequential experiments from Python.
Python 3.12–3.14 · Linux tested · libiperf 3.19.1 / 3.21 · MIT license
Choose your next step¶
-
Run a benchmark
Install the shared library, configure a TCP or UDP client, and learn the synchronous and asynchronous APIs.
-
Understand the measurements
Read flow directions, sender and receiver observations, intervals, and the original native JSON.
-
Save results
Save native and normalized measurements with requested settings, verified observations, producer identity, and timing provenance.
-
Analyze measurements
Calculate throughput stability, stream balance and scaling, and directional comparisons with explicit missing-data and diagnostic limits.
-
Run repeatable experiments
Retain warm-ups, repetitions and failures; assess compatible baselines or explore finite parameter matrices with explicit order and admission budgets.
-
Export completed runs
Use Prometheus gauges, atomic textfiles, and a reproducible local Grafana integration. Benchmark scheduling remains under your application's control.
A small starting point¶
Start a compatible iperf3 server on a host you control, then run:
from iperf3_lib import Client, ClientConfig
result = Client(ClientConfig(server="127.0.0.1", duration=2)).run()
if result.ok:
print(f"{result.summary_mbps:.2f} Mbps")
else:
print(result.error)
The native library generates traffic and measures it. Python provides configuration, typed access to the output, and integration with your application. The package does not bundle libiperf or operate a benchmark scheduler or metrics service.
Know the execution boundary¶
Linux is the tested platform. Basic direct native calls share process-global state and must be serialized. Expanded controls, event delivery and explicit execution timeouts use isolated Python/CFFI workers. Async helpers use executor threads; cancelling an await alone does not stop the operation. See compatibility and limitations.
Use the native option inventory to find binding, protocol, transport, server-policy and output controls. Option availability also depends on the native build, kernel and peer; a configuration request is not proof of effective network behavior.