winload 0.1.8rc14

Network Load Monitor - nload-like TUI tool for Windows

Winload

A lightweight, real-time CLI tool for monitoring network bandwidth and traffic, inspired by Linux's nload.

📖 English 📖 简体中文(大陆) 📖 繁體中文(台灣) 📖 日本語 📖 한국어

📖 Build Docs

🚀 Introduction

Winload brings an intuitive, visual network monitor to the modern terminal. It started as a Windows-focused tool to fill the nload gap, and now targets Linux and macOS as well.

🙏 Acknowledgements

Winload is inspired by the classic 「nload」 project by Roland Riegel. Many thanks for the original idea and experience. https://github.com/rolandriegel/nload

✨ Key Features

• Dual implementations
  • Rust edition: fast, memory-safe, single static binary—great for everyday monitoring.
  • Python edition: easy to hack and extend for prototyping or integrations.
• Cross-platform: Windows, Linux, and macOS (x64 & ARM64).
• Real-time visualization: live incoming/outgoing graphs and throughput stats.
• Minimal UI: clean TUI that mirrors nload's ergonomics.

📊 Performance Benchmarks

⚡ Winload (Rust) achieves ~10ms startup and <5MB binary size, significantly outperforming Python and matching C++ nload in efficiency.

🔧 Run from Source

Python

git clone https://github.com/VincentZyuApps/winload.git
# or clone from Gitee (faster in China Mainland):
# git clone https://gitee.com/vincent-zyu/winload.git
cd winload/py
pip install -r requirements.txt
python main.py

Rust

git clone https://github.com/VincentZyuApps/winload.git
cd winload/rust
cargo run --release
cargo run --release -- --help    # Show help
cargo run --release -- --version # Show version

🐍 Python Edition Installation

💡 Implementation Note: Only PyPI and GitHub/Gitee provide Python edition.
Only Cargo provides Rust source code for local compilation.
All other package managers (Scoop, AUR, npm, APT, RPM) and GitHub Releases distribute Rust binaries only.

Python (pip)

pip install winload
# recommend use uv:
# https://docs.astral.sh/uv/getting-started/installation/
# https://gitee.com/wangnov/uv-custom/releases
uv venv --python 3.12
uv pip install winload
uv run winload
uv run python -c "import shutil; print(shutil.which('winload'))"

📥 Rust Edition Installation (recommended)

npm (cross-platform)

npm install -g @vincentzyuapps/winload
npm list -g @vincentzyuapps/winload
# on Windows, use win-nload to avoid conflict with System32\winload.exe
# on Linux/macOS, both winload and win-nload work
# or use npx directly
npx @vincentzyuapps/winload

⚠️ The old package winload-rust-bin has been deprecated. Please use @vincentzyuapps/winload instead. The scoped package name is required for GitHub Packages compatibility.

Includes 6 precompiled binaries for x86_64 & ARM64 across Windows, Linux, and macOS.

Cargo (Build from source)

cargo install winload
cargo install --list

Windows (Scoop)

scoop bucket add vincentzyu https://github.com/VincentZyuApps/scoop-bucket
# or from Gitee:
# scoop bucket add vincentzyu https://gitee.com/vincent-zyu/scoop-bucket
scoop install winload
# execute bin file
win-nload
Get-Command win-nload # Powershell
where win-nload # CMD

💡 Recommended: use Windows Terminal instead of the legacy Windows Console for correct CJK character rendering and better TUI experience.

scoop bucket add versions
scoop install windows-terminal-preview
wtp

Arch Linux (AUR):

paru -S winload-rust-bin
which winload

Linux (one-liner)

Supports Debian/Ubuntu and derivatives — Linux Mint, Pop!_OS, Deepin, UOS, etc. (apt)

Supports Fedora/RHEL and derivatives — Rocky Linux, AlmaLinux, CentOS Stream, etc. (dnf)

curl -fsSL https://raw.githubusercontent.com/VincentZyuApps/winload/main/docs/install_scripts/install.sh | bash
which winload

📄 View install script source

🇨🇳 Gitee mirror (faster in China Mainland):

curl -fsSL https://gitee.com/vincent-zyu/winload/raw/main/docs/install_scripts/install_gitee.sh | bash
which winload

📄 View Gitee install script

macOS / Linux (Homebrew)

brew tap vincentzyuapps/tap
# or from Gitee (manual tap clone):
# git clone https://gitee.com/vincent-zyu/homebrew-tap.git "$(brew --prefix)/Library/Taps/vincentzyuapps/homebrew-tap"
brew install winload
which winload

