WiFi on bare Debian with systemd-networkd

The problem. A fresh Debian image on a Raspberry Pi, headless, with the network managed by systemd-networkd, no NetworkManager, and no desktop to fall back on. WiFi has to be brought up entirely by hand.

The fix.

First confirm the radio is even present:

ip link show wlan0

If wlan0 appears, the firmware is already there. Install the supplicant and write the network config, substituting your real network name and password:

apt install -y wpasupplicant
wpa_passphrase 'YOUR_SSID' 'YOUR_PASSWORD' > /etc/wpa_supplicant/wpa_supplicant-wlan0.conf
chmod 600 /etc/wpa_supplicant/wpa_supplicant-wlan0.conf

The filename matters. The wlan0 in it is exactly what the per interface service looks for. Start the supplicant for that interface:

systemctl enable --now wpa_supplicant@wlan0

Then create a network file for wlan0 at /etc/systemd/network/25-wlan.network with this content:

[Match]
Name=wlan0

[Network]
DHCP=yes

Restart networkd and confirm it associated and pulled an address:

systemctl restart systemd-networkd
networkctl status wlan0

Do all of this while still on a wired connection, so you can confirm WiFi works before you pull the cable.