# pingtop: a terminal dashboard for pinging many hosts at once

> pingtop is a Textual-based TUI that pings many hosts concurrently over raw ICMP, showing RTT trends, loss statistics and sortable columns with a per-host detail panel. It targets the gap between a single ping command and a full monitoring stack, and it needs no root privileges on modern macOS or Linux.

**laixintao/pingtop** — 🏓Ping multiple servers and show results in a top-like terminal UI.

- Repository: https://github.com/laixintao/pingtop
- Website: https://pypi.org/project/pingtop/
- Stars: 541 · Forks: 39
- Language: Python
- License: MIT
- Published: 2026-10-22 · Updated: 2026-10-22 · Language: en
- Canonical page: https://hysenlabs.com/projects/laixintao-pingtop

## The pitch is the gap between one ping and a monitoring platform

pingtop is described as a fast, keyboard-first multi-host ping monitor for people who live in the terminal. The README is blunt about the positioning: 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. That is a real and quite specific audience. A single `ping` shows you one host in a scrolling log. A browser dashboard such as Grafana needs a server, an agent, a database and a retention policy. pingtop is a single Python process you start, point at a list of hosts, and quit, with a live Textual dashboard in between. The list of reasons it gives for existing covers the mechanics: monitoring many hosts at once in a single live TUI, spotting latency spikes with inline RTT trend bars, sorting by any of several signals, inspecting a selected host in a details panel, and editing targets without restarting the session.

The feature list includes using raw ICMP directly instead of shelling out to `ping`. That single choice explains the entire dependency footprint, and it has consequences worth understanding. Shelling out to `ping` is easy and portable, but it means spawning a process per host per interval, parsing the human-readable output, and dealing with the differences between the BSD ping on macOS and the iputils ping on Linux. Using ICMP sockets means the tool talks to the kernel directly and parses the reply itself. The README also notes that the raw ICMP implementation is derived from the original pingtop project, and that the TUI is built with Textual. The cost of the choice is that ICMP socket access is a privileged operation on some systems, which is what the permissions section is about.

## Installing is a pip install, and the only dependency pair is click and textual

The requirements are Python 3.10 or newer, and the install is one command:

```bash
   python -m pip install pingtop
```

After installation, run it directly:

```bash
   pingtop 1.1.1.1 8.8.8.8
```

The dependency list in the packaging metadata is unusually short for a network tool, and that is a direct consequence of the design decision to not shell out. There are two runtime dependencies, click for the command line parsing and textual for the interface, and that is it. There is no requests, no psutil, no netaddr, no scapy. The reason is the next section. The package version is 0.5.1, the build backend is poetry-core, the console script is `pingtop = "pingtop.cli:main"`, and the classifiers mark it as a beta console application that is operating system independent.

## The quick start, and the keyboard map that drives the panel

Five invocations cover most first sessions. Point it at a few public resolvers:

```bash
   pingtop 1.1.1.1 8.8.8.8 9.9.9.9
```

```bash
   pingtop 1.1.1.1 8.8.8.8 --interval 0.2 --timeout 0.5
```

```bash
   pingtop 10.22.76.19/30
```

```bash
   pingtop --hosts-file hosts.txt
```

The `--interval` and `--timeout` flags control the sampling cadence, and the interval can go quite low for a fast sweep. A CIDR block expands automatically into usable hosts:

```bash
   pingtop 10.22.76.19/30
```

And a hosts file is loaded with `--hosts-file`, where the file is newline-delimited and blank lines and lines starting with `#` are ignored. The `--hosts-file` option also deduplicates repeated hosts automatically when combining it with command line arguments, which is the kind of detail that only matters once you have combined a subnet expansion with a hand-written list and found the same address in both. The sample interval and timeout in the example are deliberately aggressive for a demo, so if you point it at a wide subnet you will want to raise them.

pingtop is keyboard-first in the strict sense. Session control uses single letters: `a` adds a host, `e` edits the selected one, `d` deletes it, `space` pauses or resumes it, `p` pauses or resumes everything, `r` resets statistics for the selected host and `ctrl+r` resets them for all hosts, `i` shows or hides the details panel, `tab` switches focus between the table and the panel, `h` or `?` opens help and `q` quits. Sorting uses capitals, one per column: `H` for host, `G` for resolved IP, `S` for sequence, `R` for last RTT, `I` for min, `A` for avg, `M` for max, `T` for stddev, `L` for lost packets, `P` for loss percentage, `U` for state and `W` for trend. Pressing the same sort key again reverses the order. The CLI surface underneath is small by comparison:

```bash
   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
```

The `U` for state and `W` for trend pair is the one to learn first, since state tells you whether a host is up and trend tells you whether it is getting worse.

## Snapshots and logs are the escape hatch out of the TUI

The common workflows are about capturing what happened rather than about watching it. Monitoring a host list and exporting the final snapshot:

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

```bash
   pingtop 1.1.1.1 8.8.8.8 --export snapshots/session.csv
```

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

```bash
   pingtop 1.1.1.1 --no-summary
```

