ipvtop

A real-time network traffic monitor for the terminal with IPv4/IPv6 breakdown. Inspired by btop.

Built with Textual, Plotext, and Scapy.

Build Status

Features

• Live packet capture with per-second refresh
• IPv4 vs IPv6 traffic breakdown across all panels
• Rolling 60-second bandwidth chart (Mb/s) with braille-dot plotting
• Sparkline history for packets/s and Mb/s per protocol version
• Visual IPv4/IPv6 traffic split bar
• Top talkers table (sources and destinations) with tabbed view
• Protocol breakdown (TCP, UDP, ICMP, ICMPv6, GRE, ESP, AH, SCTP)
• btop-inspired dark theme with rounded borders and color-coded panels
• Runs on Linux and macOS

Screenshot

Installation

Pre-built binaries

Download the latest binary for your platform from GitHub Releases:

Platform	Architecture	Download
Linux	x86_64	ipvtop-linux-x86_64
Linux	ARM64	ipvtop-linux-arm64
macOS	ARM64	ipvtop-macos-arm64

chmod +x ipvtop-*
sudo ./ipvtop-linux-x86_64 eth0

From source with uv

git clone https://github.com/yourusername/ipvtop.git
cd ipvtop
uv sync
sudo uv run ipvtop eth0

With pip

pip install .
sudo ipvtop eth0

Usage

usage: ipvtop [-h] [-l] [interface]

Real-time network traffic monitor with IPv4/IPv6 breakdown

positional arguments:
  interface   Network interface to monitor (e.g., eth0, wlan0, en0)

options:
  -h, --help  show this help message and exit
  -l, --list  List available network interfaces and exit

Examples

# List available interfaces
ipvtop -l

# Monitor a specific interface (requires root)
sudo ipvtop eth0        # Linux
sudo ipvtop en0         # macOS

# Run from source with uv
sudo uv run ipvtop eth0

Keybindings

Key	Action
q	Quit
p	Pause / resume display
r	Reset all statistics

Dashboard panels

Summary

Displays running totals and per-second rates for IPv4 and IPv6 traffic (packets and bytes), the IPv4:IPv6 ratio, and session uptime.

Bandwidth

A 60-second rolling line chart rendered with braille characters showing IPv4 and IPv6 throughput in Mb/s.

IPv4 / IPv6 Split

A full-width stacked bar showing the cumulative byte ratio between IPv4 (blue) and IPv6 (green) with embedded percentage labels.

Traffic History

Four sparkline rows showing rolling 60-second history:

• IPv4 Mb/s
• IPv6 Mb/s
• IPv4 packets/s
• IPv6 packets/s

Top Talkers

A tabbed data table switching between top source and destination IPs. Shows per-second and cumulative packet/byte counts. IPs are color-coded blue (v4) or green (v6).

Protocols

Horizontal bar chart showing the distribution of traffic across protocols (TCP, UDP, ICMP, ICMPv6, GRE, ESP, AH, SCTP).

Color scheme

The interface uses a btop-inspired dark theme:

Element	Color
IPv4	Blue (#50a0ff)
IPv6	Green (#50ffa0)
ICMP	Orange (#ffa050)
ICMPv6	Pink (#ff50a0)
Background	Dark blue-black (#0a0a1a)
Panel borders	Rounded, muted (#303050)

Building binaries

Local build

uv sync --dev
uv run pyinstaller ipvtop.spec --clean --noconfirm
# Binary at dist/ipvtop

CI/CD

The GitHub Actions workflow (.github/workflows/build.yml) builds binaries for all four platform/architecture combinations.

Automatic release on tag push:

git tag v0.1.0
git push origin v0.1.0

This triggers a build of all four binaries, generates SHA256 checksums, and creates a GitHub Release with the artifacts attached.

Manual build via the Actions tab using "Run workflow".

Requirements

• Python >= 3.10
• Root privileges (for raw packet capture)
• A terminal emulator with 256-color support

Dependencies

Package	Purpose
textual	TUI framework
textual-plotext	Terminal charts
scapy	Packet capture and parsing

Platform notes

macOS

Promiscuous mode is not supported on most macOS interfaces. ipvtop automatically disables it and captures in normal mode, which sees all traffic to and from your machine.

Linux

Works out of the box with sudo. Alternatively, grant the binary the CAP_NET_RAW capability to avoid running as root:

sudo setcap cap_net_raw+ep ./ipvtop
./ipvtop eth0

License

MIT — Copyright © 2026 Isaac B. Behrens. All rights reserved.