PyMTR Command Manual

Name

pymtr - continuous route diagnostics with GUI, live TUI, and report exports.

Synopsis

pymtr
pymtr HOST [options]
pymtr --gui [HOST]
pymtr --report HOST [options]

Running pymtr without arguments opens the Tkinter GUI. Running pymtr HOST starts the Rich live TUI. Running pymtr --report HOST performs a finite number of cycles and writes or prints a report.

In the self-contained Windows release folder, use PyMTR.exe for the GUI and PyMTR-CLI.exe for command-line/TUI usage. The installed/source console command remains pymtr.

Description

PyMTR is a clean-room Python route diagnostic tool inspired by the WinMTR workflow and MTR-style command-line ergonomics. It repeatedly probes each TTL toward a target, records per-hop packet counters, latency, jitter, and historical percentile metrics, and can export the current snapshot as text, CSV, HTML, or PDF.

PyMTR currently focuses on ICMP-based diagnostics. Raw socket access usually requires administrator/root privileges or platform-specific network capabilities.

Options

HOST : Target hostname or IP address. With no options this opens the live TUI.

--gui [HOST] : Open the graphical interface. If HOST is provided, the Host field is prefilled.

--report : Run finite report mode. Requires HOST.

-4 : Resolve and probe using IPv4.

-6 : Resolve and probe using IPv6.

-n, --no-dns : Disable reverse DNS lookups.

-b, --show-ips : Compatibility option. PyMTR always keeps IP addresses visible, so this is accepted as a no-op.

-m, --max-ttl TTL : Maximum TTL/hop count to probe.

-s, --psize BYTES : ICMP payload size in bytes.

-i, --interval SECONDS : Delay between trace cycles in seconds.

--interval-ms MILLISECONDS : Delay between trace cycles in milliseconds. This takes precedence over --interval.

-Z, --timeout SECONDS : Timeout for each probe in seconds.

--timeout-ms MILLISECONDS : Timeout for each probe in milliseconds. This takes precedence over --timeout.

-c, --report-cycles COUNT : Number of cycles to run in report mode. Defaults to 10.

-o, --order ORDER : MTR-style metric letters such as LDRSNBAWVGJMXI, or a comma-separated list of PyMTR column keys such as hostname,nr,loss,lp50,jp50. Letter mode always prepends Hostname and Nr.

--columns KEY[,KEY...] : Explicit PyMTR column keys. This overrides --order.

--route-mode static|dynamic : Choose route display mode. static preserves the first complete route identity. dynamic updates hop identity when the route changes.

--txt PATH : Write the final snapshot as a text report.

--csv PATH : Write the final snapshot as a CSV report.

--html PATH : Write the final snapshot as an HTML report.

--full-report PATH : Write a PDF FullReport with current metrics and historical charts.

--debug : Enable detailed JSON Lines telemetry.

--debug-log PATH : Set the telemetry JSON Lines path.

--version : Print the PyMTR version.

--help : Print concise command-line help.

MTR-Style `-o` Mapping

Letter	PyMTR column
`L`	`loss` / Loss %
`D`	`drop` / dropped probes
`R`	`recv` / received replies
`S`	`sent` / sent probes
`N`	`last` / newest latency
`B`	`best` / best latency
`A`	`avg` / average latency
`W`	`worst` / worst latency
`V`	`stdev` / standard deviation
`G`	`gmean` / geometric mean
`J`	`jitter` / current jitter
`M`	`javg` / average jitter
`X`	`jmax` / maximum jitter
`I`	`jint` / interarrival jitter

PyMTR also accepts comma-separated column keys with -o when you need modern columns that do not exist in the original MTR alphabet:

Key	Column
`lp50`	Latency percentile 50 / median
`lp95`	Latency percentile 95
`lp99`	Latency percentile 99
`jp50`	Jitter percentile 50 / median
`jp95`	Jitter percentile 95
`jp99`	Jitter percentile 99

Examples

Open the GUI:

pymtr

Start the live TUI:

pymtr github.com

Run 20 report cycles and print a text report:

pymtr --report github.com -c 20

Write CSV and HTML exports using an MTR-like order:

pymtr --report github.com -c 30 -o LDRSNBAWVGJMXI --csv github.csv --html github.html

Write a percentile-focused report using PyMTR column keys:

pymtr --report github.com -c 30 -o hostname,nr,loss,lp50,lp95,lp99,jp50,jp95,jp99 --csv tail.csv

Use IPv4, disable DNS, and set a 500 ms interval:

pymtr github.com -4 -n --interval-ms 500

Exit Codes

0 : The requested GUI, TUI, or report operation completed successfully.

2 : The CLI could not complete the trace or export operation. Typical causes are raw socket permissions, DNS resolution failures, unavailable network access, or invalid output paths.

Permissions

ICMP raw socket probing normally requires elevated privileges. On Windows, run PyMTR as Administrator. On Linux and macOS, run with appropriate capabilities or privileges according to your operating system security model.

Metrics

Latency and jitter metrics are displayed in milliseconds. Loss is a percentage. Sent, Recv, and Drop are packet counters. Percentile metrics such as LP50, LP95, LP99, JP50, JP95, and JP99 are derived from the temporary per-session history database and do not change the packet collection engine.

Files

PyMTR.ini : User settings file stored under PyMTR’s runtime base directory.

data/history/*.sqlite3 : Temporary per-session history stores used for Hop Details and FullReport charts.

logs/pymtr-otel.jsonl : Default debug telemetry file when detailed telemetry is enabled.