CSV is written explicitly, with `--export` deciding the format from the extension unless you override it with `--export-format`. Debug logging goes to a file with `--log-file` and `--log-level debug`, which is how you find out why a host is showing as down. And `--no-summary` suppresses the colored summary printed on exit, which is what you want when the TUI is the entire point and the summary would only pollute a scrollback. The exit summary itself reports overall status, total hosts, tx, rx and loss percentage, the lossy or down hosts, and the top issues worth investigating first, and when you export a snapshot the file includes the session config, the aggregate stats and the per-host results. That is enough to paste into a ticket or diff against a previous run, and it is the closest thing pingtop has to persistence.

## ICMP permissions, and the one Linux setting that usually needs changing

pingtop uses ICMP sockets directly and does not require sudo or root privileges on modern systems. On macOS, unprivileged ICMP is supported out of the box. On Linux, most distributions ship with a permissive `net.ipv4.ping_group_range` by default. If you do hit a permission error, the README tells you how to check the current value:

```bash
   cat /proc/sys/net/ipv4/ping_group_range
```

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

And then how to widen the allowed range so your user or group can open ICMP sockets:

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

The sysctl change is not persistent across reboots unless you write it into a sysctl configuration file, which the README does not mention, so treat it as a session-scoped workaround and a reminder to check the distribution default. That permission model is a genuine advantage over the classic ping, which needed setuid on Linux for years and still needs extra rights in some containers.

## Development uses Poetry with a strict type checker and a narrow lint rule set

The development workflow is Poetry-based, and you may need to set `poetry config virtualenvs.in-project true` for the included vscode launch.json to work:

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

The tooling configuration shows how seriously the type checking is taken. mypy runs with `python_version = "3.10"`, the `pingtop` package, `strict_optional = true` and `no_implicit_optional = true`, and the pytest configuration sets `asyncio_mode = "auto"` with `pythonpath = ["src"]`, which tells you the concurrency model: the ping workers are asyncio tasks and the tests are written to run without explicit markers. Ruff is configured with a line length of 100, a py310 target and a selected rule set of E, F, I, B and UP. The repository has no GitHub releases, and the last push was on 2026-07-13, so the project is maintained in the sense that it is not archived, but the release cadence visible through PyPI is the more useful signal of its pace.

## Where pingtop is the wrong tool

Three limits are concrete. The first is that it measures the present and forgets it. A session export is a snapshot of the aggregate at the moment you quit, and there is no database, no retention and no history, so a spike that happened while you were asleep is not in the file. The second is that ICMP is a poor choice for anything behind a firewall. Many cloud providers and most corporate networks drop or rate-limit ICMP to the internet, so a host that is perfectly reachable over TCP will show as down or lossy in pingtop, and a team that trusts the loss column will chase a problem that does not exist. The third is that this is a client-side tool with no server component, which means no alerting, no shared view between operators and no way to check a host from somewhere else than the machine running the TUI. The MIT licence leaves none of those obstacles in the legal sense, but the architecture does.

## The alternative is a monitoring agent with a time series database

The realistic alternative is a proper agent-based stack such as Prometheus with a node exporter, or a hosted ping service, and the difference in approach is where the data lives and how long it lives. pingtop keeps its measurements in memory for the duration of one terminal session and hands you a file at the end. An agent-based stack writes each sample into a time series database, so you can graph latency over a week, alert when the 95th percentile crosses a threshold, and let several people look at the same dashboard. The cost is everything pingtop avoids. You need a server to hold the metrics, a rule file to express the alerting, and a place to store the history, and for a single engineer checking three hosts from a laptop, that is a lot of machinery. The middle option is a hosted ping service, which keeps the time series for you and gives you a web page rather than a TUI, at the cost of sending your host list to someone else and losing the terminal-native workflow.

## Conclusion

pingtop fits an engineer on a remote box who needs a live read on a set of hosts right now, without standing up a monitoring service or a browser dashboard. It is the wrong tool for historical retention or alerting, since a session export is a snapshot rather than a time series, and the wrong tool for hosts behind a firewall that drops ICMP, where a TCP-based check would report on a different path than the one you care about. Before you adopt it, confirm your Linux `net.ipv4.ping_group_range` allows your user to open ICMP sockets, and read the sorting keys, since the panel is driven almost entirely by single-key presses.

## FAQ

### How do I install pingtop?

Run `python -m pip install pingtop`. It requires Python 3.10 or newer, and the only runtime dependencies are click for argument parsing and textual for the interface.

### Does pingtop need sudo or root to send ICMP packets?

No. It uses ICMP sockets directly and does not require root on modern systems, with unprivileged ICMP supported out of the box on macOS and a permissive `net.ipv4.ping_group_range` shipped by default on most Linux distributions.

### How do I export the pingtop results?

Use `--export`, for example `pingtop --hosts-file hosts.txt --export snapshots/session.json`. The format follows the extension unless `--export-format` overrides it, and the file contains the session config, aggregate statistics and per-host results.

### How do I sort the pingtop table by loss?

Press `P` to sort by loss percentage, `L` for lost packets, `R` for the last RTT, `A` for average and `W` for trend. Pressing the same key again reverses the order.

## Sources

- [Issues](https://github.com/laixintao/pingtop/issues)
- [laixintao/pingtop on GitHub](https://github.com/laixintao/pingtop)
- [License: MIT](https://github.com/laixintao/pingtop/blob/master/LICENSE)
- [Project website](https://pypi.org/project/pingtop/)
- [README](https://github.com/laixintao/pingtop/blob/master/README.md)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/laixintao-pingtop