Awesome Open Source
Awesome Open Source

Wifi Channel Watcher for GNU/Linux-based desktop environments

Monitor channel usage of neighboring routers / access points and get a desktop alert if your active channel is not optimal (has more than 1 user on it, other than you). Troubleshoot your wifi without lifting a finger!

Additional options:

  • Suggest a better, less congested channel
  • MAC address/BSSID lookups of neighbors - Useful when troubleshooting rogue access points or evil twin attacks
  • MAC address caching - No need to pull lookups from the internet when most neighboring routers are likely static
  • Enterprise access point lookup - Useful when you have several access points with the same SSID; reference a list of BSSIDs and easily set custom identifiers (see 'Full Detail' screenshot)

Better Channel Suggestion

Better wifi channel suggestion

Full Detail

Wifi channel warning - SSID, BSSID & Access Point Names

Without Custom Access Point Lookups

Wifi channel warning - SSID, BSSID & Access Point Names

Minimum Detail

Wifi channel warning - minimum detail


This script can be cloned and run manually, or added as a service that runs on a scheduled interval.

See detailed install instructions for built-in systemd user service options (no sudo/root needed).

  • After installing dependencies (most Gnome users may already have them), clone the repo to a directory on your hard drive.

    git clone

    That's it.

    You can manually run the script any time via command-line:



If you previously cloned this repo (prior to the version(s) mentioned, you'll have to add the new config variables to ~/.config/wifi-channel-watcher/config.conf in order for your existing config to be read by the script.

You can also simply delete the folder: ~/.config/wifi-channel-watcher and re-run the script to re-initialize setup (wipe existing config) to take effect, also.

Prior to v1.3.0

  • Add the following to your ~/.config/wifi-channel-watcher/config.conf file:
    These options move the channel selections from being hardcoded, to give the user greater control over what channels are considered or ignored.

Prior to v1.2.0

  • Add the v1.3.0 changes above
  • Add the new THRESHOLD variable to your ~/.config/wifi-channel-watcher/config.conf file:
    Threshold is the greater than or equal to value, for how many are on your channel (excluding you) before you get a notification.


All customizations are optional, in most cases, the script will work out of the box.

Get A Weekly Email With Trending Projects For These Topics
No Spam. Unsubscribe easily at any time.
Shell (232,512
Wifi (1,556
Gnome Shell Extension (228
Linux Desktop (203
Wifi Network (132
Related Projects