networksetup — macOS Network Configuration

What it is

networksetup is the macOS command-line front-end to the System Settings → Network pane and the underlying SystemConfiguration framework. It ships at /usr/sbin/networksetup with every macOS install and is the supported way to script configuration of Wi-Fi networks, Ethernet adapters, DNS resolvers, web/HTTP/SOCKS proxies, network Locations (named profiles), and the service order that controls which interface wins when more than one is up. It is the macOS equivalent of nmcli on Linux GNOME and a peer of the Windows netsh interface ip and netsh wlan contexts. Lower-level configuration (raw socket options, kernel routing) still lives in BSD tools — ifconfig, route, scutil, and ipconfig — but anything you can do in System Settings, networksetup can script.

Install

networksetup is part of macOS — there is nothing to install. Read operations work without privilege; write operations (setting DNS, switching locations, disabling a service) require sudo.

which networksetup
networksetup -version 2>&1 | head -1 || networksetup -listallnetworkservices | head -1

Output:

/usr/sbin/networksetup
An asterisk (*) denotes that a network service is disabled.

Syntax

networksetup takes a long flag (the verb) followed by its positional arguments. Read verbs start with -get* or -list*; write verbs start with -set* or -create*. Hardware ports (the BSD device name plus user-facing name like Wi-Fi or Ethernet) are distinct from network services (the same hardware bound into a particular Location).

networksetup -<verb> [<args>...]

networksetup -listallhardwareports
networksetup -getinfo "Wi-Fi"
sudo networksetup -setdnsservers "Wi-Fi" 1.1.1.1 9.9.9.9

Output: (none — exits 0 on success)

Essential verbs

Hardware ports vs network services

A hardware port is the physical adapter — Wi-Fi mapping to en0, Thunderbolt 1 mapping to en5, an Apple USB-C dongle showing up as en7. A network service is a hardware port bound into a particular Location with a specific configuration (DHCP vs static, DNS, proxies). Two services can use the same hardware port across different Locations, which is why scripts that touch network state name the service — not the BSD device.

networksetup -listallhardwareports

Output:

Hardware Port: Ethernet
Device: en5
Ethernet Address: a8:66:7f:1b:3e:01

Hardware Port: Wi-Fi
Device: en0
Ethernet Address: a8:66:7f:1b:3e:02

Hardware Port: Bluetooth PAN
Device: en6
Ethernet Address: a8:66:7f:1b:3e:03

Hardware Port: Thunderbolt Bridge
Device: bridge0
Ethernet Address: 5a:1a:2b:3c:4d:5e

networksetup -listallnetworkservices

Output:

An asterisk (*) denotes that a network service is disabled.
Wi-Fi
*Ethernet
iPhone USB
Bluetooth PAN
Thunderbolt Bridge

networksetup -listnetworkserviceorder

Output:

An asterisk (*) denotes that a network service is disabled.
(1) Wi-Fi
(Hardware Port: Wi-Fi, Device: en0)

(2) Ethernet
(Hardware Port: Ethernet, Device: en5)

(3) iPhone USB
(Hardware Port: iPhone USB, Device: en4)

The Linux equivalent of this taxonomy lives in ip and NetworkManager: ip link ↔ hardware ports, nmcli connection ↔ network services.

Reading a service's current configuration

-getinfo prints the active IPv4 address, subnet mask, gateway, plus DHCP/BootP/static flag, plus DNS resolvers in one block. Most scripts that swap DNS or proxy state read this first to know what they're about to overwrite.

networksetup -getinfo "Wi-Fi"

Output:

DHCP Configuration
IP address: 192.168.1.42
Subnet mask: 255.255.255.0
Router: 192.168.1.1
Client ID:
IPv6: Automatic
IPv6 IP address: fe80::1c7a:4f2d:3a8b:c1e9
IPv6 Router: fe80::1
Wi-Fi ID: a8:66:7f:1b:3e:02

networksetup -getmacaddress "Wi-Fi"
networksetup -getdnsservers "Wi-Fi"
networksetup -getsearchdomains "Wi-Fi"

Output:

