A tmux plugin to run internet speed tests and display results in your status bar.
- Run speedtest with a single keypress (
prefix + oby default) - Non-blocking - tmux remains fully responsive while test runs
- Results persist in status bar until next test
- Clear results with a keypress (
prefix + Oby default) - Auto-detects available CLI (Ookla
speedtest,cloudflare-speed-cli,fast-cli, orspeedtest-cli) - Auto-scales units (Mbps/Gbps)
- Fully configurable format, icons, and key bindings
- Shows progress indicator while running
- Prevents multiple concurrent tests
- Color-coded results - configurable thresholds for good/warn/bad speeds and ping
- Auto-run on interval - schedule periodic tests automatically
- Detail popup - view full test results including server, ISP, jitter, and packet loss (
prefix + S)
One of the following speedtest CLI tools must be installed:
- Ookla Speedtest CLI (recommended)
- cloudflare-speed-cli (Cloudflare)
- fast-cli (Netflix's fast.com)
- speedtest-cli (Python)
Optional: jq for more robust JSON parsing (falls back to grep if unavailable).
Ookla (recommended):
# macOS
brew tap teamookla/speedtest
brew install speedtest
# Linux (Debian/Ubuntu)
curl -s https://packagecloud.io/install/repositories/ookla/speedtest-cli/script.deb.sh | sudo bash
sudo apt install speedtestcloudflare-speed-cli:
Works for both Intel and Silicon Macs.
Using Cargo:
cargo install --git https://github.com/kavehtehrani/cloudflare-speed-cli --features tuiUsing Homebrew:
brew tap kavehtehrani/tap
brew install cloudflare-speed-clifast-cli (Netflix fast.com):
npm install --global fast-cliNote: fast-cli requires Node.js 20+
speedtest-cli:
pip install speedtest-cli
# or
brew install speedtest-cliAuto-detection priority: Ookla → Cloudflare → fast-cli → speedtest-cli
Add to your ~/.tmux.conf:
set -g @plugin 'YousefHadder/tmux-speedtest'Press prefix + I to install.
git clone https://github.com/YousefHadder/tmux-speedtest ~/.tmux/plugins/tmux-speedtestAdd to ~/.tmux.conf:
run-shell ~/.tmux/plugins/tmux-speedtest/speedtest.tmux- Add
#{speedtest_result}to your status bar:
set -g status-right '#{speedtest_result} | %H:%M'
# or
set -g status-left '#{speedtest_result} [#S]'-
Press
prefix + oto run a speedtest -
Results appear in status bar:
↓ 250 Mbps ↑ 25 Mbps 15ms
| Key | Action | Option |
|---|---|---|
prefix + o |
Run speedtest | @speedtest_key |
prefix + O |
Clear results | @speedtest_clear_key |
prefix + S |
Detail popup (full results) | @speedtest_detail_key |
Add these to your ~/.tmux.conf before the plugin loads:
# Key binding (default: o)
set -g @speedtest_key 'o'
# Key binding to clear results (default: O)
set -g @speedtest_clear_key 'O'
# Key binding for detail popup (default: d)
set -g @speedtest_detail_key 'S'
# Output format (default shown)
set -g @speedtest_format '↓ #{download} ↑ #{upload} #{ping}'
# Icon shown while test is running (default: ⏳)
set -g @speedtest_icon_running '⏳'
# Icon shown when no result yet (default: —)
# Set to "" (empty string) to auto-hide the plugin when idle
set -g @speedtest_icon_idle '—'
# Speedtest provider: auto, ookla, fast, cloudflare, or sivel (default: auto)
set -g @speedtest_provider 'auto'
# Use specific server ID (default: auto-select, only works with ookla/sivel)
set -g @speedtest_server ''
# Enable/Disable notifications (default: on)
set -g @speedtest_notifications 'on'
# Timeout in seconds for each test (default: 120)
set -g @speedtest_timeout '120'
# Minimum time between tests (default: 0, disabled)
# Supports same syntax as @speedtest_interval (e.g., 30s, 5m, 1h30m)
set -g @speedtest_min_interval '0'
# Temporary backoff duration after provider rate-limit response (default: 10m)
# Use 0/off/disabled to disable automatic backoff
set -g @speedtest_rate_limit_backoff '10m'Run tests automatically on a schedule:
# Run a test when tmux starts (default: off)
set -g @speedtest_run_on_start 'on'
# Auto-run interval (default: 0, disabled)
# Supports: plain seconds (e.g., 3600), or units:
# - seconds: "30s"
# - minutes: "30m"
# - hours: "1h"
# - days: "2d"
# You can also combine units, e.g., "1h30m". Use "0", "off", or "disabled" to turn this off.
set -g @speedtest_interval '30m'Enable color-coded speeds and ping in the status bar based on configurable thresholds:
# Enable color coding (default: off)
set -g @speedtest_colors 'on'
# Speed thresholds in Mbps (values >= good = green, >= bad and < good = yellow, < bad = red)
set -g @speedtest_threshold_good '100'
set -g @speedtest_threshold_bad '25'
# Ping thresholds in ms (values <= good = green, <= bad and > good = yellow, > bad = red)
set -g @speedtest_ping_threshold_good '30'
set -g @speedtest_ping_threshold_bad '100'
# Custom colors (default: green, yellow, red)
set -g @speedtest_color_good 'green'
set -g @speedtest_color_warn 'yellow'
set -g @speedtest_color_bad 'red'| Placeholder | Description |
|---|---|
#{download} |
Download speed (e.g., 250 Mbps or 1.5 Gbps) |
#{upload} |
Upload speed |
#{ping} |
Latency (e.g., 15ms) |
Minimal:
set -g @speedtest_format '↓#{download} ↑#{upload}'With emoji:
set -g @speedtest_format '🌐 ⬇#{download} ⬆#{upload} 📶#{ping}'Compact:
set -g @speedtest_format 'D:#{download} U:#{upload} P:#{ping}'Nerd Fonts:
set -g @speedtest_icon_running ''
set -g @speedtest_format ' #{download} #{upload} #{ping}'If you're using catppuccin/tmux, create a custom module file:
~/.config/tmux/custom_modules/ctp_speedtest.conf:
# vim:set ft=tmux:
%hidden MODULE_NAME='ctp_speedtest'
set-option -gq "@catppuccin_${MODULE_NAME}_icon" ' '
set-option -gq "@catppuccin_${MODULE_NAME}_color" '#{E:@thm_teal}'
set-option -gq "@catppuccin_${MODULE_NAME}_text" '#(~/.tmux/plugins/tmux-speedtest/scripts/speedtest_status.sh)'
source-file -F '#{TMUX_PLUGIN_MANAGER_PATH}/tmux/utils/status_module.conf'Then in your ~/.tmux.conf:
# Source the custom module
source -F '#{HOME}/.config/tmux/custom_modules/ctp_speedtest.conf'
# Add to your status bar
# To auto-hide the module when idle (if @speedtest_icon_idle is empty), use conditional logic:
set -ag status-left "#{?#(~/.tmux/plugins/tmux-speedtest/scripts/speedtest_status.sh),#{E:@catppuccin_status_ctp_speedtest},}"
# Or just display it always:
# set -ag status-left '#{E:@catppuccin_status_ctp_speedtest}'Install one of the required speedtest tools (see Requirements).
Make sure #{speedtest_result} is in your status-right or status-left config, then reload tmux: tmux source ~/.tmux.conf
Check your internet connection. Try running speedtest, fast, or speedtest-cli directly in terminal to see detailed errors.
Use cooldown and backoff settings to reduce test frequency:
# Prevent tests from running too frequently
set -g @speedtest_min_interval '5m'
# If provider reports rate-limit, wait before retrying
set -g @speedtest_rate_limit_backoff '15m'
# During heavy config iteration, disable auto-runs temporarily
set -g @speedtest_run_on_start 'off'
set -g @speedtest_interval '0'The display-popup command requires tmux 3.2 or later. On older versions, the plugin automatically falls back to a split pane.
The Python speedtest-cli sometimes gets blocked by Speedtest.net. Use the Ookla CLI or fast-cli instead:
set -g @speedtest_provider 'ookla' # or 'fast'MIT