📄 View Homebrew formula

⚠️ These install scripts only support systems with apt or dnf package managers on x86_64 / aarch64 architectures. For other platforms, use npm (npm install -g @vincentzyuapps/winload) or Cargo (cargo install winload) instead.

Manual install

DEB (Debian/Ubuntu):

# Download the latest .deb from GitHub Releases
sudo dpkg -i ./winload_*_amd64.deb
# or use apt (auto-resolves dependencies)
sudo apt install ./winload_*_amd64.deb
which winload

RPM (Fedora/RHEL):

sudo dnf install ./winload-*-1.x86_64.rpm
which winload

Or download binaries directly from GitHub Releases.

⌨️ Usage

winload              # Monitor all active network interfaces
winload -t 200       # Set refresh interval to 200ms
winload -d "Wi-Fi"   # Start with a specific device
winload -e           # Enable emoji decorations 🎉
winload --npcap      # Capture 127.0.0.1 loopback traffic (Windows, requires Npcap)

Options

Flag	Description	Default
-t, --interval <MS>	Refresh interval in milliseconds	500
-a, --average <SEC>	Average calculation window in seconds	300
-d, --device <NAME>	Default device name (partial match)	—
-e, --emoji	Enable emoji decorations in TUI 🎉	off
-U, --unicode	Use Unicode block characters for graph (█▓░·)	off
-u, --unit <UNIT>	Display unit: bit or byte	bit
-b, --bar-style <STYLE>	Bar style: fill, color, or plain	fill
--in-color <HEX>	Incoming graph color, hex RGB (e.g. 0x00d7ff)	cyan
--out-color <HEX>	Outgoing graph color, hex RGB (e.g. 0xffaf00)	gold
-m, --max <VALUE>	Fixed Y-axis max (e.g. 10M, 1G, 500K) — conflicts with --smart-max	auto
--smart-max [SECS]	Smart adaptive Y-axis: auto-decays after traffic spikes (default half-life: 10s) — conflicts with --max	off
-n, --no-graph	Hide graph, show stats only	off
--hide-separator	Hide the separator line (row of equals signs)	off
--no-color	Disable all TUI colors (monochrome mode)	off
--npcap	[Windows Rust Only] Capture loopback traffic via Npcap (recommended)	off
--debug-info	Print network interface debug info and exit	—
-h, --help	Print help (--help --emoji for emoji version!)	—
-V, --version	Print version	—

Y-axis scaling modes — there are three mutually exclusive scenarios:

Mode	Flag	Behavior
Fixed max	--max <VALUE>	Y-axis is locked to the specified value (e.g. 10M, 1G).
Smart max	--smart-max [SECS]	Y-axis adapts automatically: jumps up on traffic spikes, then smoothly decays back down (exponential decay, default half-life 10 s).
History peak	(neither flag)	Y-axis follows the historical maximum of each metric — the default behavior.

⚠️ --max and --smart-max conflict with each other — you can only use one at a time.

Keyboard Shortcuts

Key	Action
← / → or ↑ / ↓	Switch network device
F3	Toggle debug info overlay (Minecraft-style)
=	Toggle separator line visibility
c	Toggle color on/off
q / Esc	Quit

🪟 Windows Loopback (127.0.0.1)

Windows cannot report loopback traffic through standard APIs — this is a functional deficiency in Windows' network stack.

To capture loopback traffic on Windows, use the --npcap flag:

winload --npcap

This requires Npcap installed with "Support loopback traffic capture" enabled during setup.

I previously tried polling Windows' own GetIfEntry API directly, but the counters are always 0 for loopback — there is simply no NDIS driver behind the loopback pseudo-interface to count anything. That code path has been removed.

📖 For a deep dive into why Windows loopback is broken, see docs/win_loopback.md

On Linux and macOS, loopback traffic works out of the box — no extra flags needed.

🖼️ Previews

Python Edition Preview

Rust Edition Preview

Rust Edition Preview GIF

📦 Dependencies

Python Edition

Package	Version	Description
	3.12.12	Programming language
	≥7.0	Process and system utilities
	≥2.0	Windows curses support

Rust Edition

Package	Version	Description
	1.93.0	Programming language
	0.29	Terminal UI framework
	0.28	Cross-platform terminal library
	0.32	System information library
	4	Command-line argument parser
	2	Packet capture (optional, Windows)