Ethernet Address: a8:66:7f:1b:3e:02 (Hardware Port: Wi-Fi)
1.1.1.1
9.9.9.9
example.com
internal.example.com

When no DNS servers are explicitly set (i.e. the service is using whatever DHCP handed it), -getdnsservers prints the literal string There aren't any DNS Servers set on Wi-Fi. — scripts that parse the output must guard for this.

Wi-Fi

Wi-Fi support is split between networksetup (System Settings layer: power, joining, preferred-network list, profiles) and the deprecated airport private tool (raw scanning, channel info). For everything except scanning, prefer networksetup. The Wi-Fi device is typically en0 on Apple Silicon and en1 on older Intel models — confirm with -listallhardwareports.

# Power
networksetup -getairportpower en0
sudo networksetup -setairportpower en0 off
sudo networksetup -setairportpower en0 on

# Current SSID
networksetup -getairportnetwork en0

Output:

Wi-Fi Power (en0): On
Wi-Fi Power (en0): Off
Wi-Fi Power (en0): On
Current Wi-Fi Network: OfficeWiFi

Joining a network

-setairportnetwork joins a Wi-Fi network by SSID, prompting interactively for the password if one is not provided on the command line. Note that putting the password as an argv parameter exposes it to ps/ps aux for the duration of the command — prefer setting it via the keychain (System Settings → Network → Wi-Fi → … → Other Network → Show Password) and letting setairportnetwork look it up.

# Join with password on the command line (visible in ps!)
networksetup -setairportnetwork en0 OfficeWiFi 'sup3rsecret'

# Join from keychain (no password arg)
networksetup -setairportnetwork en0 OfficeWiFi

Output:

(none — exits 0 on success)

Preferred networks (the macOS "Known Networks" list)

networksetup -listpreferredwirelessnetworks en0

Output:

Preferred networks on en0:
        OfficeWiFi
        HomeNet5
        Conference
        eduroam

# Forget one
sudo networksetup -removepreferredwirelessnetwork en0 Conference

# Add one at index 0 (top of the list = highest auto-join priority)
sudo networksetup -addpreferredwirelessnetworkatindex en0 HomeNet5 0 WPA2 'homepass123'

# Wipe every preferred network (start over)
sudo networksetup -removeallpreferredwirelessnetworks en0

Output:

Removed Conference from the preferred networks list
Added HomeNet5
Removed all preferred wireless networks

Scanning nearby Wi-Fi

networksetup cannot list nearby networks — that capability historically lived in the private airport binary deep inside Apple80211.framework. Apple removed airport -s in macOS 14.4 (Sonoma) and the binary is gone entirely on Sequoia 15 and Tahoe 26. The recommended replacement is wdutil (privileged) or third-party scanners like WiFi Explorer. Additionally, on Sonoma 14 and later, the SSID/BSSID fields returned by networksetup, ioreg, system_profiler, and wdutil print as <redacted> unless the calling app holds Location Services permission.

# Modern Wi-Fi diagnostics dump (requires sudo)
sudo wdutil info | grep -A2 "WIFI"

# SSID redaction example — Tahoe 26 without Location Services grant
sudo wdutil info | grep -E "SSID|BSSID"

Output:

        SSID                 : <redacted>
        BSSID                : <redacted>

To unredact, grant Location Services to your terminal app in System Settings → Privacy & Security → Location Services, then re-run the command. The change applies to all of airport (gone), networksetup -getairportnetwork, ioreg -l | grep IO80211, and wdutil info.

Output (airport -s):

                            SSID BSSID             RSSI CHANNEL HT CC SECURITY
                      OfficeWiFi a8:66:7f:1b:3e:0a -53  36,80   Y  US WPA2(PSK/AES/AES)
                         HomeNet a8:66:7f:1b:3e:0b -71  6       Y  US WPA2(PSK/AES/AES)
                        eduroam  a8:66:7f:1b:3e:0c -64  149,40  Y  US WPA2(802.1x/AES/AES)
                        Hotspot  a8:66:7f:1b:3e:0d -82  11      Y  US WPA(PSK/AES/AES)

