iperf3-lib

Documentation · Changelog · Issues

iperf3-lib is a programmable network benchmarking and analysis library powered by native libiperf through CFFI. Configure clients and servers from Python, preserve and analyze measurements, run repeatable experiments, and export results to Prometheus.

Why use iperf3-lib?

Use iperf3-lib when benchmarks feed an application, a repeatable test campaign, or a monitoring pipeline. Reuse a tested Python API for the work that otherwise accumulates around subprocess calls or Ansible tasks:

• Configure tests with validated dataclasses, including traffic direction, transport controls, and explicit rate intent.
• Interpret measurements consistently, keeping sender and receiver observations separate, preserving native JSON, and distinguishing missing measurements from measured zero.
• Build on reusable experiments and reports: repeated trials, baseline assessments, bounded parameter sweeps, portable artifacts, and Prometheus output.

The library calls libiperf through CFFI; it does not invoke the iperf3 executable. Some execution paths use isolated Python worker processes. A short CLI script remains useful for one-off tests, and Ansible can deploy and run Python benchmark applications across your hosts. See choosing a Python API, CLI, or Ansible workflow for the comparison, execution boundaries, and version-specific features.

Getting started

Follow the installation and first-run guide to install the Python package and native library, start a server, and run a benchmark. The Python package does not bundle libiperf. Current native qualification covers libiperf 3.19.1 and 3.22 on Linux; see the compatibility reference.

Python 3.12–3.15 with the standard GIL is supported. Stable CI and release qualification cover all four Python versions against both native endpoints, including installed wheel and sdist checks.

The 0.4.0 candidate is unreleased; 0.3.0 is the latest published version. Documentation follows main. The installation guide explains how to choose between a published package and a source revision; consult the changelog for release status. Upgrade guidance covers 0.2.0 to 0.3.0 and unreleased changes after 0.3.0.

Documentation

The documentation contains the examples, API contracts, supported versions, and execution limits.

Contributing

See the contributor guide for development setup, checks, and repository policies. Use GitHub issues to report bugs or discuss planned work.