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)
| 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)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| 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 logRelease 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 logSecurity 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.
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 logA 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.