DNS

-setdnsservers overrides the resolvers DHCP would otherwise supply. The first positional argument after the service name is one or more IP addresses; pass the literal string empty to clear the override and revert to DHCP-supplied resolvers. macOS uses mDNSResponder as the system-wide resolver — after changing DNS, flush the cache so already-resolved names re-query.

# Override
sudo networksetup -setdnsservers "Wi-Fi" 1.1.1.1 9.9.9.9

# Revert to DHCP
sudo networksetup -setdnsservers "Wi-Fi" empty

# Read
networksetup -getdnsservers "Wi-Fi"

# Search domains
sudo networksetup -setsearchdomains "Wi-Fi" example.com internal.example.com
networksetup -getsearchdomains "Wi-Fi"
sudo networksetup -setsearchdomains "Wi-Fi" empty

# Flush DNS cache after changes
sudo dscacheutil -flushcache && sudo killall -HUP mDNSResponder

Output:

1.1.1.1
9.9.9.9
There aren't any DNS Servers set on Wi-Fi.
example.com
internal.example.com
There aren't any Search Domains set on Wi-Fi.

The macOS DNS resolution stack (scutil --dns) layers per-service overrides over DHCP-supplied defaults; you can inspect the full resolution table with:

scutil --dns | head -40

Output:

DNS configuration

resolver #1
  search domain[0] : example.com
  nameserver[0] : 1.1.1.1
  nameserver[1] : 9.9.9.9
  if_index : 4 (en0)
  flags    : Request A records, Request AAAA records
  reach    : 0x00020002 (Reachable, Directly Reachable Address)

resolver #2
  domain   : local
  options  : mdns
  timeout  : 5
  flags    : Request A records, Request AAAA records
  reach    : 0x00000000 (Not Reachable)

Proxies

macOS supports three independent proxy channels per service — HTTP (webproxy), HTTPS (securewebproxy), and SOCKS (socksfirewallproxy) — plus a PAC URL (autoproxyurl) and a bypass list (proxybypassdomains). Each can be toggled on/off without losing its configured host:port (-setwebproxystate ... off); this is how the GUI's "Use a proxy server" checkbox works.

# Configure an HTTP proxy
sudo networksetup -setwebproxy "Wi-Fi" proxy.example.com 3128

# With authentication
sudo networksetup -setwebproxy "Wi-Fi" proxy.example.com 3128 on alice 'sup3rsecret'

# Read back
networksetup -getwebproxy "Wi-Fi"

# Toggle off without forgetting the config
sudo networksetup -setwebproxystate "Wi-Fi" off

# Toggle back on
sudo networksetup -setwebproxystate "Wi-Fi" on

# Clear bypass list (hostnames that bypass the proxy)
sudo networksetup -setproxybypassdomains "Wi-Fi" \
  localhost 127.0.0.1 *.local *.example.com 169.254/16
networksetup -getproxybypassdomains "Wi-Fi"

Output:

Enabled: Yes
Server: proxy.example.com
Port: 3128
Authenticated Proxy Enabled: 1
localhost
127.0.0.1
*.local
*.example.com
169.254/16

PAC (auto-discovery)

A proxy auto-configuration file is a JavaScript document hosted at an HTTP(S) URL that returns the proxy directive (DIRECT, PROXY host:port, SOCKS host:port) per outbound URL. macOS supports both fixed PAC URLs and DHCP/DNS-based WPAD discovery.

sudo networksetup -setautoproxyurl "Wi-Fi" "http://wpad.example.com/wpad.dat"
networksetup -getautoproxyurl "Wi-Fi"
sudo networksetup -setautoproxystate "Wi-Fi" off

Output:

URL: http://wpad.example.com/wpad.dat
Enabled: Yes

Locations

A Location is a saved profile of network services and their settings. The pre-installed Location is named Automatic; create more (e.g. Office, Home, Cafe, VPN) to flip the entire stack — DNS, proxies, service order, even disabled services — with one command. This is the macOS-native answer to per-network DNS or "I'm at work today" scripts.

