Skip to main content

ipyrf

Minimal iperf3-like network throughput tool with JSON output. Supports TCP and UDP, server and client modes.

Features

  • TCP and UDP tests

  • JSON or human-readable output

  • Optional bandwidth capping (TCP/UDP)

  • UDP packet loss estimation

  • Optional per-datagram UDP packet recording

  • Linux TCP congestion control selection (if available)

Installation

From PyPI (recommended):

python3 -m pip install ipyrf

From source (editable):

python3 -m venv .venv
source .venv/bin/activate
python3 -m pip install -U pip build
python3 -m pip install -e .

Test Utilities (ipyrf.test)

The ipyrf.test module provides test utilities for writing your own tests:

from ipyrf.test import IPyrfBuilder, CheckCriteria

def test_my_network(testdirectory):
    builder = IPyrfBuilder(testdirectory)
    port = 12345

    server = builder.build()
    client = builder.build()

    server.run_tcp_server("127.0.0.1", port)
    client.run_tcp_client("127.0.0.1", port, duration=2)

    # Check with custom criteria
    builder.check(
        (server, client),
        timeout=5,
        criteria={"min_bps": 1000000}
    )

Available classes and functions:

  • IPyrfClient: Run and monitor ipyrf instances

  • IPyrfBuilder: Builder pattern for creating test instances

  • CheckCriteria: Configurable criteria for evaluating test results

See examples/using_test_utilities.py for more examples.

Running Tests

The project includes a comprehensive test suite using pytest:

# Run all tests
python3 waf --run_tests

Usage

The package installs a console script named ipyrf.

Quick examples

TCP server:

ipyrf tcp server 0.0.0.0 --port 12345

TCP client:

ipyrf tcp client 127.0.0.1 --port 12345 --time 5
ipyrf tcp client 127.0.0.1 --port 12345 --time 5 --set-mss 1400

UDP server:

ipyrf udp server 0.0.0.0 --port 12345
ipyrf udp server 0.0.0.0 --port 12345 --packet-record packets.csv

UDP client (with bandwidth cap and optional payload size):

ipyrf udp client 127.0.0.1 --port 12345 --bandwidth 50M --time 5
ipyrf udp client 127.0.0.1 --port 12345 --bandwidth 50M --time 5 -l 1200

Interactive mode

You can run clients in an interactive mode that lets you adjust the pacing live using your keyboard. Use --interactive and optionally --interval (seconds between stats updates). When interactive is enabled, the same client logic is used underneath with a dynamic pacing controller.

Controls shown in the terminal:

  • ←: -1 Mbps

  • →: +1 Mbps

  • ↓: -10%

  • ↑: +10%

  • 0: reset to initial bandwidth (or unlimited for TCP if none was provided)

  • u: unlimited (disable pacing)

  • q: quit

Examples:

# TCP interactive (unlimited unless you pass --bandwidth)
ipyrf tcp client 127.0.0.1 --port 5201 --interactive

# TCP interactive with initial pacing and custom interval
ipyrf tcp client 127.0.0.1 --port 5201 --bandwidth 200M --set-mss 1400 --interactive --interval 0.5

# UDP interactive (requires initial --bandwidth)
ipyrf udp client 127.0.0.1 --port 5201 --bandwidth 50M -l 1200 --interactive

CLI overview

Top-level structure:

ipyrf [tcp|udp] [server|client] [OPTIONS]

Common options (both protocols, both roles):

  • --port: Port (default 5201)

  • --logfile: Redirect output to a file

  • --json_log: Emit logs in JSON (newline-delimited)

TCP-specific options:

  • tcp server ADDRESS: Start a TCP server on ADDRESS

  • tcp client ADDRESS: Start a TCP client to connect to ADDRESS

  • --congestion-control: Select Linux TCP CC algorithm if available

  • --time: Test duration (seconds), default 10

  • --bandwidth: Target rate (e.g., 50M); used for pacing, optional

  • --set-mss: Set approximate MSS via TCP_MAXSEG

  • --interactive: Enable interactive pacing controls

  • --interval: Stats interval in seconds for interactive mode (default 1.0)

