yslow 0.5.0

Diagnose why your network connection is slow

yslow

A command-line tool that diagnoses why your network connection is slow (or feels slow).

Instead of just reporting numbers, yslow isolates where the problem is — your local network (wifi/router), your ISP, or the broader internet — and tells you in plain language.

╻ ╻┏━┓╻  ┏━┓╻ ╻┏━┓
┗┳┛┗━┓┃  ┃ ┃┃╻┃ ╺┛
 ╹ ┗━┛┗━╸┗━┛┗┻┛ ╹

Is it slow?
● YES!

Why?
  ⚠ network no targets reachable (internet may be down) (1x, ongoing)
  ⚠ LAN     gateway unreachable (unusual routing setup) (1x, ongoing)
  ⚠ WiFi    very weak signal (too far from access point) (1x, ongoing)

Details
  WiFi:         -82 dBm (2.4 GHz), 6 Mbps TX, 6 Mbps RX
  LAN:          gateway 192.168.1.1 unreachable
  ISP/internet: all targets unreachable
  10.0.0.1:       3.0 ms cached,  45.0 ms uncached ✱
  Google DNS:    25.0 ms cached,  60.0 ms uncached
  OpenDNS:       35.0 ms cached,  42.0 ms uncached
  Cloudflare DNS:  9.0 ms cached,  40.0 ms uncached

What it checks

• Gateway latency — how fast your machine can talk to your router. High latency or jitter here points to wifi congestion, a bad cable, or an overloaded router.
• Internet latency — TCP handshake time to multiple well-known servers (Cloudflare, Google, OpenDNS).
• DNS resolution — cached and uncached lookup times for your configured resolver and public resolvers (Google, Cloudflare, OpenDNS). Flags slow resolvers and compares your configured resolver against public alternatives.
• Packet loss — at both the local and internet level.
• Jitter — variance in latency, which causes buffering, choppy calls, and inconsistent page loads.
• Wifi Signal Strength — how strong your wifi signal is.

Usage

uvx yslow              # one-shot check
uvx yslow -w           # continuous monitoring (every 30s)

Requires Python 3.10+. Works on Linux and macOS.

How it works

See docs/

Development

uv sync                  # install deps
./check.sh               # run all checks (format, lint, typecheck, tests)
uv run ruff check --fix  # lint
uv run ruff format       # format

Documentation

See docs/metrics.md for details on what yslow measures (RTT, packet loss, jitter, DNS), how each metric is calculated, and the thresholds used for diagnosis.

Planned

See TODO.md