networksetup -listlocations
networksetup -getcurrentlocation

# Create a new location, populated from current config
sudo networksetup -createlocation Office populate

# Create a blank location (no services until you add them via System Settings)
sudo networksetup -createlocation VPN

# Switch
sudo networksetup -switchtolocation Office

# Delete
sudo networksetup -deletelocation VPN

Output:

Automatic
Office
Home

Automatic

Persisted location Office
Office

Service order and enabling

When more than one service is up, macOS uses the highest-priority service in the service order as the default route. -ordernetworkservices takes the complete ordered list of services (every service must appear exactly once); shorter forms are rejected. To prefer Ethernet over Wi-Fi:

networksetup -listnetworkserviceorder | grep "^("
# (1) Wi-Fi
# (2) Ethernet
# (3) iPhone USB
# ...

sudo networksetup -ordernetworkservices Ethernet "Wi-Fi" "iPhone USB" "Bluetooth PAN" "Thunderbolt Bridge"

# Now Ethernet wins when both are up.
networksetup -listnetworkserviceorder | grep "^("

Output:

(1) Wi-Fi
(2) Ethernet
(3) iPhone USB
(4) Bluetooth PAN
(5) Thunderbolt Bridge
(1) Ethernet
(2) Wi-Fi
(3) iPhone USB
(4) Bluetooth PAN
(5) Thunderbolt Bridge

Enabling and disabling services

A disabled service is greyed out in System Settings → Network and shows a * next to its name in -listallnetworkservices. Use this to "turn off" Bluetooth PAN or Thunderbolt Bridge entirely instead of letting them appear in the routing table.

sudo networksetup -setnetworkserviceenabled "Bluetooth PAN" off
sudo networksetup -setnetworkserviceenabled "Bluetooth PAN" on
networksetup -listallnetworkservices

Output:

An asterisk (*) denotes that a network service is disabled.
Wi-Fi
Ethernet
iPhone USB
*Bluetooth PAN
Thunderbolt Bridge

IPv4 mode: DHCP, manual, BootP, DHCP with manual IP

Every service has an IPv4 mode controlled by one of four verbs. -setdhcp and -setbootp take only the service name; -setmanual and -setmanualwithdhcprouter require explicit IP/mask/gateway.

# Static
sudo networksetup -setmanual "Ethernet" 192.168.1.42 255.255.255.0 192.168.1.1

# Back to DHCP
sudo networksetup -setdhcp "Ethernet"

# DHCP with a stable IP override (rare)
sudo networksetup -setmanualwithdhcprouter "Ethernet" 192.168.1.42

# BootP (legacy thin clients)
sudo networksetup -setbootp "Ethernet"

# Renew DHCP lease
sudo ipconfig set en5 BOOTP && sudo ipconfig set en5 DHCP

Output:

(none — exits 0 on success)

MTU and link speed

-setmtu adjusts the maximum transmission unit on an Ethernet adapter; the supported range is reported by -listvalidMTUrange. Jumbo frames (9000 bytes) require switch and cabling support end-to-end — set them blindly and you will see TCP throughput collapse rather than improve.

networksetup -getmtu en5
networksetup -listvalidMTUrange en5
sudo networksetup -setmtu en5 9000
sudo networksetup -setmtu en5 1500    # back to default

Output:

Active MTU: 1500 (Current Setting: 1500)
Valid MTU Range: 72 - 9000
(none — exits 0 on success)

networksetup vs Linux ip / nmcli

networksetup is the macOS analogue of a chunk of Linux's networking surface. The mental map below pairs each common task with the closest Linux equivalent so muscle memory transfers.

The Linux ip cheat sheet at sections/linux/ip covers the lower-level interface and routing primitives the macOS equivalent (ifconfig and route) maps to.

Common pitfalls

