wdutil for Troubleshooting Wi-Fi Issues on MacOS
Recently I wrote an article on how to use the netsh command to troubleshoot WiFi issues on Windows. Fortunately, macOS comes equipped with a similar option, for debugging Wi-Fi-related issues. This blog post will walk you through how to use wdutil to identify and resolve common Wi-Fi problems on macOS.
What is wdutil?
wdutil is a command-line tool included in macOS that interacts with the wireless diagnostics framework. It allows users to collect detailed logs, monitor Wi-Fi activity, and analyze network performance. This tool is invaluable for pinpointing issues like dropped connections, slow speeds, or interference.
To use wdutil, you need to have administrative privileges, as many of its commands require elevated permissions. You’ll also need to access it through the Terminal application.
Basic wdutil Commands
Here’s the usage information of wdutil:
$>wdutil -h
usage: sudo wdutil diagnose [-q] [-f outputDirectoryPath] -q may be specified to suppress legal prompt and Finder window sudo wdutil info sudo wdutil log [{+|-} {system|wifi}]+ sudo wdutil dump sudo wdutil clean sudo wdutil privateMAC={0/1}
Basic wdutil Commands
Out of all these options, the one I find more useful is is “sudo wdutil info”. The output on my laptop looks like this (abbreviated for readability):
$> sudo wdutil info
————————————————————————————————————————————————————————————————————
NETWORK
————————————————————————————————————————————————————————————————————
Primary IPv4 : en0 (Wi-Fi / 939E6FB9-6715-40A4-A3EA-BEF6049952CB)
: 192.168.86.41
Primary IPv6 : None
DNS Addresses : 192.168.86.1
Apple : Reachable
————————————————————————————————————————————————————————————————————
WIFI
————————————————————————————————————————————————————————————————————
MAC Address : <redacted> (hw=<redacted>)
Interface Name : en0
Power : On [On]
Op Mode : STA
SSID : <redacted>
BSSID : <redacted>
RSSI : -46 dBm
CCA : 18 %
Noise : -91 dBm
Tx Rate : 780.0 Mbps
Security : WPA3 Personal
PHY Mode : 11ac
MCS Index : 8
Guard Interval : 400
NSS : 2
Channel : 5g149/80
Country Code : US
Scan Cache Count : 57
NetworkServiceID : 939E6FB9-6715-40A4-A3EA-BEF6049952CB
IPv4 Config Method : DHCP
IPv4 Address : 192.168.86.41
IPv4 Router : 192.168.86.1
IPv6 Config Method : ? (9223372036854775807)
IPv6 Address : None
IPv6 Router : None
DNS : 192.168.86.1
BTC Mode : Off
Desense :
Chain Ack : []
BTC Profile 2.4GHz : Disabled
BTC Profile 5GHz : Disabled
Sniffer Supported : NO
Supports 6e : No
Supported Channels : 2g1/20,2g2/20,...,5g128/80,5g144/80,5g161/80
————————————————————————————————————————————————————————————————————
BLUETOOTH
————————————————————————————————————————————————————————————————————
Power : On
Address : 90:9C:4A:C3:EC:6B
Discoverable : No
Connectable : No
Scanning : No
Devices : 3 (paired=3 cloud=0 connected=0)…
————————————————————————————————————————————————————————————————————
AWDL
————————————————————————————————————————————————————————————————————
MAC Address : 66:1e:32:d7:d5:47 (hw=66:1e:32:d7:d5:47)
AirDrop Disc Mode : Contacts Only
AWDL Enabled : No
Interface Name : awdl0
Power : On…
Our focus here is the WiFi section, and as you can see it gives pretty detailed information about the signal strength, noise, Clear Channel Assessment (CCA), MCS index and others. Note that, by default, the MAC, SSID, and BSSID are redacted because they can be used to identify the user’s geographical location.
Part of this output is displayed if you hold the Option key and click the Wi-Fi icon in the menu bar.
In addition, wdutil gives information for the rest of the laptop’s wireless networks such as bluetooth, and the Apple Wireless Direct Link (AWDL), since they can be relevant to WiFi troubleshooting.
Collecting Diagnostics Data
The option that gives the most detailed diagnostics information is “sudo wdutil diagnose”. This might take several minutes to complete and the output looks like this (abbreviated for readability):
$> sudo wdutil diagnose -q ——————————————————————————————————————————————————————————————————————————————
Timestamp Name Duration Result Description ——————————————————————————————————————————————————————————————————————————————
Ping LAN 0.023 Yes Could ping router Ping LAN 0.019 Yes Could ping router
Ping LAN 0.018 Yes Could ping router
Ping LAN 0.023 Yes Could ping router
…
——————————————————————————————————————————————————————————————————————————————
Timestamp Name Duration Result Description ——————————————————————————————————————————————————————————————————————————————
Wi-Fi Link 0.001 Yes 15:56:17.298 Wi-Fi is associated to 'netbeez'
IPv4 Assigned 0.002 Yes 15:56:17.300 Wi-Fi has IPv4 assigned (router=192.168.86.1 ip=192.168.86.41)
IPv6 Assigned 0.001 No 15:56:17.302 Wi-Fi does not have IPv6 assigned
Primary IPv4 is Wi-Fi 0.004 Yes 15:56:17.305 en0 (Wi-Fi / 939E6FB9-6715-40A4-A3EA-BEF6049952CB) … /var/tmp/WirelessDiagnostics_C02D81K3ML85_2024-12-16_15.59.23.tar.gzThis command gathers detailed diagnostic data about your Wi-Fi environment. It’s useful for capturing logs when a problem occurs. The output is stored in the .tar.gz archive printed at the end of the execution. You can review these logs or share them with support personnel.
If you extract the archive and examine the contents you will see that it includes around 50 different files, such as arp.txt, traceroute.txt, ifconfig.txt and many others. For someone with some basic networking knowledge it is obvious what these log files contain. However, you probably need quite some digging if you are looking to troubleshoot an active issue.
Compared to the Windows WiFi troubleshooting utility netsh I find the MacOS approach much more detailed, but much less friendly. The Windows output includes an easily readable HTML page that makes it easy to read the key information over a period of days. There is always a tradeoff…
Part of the wdutil purpose is to generate the report and share it with Apple for troubleshooting purposes. My assumption is that Apple would have an automated parser to process and analyze the log files.
Conclusion
wdutil is a powerful yet underutilized tool for diagnosing Wi-Fi issues on macOS. Whether you’re dealing with dropped connections, slow speeds, or interference, this utility provides the data you need to identify and resolve problems.
Get your free trial now
Monitor your network from the user perspective