UDP-specific options:

  • udp server ADDRESS: Start a UDP server on ADDRESS

  • udp client ADDRESS: Start a UDP client to ADDRESS

  • --time: Test duration (seconds), default 10

  • --bandwidth: Target rate (required for UDP client; e.g., 50M)

  • -l/--length: UDP payload length (default 1200)

  • --packet-record PATH: UDP server: write received packet traces to a CSV file after the test

  • --interactive: Enable interactive pacing controls

  • --interval: Stats interval in seconds for interactive mode (default 1.0)

UDP packet recording

Pass --packet-record PATH to a UDP server to record one trace entry per received datagram (sequence number, sender timestamp, receiver timestamp, packet size). Records are packed into fixed-size in-memory chunks during the test so the receive path stays free of CSV I/O. Chunks are allocated before the test starts (about 20 s of 1 Gbit/s traffic by default) so rotation does not stall the receive loop. When the test ends, the CSV file (columns seq, size, latency, tx_ts, rx_ts) is written to PATH.

Quick local test (two terminals):

# Terminal 1 — server with recording
ipyrf udp server 0.0.0.0 --port 12345 --packet-record packets.csv

# Terminal 2 — short paced client
ipyrf udp client 127.0.0.1 --port 12345 --bandwidth 50M --time 2 -l 1200

When the client finishes, the server exits and packets.csv contains the trace. Use --enable-latency on the client if you also want latency stats in the server summary (per-packet latency is always in the CSV).

JSON logging

Add --json_log to switch all output to newline-delimited JSON objects. This is useful for machine parsing or dashboards. Example:

ipyrf tcp client 127.0.0.1 --time 5 --json_log | jq

Notes

  • Output is JSON (newline-delimited for update events) when --json_log is given; otherwise, a human-readable summary is printed.

  • UDP mode sends a FIN marker at the end and the server exits after FIN (or inactivity timeout).

  • On Linux, congestion control selection is exposed if /proc entries are available.

License

MIT. See LICENSE.

Metadata

Release files for ipyrf 1.5.0

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for ipyrf 1.5.0
File Size Uploaded Provenance Actions
ipyrf-1.5.0.tar.gz 26.1 kB With provenance Details for ipyrf-1.5.0.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for ipyrf 1.5.0
File Interpreter ABI Platform Actions
ipyrf-1.5.0-py3-none-any.whl Python 3 none any Details for ipyrf-1.5.0-py3-none-any.whl

Total release size: 50.9 kB

Release files / ipyrf-1.5.0.tar.gz

Download URL ipyrf-1.5.0.tar.gz
Size 26.1 kB
Tags Source
SHA-256 checksum
How to use checksums
412ca26a23a99b89e0661717f8f18b7382b2088edeb3b8a5c34ecdc1730f8cd6
BLAKE2b-256 checksum
How to use checksums
c23f601fd6efd7f34adf87a140128bb37d9ad8a046ea05ce5b1321e937346fc0
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.14

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Aug 25, 2026.

Transparency log

Release files / ipyrf-1.5.0-py3-none-any.whl

Download URL ipyrf-1.5.0-py3-none-any.whl
Size 24.8 kB
Tags Python 3
SHA-256 checksum
How to use checksums
1c2c596d1a8a609ffd106c4369ac2c5275e81437aeaa668236b0f06bf142647b
BLAKE2b-256 checksum
How to use checksums
ec5b814cdca11caa7f2bb8965963826a0bb829f1bc7df33cbbe1658ef3da44e2
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.14

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Aug 25, 2026.

Transparency log

Security for ipyrf 1.5.0

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

Full provenance

Both files in this release have been uploaded with provenance metadata.

Select from 2 files

Attestation for ipyrf-1.5.0.tar.gz

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Aug 25, 2026.

Transparency log

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page