1. Service names are case-sensitive and may contain spaces — "Wi-Fi" not wifi. Quote them in scripts. -listallnetworkservices is the authoritative source.
2. -setdnsservers clears prior DNS when called with new IPs — there is no "add one DNS server" verb. Read the existing list, append, and pass the full new list.
3. Passwords on the -setairportnetwork command line leak into ps — anyone with ps aux can read them while the command runs. Pre-store the password in the keychain and omit the argument.
4. Service order changes affect every Location — wait, no: each Location has its own service order. If your script switches Location and then sets order, the order applies only to the Location you switched into.
5. -getdnsservers prints prose when nothing is set — There aren't any DNS Servers set on <Service>. is what you get back, not an empty list. Parse for that string.
6. DHCP override does not survive a Location switch — the override is stored per-service-per-location, so flipping Locations resets DNS to whatever that Location stored.
7. Disabling a service doesn't remove it from the order list — disabled services still appear in -listnetworkserviceorder, just with a *. Re-ordering requires naming all services including disabled ones.
8. MTU on a USB-C dongle resets on reconnect — these are transient services. Set MTU as part of a launch agent that fires on adapter arrival rather than once at boot.
9. PAC URLs that respond with text/html instead of application/x-ns-proxy-autoconfig are silently ignored — macOS will fall through to direct connections. Inspect the response with curl -I if the proxy isn't being used.
10. scutil --dns shows the resolver order, not what was set — multiple "resolver" blocks indicate split-DNS via VPN or per-domain rules. networksetup -getdnsservers only shows the manual override layer.

Real-world recipes

Toggle DNS between work resolvers and DHCP defaults

A common need: at the office your DNS is forced to an internal resolver; at home you want DHCP-supplied defaults so router-served LAN names resolve. This two-line pair of functions is what most engineers add to their ~/.zshrc.

# Add to ~/.zshrc

work_dns() {
  sudo networksetup -setdnsservers "Wi-Fi" 10.0.0.53 10.0.0.54
  sudo dscacheutil -flushcache && sudo killall -HUP mDNSResponder
}

home_dns() {
  sudo networksetup -setdnsservers "Wi-Fi" empty
  sudo dscacheutil -flushcache && sudo killall -HUP mDNSResponder
}

# Use
work_dns
home_dns

Output:

(none — exits 0 on success)

Bootstrap a Wi-Fi network from a CSV

For lab deployments — push a list of pre-shared Wi-Fi networks onto a fresh machine.

# wifi.csv  →  ssid,security,password
# OfficeWiFi,WPA2,sup3rsecret
# HomeNet5,WPA2,homepass

while IFS=, read -r ssid sec pass; do
  sudo networksetup -addpreferredwirelessnetworkatindex en0 \
    "$ssid" 0 "$sec" "$pass"
done < wifi.csv

Output:

Added OfficeWiFi
Added HomeNet5

"Presentation mode" Location: no proxy, no extra DNS, no power tricks

Create a Location that disables every proxy and DNS override so an external display + airdropped demo behave reliably.

# Create + switch
sudo networksetup -createlocation "Presentation" populate
sudo networksetup -switchtolocation "Presentation"

# Wipe overrides
sudo networksetup -setdnsservers "Wi-Fi" empty
sudo networksetup -setwebproxystate "Wi-Fi" off
sudo networksetup -setsecurewebproxystate "Wi-Fi" off
sudo networksetup -setsocksfirewallproxystate "Wi-Fi" off
sudo networksetup -setautoproxystate "Wi-Fi" off

# When done
sudo networksetup -switchtolocation Automatic

Output:

Persisted location Presentation
Persisted location Automatic

Per-domain split DNS via search domains

When you need certain hostnames (*.internal.example.com) to resolve through a VPN-supplied DNS while everything else uses DHCP defaults.

# Configure search domain on the VPN service (created by your VPN client)
networksetup -listallnetworkservices | grep -i vpn
sudo networksetup -setsearchdomains "Cisco AnyConnect Secure Mobility Client" internal.example.com
sudo networksetup -setdnsservers   "Cisco AnyConnect Secure Mobility Client" 10.0.0.53

# Confirm via scutil
scutil --dns | grep -A1 "search domain"

Output:

search domain[0] : internal.example.com
  nameserver[0] : 10.0.0.53

Detect captive portals and silence them

