Suppressing Keyboard Setup Assistant

Researching Keyboard Setup Assistant started as an exercise in suppressing it during a demonstration video of our Mac provisioning process. My findings quickly became part of that very provisioning process. 


macOS presents Keyboard Setup Assistant when it encounters an unknown 3rd party keyboard. The assistant guides the user to press a couple of keys on the unknown keyboard and guesses the keyboard’s type: ANSI (United States), ISO (European), or JIS (Japanese). If the user closes KSA when it appears, it chooses ANSI. KSA also appears if you attach a peripheral that acts as a keyboard, such as a barcode scanner or a security key. (Quite honestly, I find KSA to be an annoyance.)

Technical Details

KSA persists the keyboard’s type in /Library/Preferences/ (“the plist”). That plist contains a key named keyboardtype. In the keyboardtype dictionary, the key is an identifier and the value is an integer representing the type.

The identifier appears consistent across different Mac models and macOS versions. It is built from other identifiers found in IOKit. My Microsoft Sculpt Ergonomic (wireless) has an identifier of 1957-1118-0. 1957 is the ProductID. 1118 is the VendorID.

For the type, 40, 41, and 42 represent ANSI, ISO, and JIS respectively.

Discovering Keyboard Identifiers

When a keyboard’s identifier and corresponding type is known, it can be populated in the plist prior to KSA appearing.

The best way I found to discover the identifier and type was to was attach the keyboard to a clean test system.
First, discover the state of the plist. (It may not exist yet as it’s not in a default macOS install.)
    defaults read /Library/Preferences/
Attach the keyboard and complete KSA.
Read the plist again. There should be a new entry for the keyboard.


As mentioned above, it’s not just keyboards that trigger KSA. Keyboard-like devices such as barcode readers and security keys trigger it too. These types of device don’t have any keys to that KSA can use to detect the type. (One should just close KSA.) I realized that this research had a broader application at work where we use YubiKeys for MFA. By pre-populating the plist I could suppress KSA whenever we enroll a user’s new YubiKey. I gathered up all the YubiKey types we use and used the method above to learn their identifiers — only to discover they all had the same identifier.

The zsh script below is now part of our provisioning process. Other keyboards can be easily added as needed.


declare -A KEYBOARDS

KEYBOARDS[1031-4176-0]=40 # YubiKey
KEYBOARDS[1957-1118-0]=40 # Microsoft Sculpt Ergonomic
KEYBOARDS[219-1118-0]=40  # Microsoft Natural Ergonomic Keyboard 4000

for ID TYPE in "${(@kv)KEYBOARDS}"; do
    defaults write /Library/Preferences/ keyboardtype \
    -dict-add "$ID" -integer $TYPE

Leave a Reply

Fill in your details below or click an icon to log in: Logo

You are commenting using your account. Log Out /  Change )

Facebook photo

You are commenting using your Facebook account. Log Out /  Change )

Connecting to %s

Website Powered by

%d bloggers like this: