# Winload <img src="docs/images/miku.png" height="32px">
> A lightweight, real-time CLI tool for monitoring network bandwidth and traffic, inspired by Linux's nload.
> **[๐ English](readme.md)**
> **[๐ ็ฎไฝไธญๆ(ๅคง้)](readme.zh-cn.md)**
> **[๐ ็น้ซไธญๆ(ๅฐ็ฃ)](readme.zh-tw.md)**
> **[๐ ๆฅๆฌ่ช](readme.jp.md)**
> **[๐ ํ๊ตญ์ด](readme.ko.md)**
[](https://github.com/VincentZyuApps/winload)
[](https://gitee.com/vincent-zyu/winload)
[](https://github.com/VincentZyuApps/winload/releases)
[](https://github.com/VincentZyuApps/winload/releases)
[](https://github.com/VincentZyuApps/winload/releases)
[](https://github.com/VincentZyuApps/winload/releases)
[](https://pypi.org/project/winload/)
[](https://www.npmjs.com/package/@vincentzyuapps/winload)
[](https://crates.io/crates/winload)
[](https://scoop.sh/#/apps?q=%22https%3A%2F%2Fgithub.com%2FVincentZyuApps%2Fscoop-bucket%22&o=false)
[](https://aur.archlinux.org/packages/winload-rust-bin)
[](https://github.com/VincentZyuApps/winload/releases)
[](https://github.com/VincentZyuApps/winload/releases)
[](https://github.com/VincentZyuApps/homebrew-tap/blob/main/Formula/winload.rb)
> **[๐ Build Docs](.github/workflows/build.md)**
## ๐ 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](https://github.com/rolandriegel/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
```bash
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
```bash
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)
```bash
pip install winload
uv venv --python 3.13
uv pip install winload
uv run winload
uv run python -c "import shutil; print(shutil.which('winload'))"
```
## ๐ฅ Rust Edition Installation (recommended)
### npm (cross-platform)
```bash
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](https://github.com/features/packages) compatibility.
> Includes 6 precompiled binaries for x86_64 & ARM64 across Windows, Linux, and macOS.
### Cargo (Build from source)
```bash
cargo install winload
cargo install --list
```
### Windows (Scoop)
> ๐ [Scoop Bucket (GitHub)](https://github.com/VincentZyuApps/scoop-bucket/blob/main/bucket/winload.json)
> ๐ [Scoop Bucket (Gitee)](https://gitee.com/vincent-zyu/scoop-bucket/blob/main/bucket/winload.json)
```powershell
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 update # optional: manually refresh bucket list before install
scoop install winload
# execute bin file
win-nload
Get-Command win-nload # Powershell
where win-nload # CMD
```
> ๐ก Recommended: use [Windows Terminal](https://github.com/microsoft/terminal) instead of the legacy Windows Console for correct CJK character rendering and better TUI experience.
> ```powershell
> scoop bucket add versions
> scoop install windows-terminal-preview
> wtp
> ```
> ๐ก **All builds require Windows 10+** (Rust 1.77+ dropped Windows 7/8 support). Scoop and npm provide **MSVC + Npcap** for **x86_64** and **ARM64** by default. These builds now delay-load `wpcap.dll`, reducing startup failures before `--npcap` is used, but loopback capture still requires Npcap installed on the system. For other variants (MinGW, non-Npcap, i686), download from [GitHub Releases](https://github.com/VincentZyuApps/winload/releases).
### Arch Linux (AUR):
```bash
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)
```bash
curl -fsSL https://raw.githubusercontent.com/VincentZyuApps/winload/main/docs/install_scripts/install.sh | bash
which winload
```
> ๐ [View install script source](https://github.com/VincentZyuApps/winload/blob/main/docs/install_scripts/install.sh)
**๐จ๐ณ Gitee mirror (faster in China Mainland):**
```bash
```
> ๐ [View Gitee install script](https://gitee.com/vincent-zyu/winload/blob/main/docs/install_scripts/install_gitee.sh)
> โ ๏ธ The two `curl ... | bash` install scripts above support **x86_64 / aarch64** systems with **apt** (Debian/Ubuntu), **dnf** (Fedora/RHEL), or **Termux** (Android). For other platforms, use **npm** (`npm install -g @vincentzyuapps/winload`) or **Cargo** (`cargo install winload`) instead.
### macOS / Linux (Homebrew)
> ๐ [Homebrew Formula (GitHub)](https://github.com/VincentZyuApps/homebrew-tap/blob/main/Formula/winload.rb)
> ๐ [Homebrew Formula (Gitee)](https://gitee.com/vincent-zyu/homebrew-tap/blob/main/Formula/winload.rb)
```bash
brew tap vincentzyuapps/tap
brew update && brew install winload
which winload
```
> ๐ก Homebrew supports **macOS** (Intel & Apple Silicon) and **Linux** (x86_64 & ARM64).
<details>
<summary>Manual install</summary>
**DEB (Debian/Ubuntu):**
```bash
# Download the latest .deb from GitHub Releases
sudo dpkg -i ./winload*.deb
# or use apt (auto-resolves dependencies)
sudo apt install ./winload*.deb
which winload
```
**RPM (Fedora/RHEL):**
```bash
sudo dnf install ./winload*.rpm
which winload
```
**Or download binaries directly from [GitHub Releases](https://github.com/VincentZyuApps/winload/releases).**
</details>
## โจ๏ธ Usage
```bash
winload # Monitor all active network interfaces
winload -t 200 # Set refresh interval to 200ms
winload -d "Wi-Fi" # Start with a specific device
winload --title # Show "winload <version>" as the header title
winload --title "My Monitor" # Use a custom header title
winload --title "" # Keep the default device header
winload -e # Enable emoji decorations ๐
winload --npcap # Capture 127.0.0.1 loopback traffic (Windows, requires Npcap)
```
### Options
| `-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) | โ |
| `--title [TITLE]` | Add a title line above device header: no value shows `winload <version>`; empty string (or omitted) shows only the default device header | โ |
| `-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
| `โ` / `โ` 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](docs/win_loopback.md).
**To capture loopback traffic on Windows**, use the `--npcap` flag:
```bash
winload --npcap
```
This requires [Npcap](https://npcap.com/#download) 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](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
##### Terminal Recording
<a href="https://asciinema.org/a/1030894?startAt=30" target="_blank"><img src="https://asciinema.org/a/1030894.svg" alt="winload demo" width="100%" /></a>
> โ Recorded by [asciinema](https://github.com/asciinema/asciinema)
## ๐ฆ Dependencies
### Python Edition
| [](https://python.org/) | 3.13.11 | Programming language |
| [](https://github.com/giampaolo/psutil) | โฅ7.0 | Process and system utilities |
| [](https://github.com/zhirui2020/windows-curses) | โฅ2.0 | Windows curses support |
### Rust Edition
| [](https://www.rust-lang.org/) | 1.93.0 | Programming language |
| [](https://github.com/ratatui-org/ratatui) | 0.29 | Terminal UI framework |
| [](https://github.com/crossterm-rs/crossterm) | 0.28 | Cross-platform terminal library |
| [](https://github.com/GuillaumeGomez/sysinfo) | 0.32 | System information library |
| [](https://github.com/clap-rs/clap) | 4 | Command-line argument parser |
| [](https://github.com/pcap-parser/pcap) | 2 | Packet capture (optional, Windows) |