When networksetup joins a public Wi-Fi (cafe, hotel), Captive Network Assistant opens the login page. To suppress the popup and handle login yourself:

# Disable the captive portal helper system-wide
sudo defaults write /Library/Preferences/SystemConfiguration/com.apple.captive.control Active -bool false

# Re-enable
sudo defaults write /Library/Preferences/SystemConfiguration/com.apple.captive.control Active -bool true

Output:

(none — exits 0 on success)

One-shot "give me a working network" function

A diagnostic helper that prints the active service, its IP, gateway, DNS, and whether DNS resolves a known hostname.

netstat_quick() {
  local svc
  svc=$(networksetup -listnetworkserviceorder \
        | awk '/^\(1\)/{getline; print}' \
        | tr -d '()' | awk -F': ' '{print $2}' | head -1)
  echo "== Active service: $svc =="
  networksetup -getinfo "$svc"
  echo "DNS servers:"
  networksetup -getdnsservers "$svc"
  echo "Resolve check:"
  dig +short example.com
}

netstat_quick

Output:

== Active service: Wi-Fi ==
DHCP Configuration
IP address: 192.168.1.42
Subnet mask: 255.255.255.0
Router: 192.168.1.1
...
DNS servers:
1.1.1.1
9.9.9.9
Resolve check:
93.184.216.34

Cycle Wi-Fi without losing the SSID

A reliable "reset the radio" function that survives bad DHCP states.

wifi_cycle() {
  local dev=en0
  echo "Bouncing Wi-Fi on $dev"
  sudo networksetup -setairportpower "$dev" off
  sleep 2
  sudo networksetup -setairportpower "$dev" on
}

wifi_cycle

Output:

Bouncing Wi-Fi on en0
(none — exits 0 on success)

macOS Tahoe 26 — IKEv2 VPN algorithm deprecations

macOS Tahoe 26 drops support for legacy IKEv2 algorithms from the built-in system VPN importer: DES, 3DES, SHA1-96, SHA1-160, and Diffie-Hellman groups below 14 are no longer negotiable. VPN profiles that still specify those will fail to connect with a generic IKE negotiation error. Re-issue the profile with AES-GCM-256 / SHA-256 / DH group 14+ to restore connectivity. The deprecation also affects IKEv1 and L2TP/IPSec when they rely on the system importer; vendor clients (Cisco Secure Client, FortiClient, SonicWall GVC) ship their own crypto and are governed by their own update cadence.

# Inspect a configured IKEv2 service after upgrade
networksetup -listallnetworkservices | grep -i vpn
networksetup -getinfo "Corporate VPN"

# Watch the IKE negotiation log
log stream --predicate 'process == "neagent"' --info

Output:

neagent  IKE2: SA INIT failed: no proposal chosen
neagent  IKE2: peer offered DH=2; minimum required is DH=14

Tahoe 26.4.1 also patched a separate Wi-Fi join bug on M5 MacBook Air / M5 Pro/Max MacBook Pro where 802.1X enterprise networks failed when a content filter network extension was active. If you script Wi-Fi onboarding on those models, ensure the device is on 26.4.1 or later before running -setairportnetwork.

Backup and restore the entire network configuration

networksetup does not have a -export/-import pair, but the underlying preferences live in /Library/Preferences/SystemConfiguration/preferences.plist. Snapshot it before risky changes.

# Backup
sudo cp /Library/Preferences/SystemConfiguration/preferences.plist \
  ~/Backups/preferences.plist.$(date +%F)

# Restore (requires reboot to take effect)
sudo cp ~/Backups/preferences.plist.2026-05-24 \
  /Library/Preferences/SystemConfiguration/preferences.plist
sudo killall configd

Output:

(none — exits 0 on success)

Sources

What's new for enterprise in macOS Tahoe 26 — Apple Support NETWORKSETUP Command reference — ss64.com wifi-unredactor — SSID redaction on macOS Sonoma+ networksetup -getairportnetwork en0 is no longer working — Apple Community Goodbye, airport! — Intuitibits macOS Sequoia change breaks networking for VPN, antivirus software — BleepingComputer