Automatic Wi-Fi Toggle for macOS

• When I connect my MacBook to a wired network, I'd like Wi-Fi to automatically turn off.
• When I disconnect my MacBook from all wired networks, I'd like Wi-Fi to automatically turn back on.

Sounds simple and obvious, but I couldn't find a tool to do this. I did find this gist by Albert Bori. In 2024 I took Albert's basic idea and wrote wifi-toggle.sh from scratch to be as simple to use as possible.

For the last couple of years there has been a steady stream of comments on the gist and a couple of forks adding features. This repo is an attempt to provide a central place to document and improve the script.

How it works

The script automatically discovers network hardware using macOS's built-in networksetup command. There is nothing to configure:

• Interfaces that support networksetup -getairportpower are treated as Wi-Fi.
• Other en interfaces are treated as wired interfaces.
• If any wired interface is active, Wi-Fi is turned off.
• When all wired interface are inactive, Wi-Fi is turned back on (but only if this script previously turned it off).

This supports multiple Ethernet adapters, docks, and Thunderbolt interfaces. *"Active" means the interface has an active link; it does not guarantee that the wired network has Internet access.

The script remembers when it turns Wi-Fi off. If you manually turn Wi-Fi off, it will respect that choice rather than turning Wi-Fi back on later.

Installation

Homebrew (macOS)

brew install adamshand/tap/wifi-toggle
wifi-toggle status
wifi-toggle on

You must run wifi-toggle on to enable automatic toggling. Do not use sudo.

To uninstall, stop the agent first (this also restores Wi-Fi if needed):

wifi-toggle off
brew uninstall wifi-toggle

Manual installation

Follow these instructions with your normal user account. The script will show an error if you run it as root.

1. Download wifi-toggle.sh and move it to a stable location outside Desktop, Documents, or Downloads. For example:

   mkdir -p ~/bin
   mv ~/Downloads/wifi-toggle.sh ~/bin/
   chmod 755 ~/bin/wifi-toggle.sh

2. If ~/bin is not in your $PATH, either add it to your path, add wifi-toggle.sh to another folder which is in your path, or use the full script path in the commands below.

3. Check the automatically detected interfaces:

   wifi-toggle.sh status

4. Check macOS notification settings in "System Settings > Notifications > Script Editor" and adjust as you prefer.

5. Test the toggle manually:

   wifi-toggle.sh run

6. Enable automatic toggling:

   wifi-toggle.sh on

   This installs and loads a service in ~/Library/LaunchAgents. From now on:

   • If any wired interface is active, Wi-Fi will automatically turn off.
   • When every wired interface is inactive, Wi-Fi will turn back on if the script disabled it.

7. To stop automatic toggling:

   wifi-toggle.sh off

   This unloads and removes the launchd service. If the script previously disabled Wi-Fi, it also restores Wi-Fi.

Running wifi-toggle.sh on again safely updates the launchd service. Do this after moving the script to a different location.

Upgrading

Homebrew:

brew update
brew upgrade wifi-toggle

The launch agent uses the new script the next time it runs. If release notes request a launch-agent update, run wifi-toggle on again.

Manual installation:

• Copy the new version of wifi-toggle.sh over the top of the old one (launchd will use the upgraded script the next time it runs).
• Run wifi-toggle.sh on to validate the installed service.

Usage

❯ wifi-toggle.sh help
Automatically toggle macOS Wi-Fi based on wired network status (uses launchd)

Usage: wifi-toggle.sh [ on | off | run | status | help ]
      on - start automatically toggling Wi-Fi (install launchd service)
     off - stop automatically toggling Wi-Fi (uninstall launchd service)
     run - toggle Wi-Fi now (also run automatically by launchd)
  status - show detected interfaces and launchd status
    help - show this help

The status command shows whether automatic toggling is enabled, every detected interface, and its current state:

❯ wifi-toggle.sh status
Automatic toggle: enabled
Installed script: /Users/adam/bin/wifi-toggle.sh
Installed service version: 2
Wi-Fi interfaces:
  en0: on
Wired interfaces:
  en4: active
  en5: inactive
Wi-Fi restore pending: yes

The run command is a good way to test behavior before enabling the launchd service. Debug output explains which interfaces were detected and whether Wi-Fi needs to change:

❯ wifi-toggle.sh run
DEBUG: Wi-Fi interfaces: en0
DEBUG: wired interfaces: en4 en5
DEBUG: wired interface en4 is inactive
DEBUG: wired interface en5 is inactive
DEBUG: all wired interfaces are inactive; Wi-Fi was not disabled by this script

Troubleshooting

• First run wifi-toggle.sh status, followed by wifi-toggle.sh run. Errors from automatic interface discovery or Wi-Fi control will be shown directly.

• Inspect the loaded launchd service with:

  launchctl print gui/$(id -u)/nz.haume.wifi-toggle

• Validate the installed launchd file with:

  plutil -lint ~/Library/LaunchAgents/nz.haume.wifi-toggle.plist

• The script requires permission to write to ~/Library/LaunchAgents. It creates that directory automatically when necessary.

• macOS may quarantine a script downloaded through a browser. If you downloaded the file from this repository and receive an Operation not permitted error, move it outside Desktop, Documents, and Downloads. If necessary, remove its quarantine attribute:

  xattr -d com.apple.quarantine ~/bin/wifi-toggle.sh

• Do not run the script as root. A per-user launchd agent must be installed by the user it belongs to.

• If a wired link is active but has no Internet access, the script still considers it active and turns Wi-Fi off. Disconnect that interface or disable automatic toggling with wifi-toggle.sh off.