pingtop 0.5.0

Modern multi-host ping monitor with a Textual TUI.

pingtop is a fast, keyboard-first multi-host ping monitor for people who live in the terminal. Point it at a few hosts, a whole subnet, or a host list, and get a live Textual dashboard with RTT trends, loss stats, sortable columns, and per-host drill-down details.

It is built for the moment when ping is too small, dashboards are too heavy, and you just want to see what your network is doing right now.

Why pingtop

• Monitor many hosts at once in a single live TUI

• Spot latency spikes instantly with inline RTT trend bars

• Sort by host, IP, RTT, avg, max, stddev, loss, state, or trend

• Inspect a selected host in a dedicated details panel

• Add, edit, delete, pause, and reset hosts without restarting the session

• Load targets from CLI args, CIDR ranges, or a hosts file

• Export the final snapshot to JSON or CSV

• Print a clean colored summary on exit

• Use raw ICMP directly instead of shelling out to ping

Feature Highlights

Live network view

• Real-time host table with RTT, min/avg/max, stddev, loss, state, and trend columns

• Responsive layout that keeps the table useful on both wide and narrow terminals

• Stable numeric column widths, so values stay easy to scan while data updates

Designed for triage

• One-key sorting across every important signal

• A details panel with an expanded RTT graph for the selected host

• Global status strip showing active hosts, paused hosts, errors, sent packets, and total loss

Built for real sessions

• Add or fix targets in place instead of restarting

• Pause a noisy host, pause everything, or reset stats when you want a clean measurement window

• Deduplicate repeated hosts automatically when combining CLI args and --hosts-file

Install

Requirements:

• Python 3.10+

python -m pip install pingtop

After installation, run it directly:

pingtop 1.1.1.1 8.8.8.8

Quick Start

Monitor a few public resolvers:

pingtop 1.1.1.1 8.8.8.8 9.9.9.9

Use a faster sampling interval:

pingtop 1.1.1.1 8.8.8.8 --interval 0.2 --timeout 0.5

Expand a CIDR block into usable hosts automatically:

pingtop 10.22.76.19/30

Load hosts from a file:

pingtop --hosts-file hosts.txt

hosts.txt is newline-delimited. Blank lines and lines starting with # are ignored.

Common Workflows

Monitor a host list and export the final snapshot:

pingtop --hosts-file hosts.txt --export snapshots/session.json

Write CSV explicitly:

pingtop 1.1.1.1 8.8.8.8 --export snapshots/session.csv

Enable debug logging while troubleshooting:

pingtop 10.0.0.1 10.0.0.2 --log-file pingtop.log --log-level debug

Disable the exit summary when you only want the TUI:

pingtop 1.1.1.1 --no-summary

CLI Options

Usage: pingtop [OPTIONS] [HOSTS]...

Options:
  -i, --interval FLOAT            ping interval in seconds
  -t, --timeout FLOAT             timeout in seconds
  -s, --packet-size INTEGER       ICMP payload size in bytes
  --hosts-file FILE               newline-delimited host list
  --summary / --no-summary        print a colored summary on exit
  --export FILE                   export final snapshot
  --export-format [json|csv]      override export format
  --log-file FILE                 write logs to a file
  --log-level [debug|info|warning|error|critical]
  -h, --help

Keyboard Shortcuts

Session control:

• a add a host

• e edit the selected host

• d delete the selected host

• space pause or resume the selected host

• p pause or resume all hosts

• r reset statistics for the selected host

• ctrl+r reset statistics for all hosts

• i show or hide the details panel

• tab switch focus between the table and details panel

• h or ? open help

• q quit

Sorting:

• H host

• G resolved IP

• S sequence

• R last RTT

• I min RTT

• A avg RTT

• M max RTT

• T stddev

• L lost packets

• P loss percentage

• U state

• W trend

Press the same sort key again to reverse the order.

What You Get On Exit

By default, pingtop prints a compact colored summary with:

• overall status

• total hosts, tx, rx, and loss percentage

• lossy or down hosts

• top issues worth investigating first

If you export a snapshot, the file includes session config, aggregate stats, and per-host results.

Permissions

pingtop uses ICMP sockets directly.

On Linux, non-root access depends on net.ipv4.ping_group_range. If you hit a permission error, inspect the current value:

cat /proc/sys/net/ipv4/ping_group_range

Then widen the allowed range so your user or group can open ICMP sockets:

sudo sysctl -w net.ipv4.ping_group_range='0 1001'

Development

poetry install
poetry run pytest
poetry run ruff check .
poetry run mypy src

Credits

• The raw ICMP implementation is derived from the original pingtop project.

• The TUI is built with Textual.

If pingtop earns a place in your toolbox, star the repo.