Make a custom keyboard layout the system default — even for the login screen

This works on OSX 10.9 Mavericks, with a keyboard layout that I created with Ukulele. Assuming that you have the layout already installed in your system, log into your account and make your custom keyboard layout active.

Open a terminal and run the following command:

cp /Library/Preferences/com.apple.HIToolbox.plist /tmp/

If you intend to use a text editor (e.g., TextWrangler) to make this change instead of XCode (which has a specialized graphical plist editor), also run:

plutil -convert xml1 /tmp/com.apple.HIToolbox.plist

Now, open /tmp/com.apple.HIToolbox.plist in the text editor or in XCode.

Throughout the file you will find several mentions of a KeyboardLayout ID key followed by an integer and KeyboardLayout Name followed by a string. Change these strings to the name of your custom keyboard layout and the id integers to the ID of your layout (the easiest way to find the right values is to compare with your user settings found in the file ~/Library/Preferences/com.apple.HIToolbox.plist.

Also the value of the key AppleCurrentKeyboardLayoutInputSourceID must be changed accordingly (probably to something like org.unknown.keylayout.NameOfYourLayout). Again you can find this value in your local preference file.

Once these changes are done, save the file and go back to the terminal. To play it safe, you can create a copy of the original com.apple.HIToolbox.plist file, just in case you made an error and need to roll back. For instance, to save a copy in your Documents folder:

sudo cp /Library/Preferences/com.apple.HIToolbox.plist ~/Documents

Then install your change with the following:

sudo sh -c 'cat /tmp/com.apple.HIToolbox.plist > /Library/Preferences/com.apple.HIToolbox.plist'

(It isn't necessary to convert your file back out of text form with plutil if you did so earlier.)

Exit the terminal, and restart the computer (logout is not sufficient: the file will not be reread). After restart, you should have your keyboard layout in the login screen.

NOTE: it's possible that it would have been enough to copy the file com.apple.HIToolbox.plist from ~/Library/Preferences/ to /Library/Preferences/, however in my case it has more entries, so I decided to play it safe and just modify the existing file.

I found this old MacWorld tip, that suggested running the Setup Assistant again:

sudo /System/Library/CoreServices/Setup Assistant.app\
/Contents/MacOS/Setup Assistant

At first I thought this wasn’t supported in Lion anymore as running this command didn’t seem to have any effect. Only after posting this question, I noticed there’s a typo in the command. The space characters need to be escaped properly, or the location of the binary needs to be quoted. For this reason, the tip I linked to doesn’t work.

Here’s the correct command:

sudo "/System/Library/CoreServices/Setup Assistant.app/Contents/MacOS/Setup Assistant"

Alternatively, this would work as well:

sudo /System/Library/CoreServices/Setup\ Assistant.app/Contents/MacOS/Setup\ Assistant

Another gotcha that wasn’t mentioned on the page I linked to: the custom keyboard layout needs to be installed in /Library/Keyboard Layouts/ (i.e. cd /Library/Keyboard\ Layouts), not ~/Library/Keyboard Layouts, for it to appear in the Setup Assistant’s keyboard layout selection screen.

Update: As of OS X 10.8, you’ll need to run an extra command (i.e. remove a file first):

sudo rm /var/db/.AppleSetupDone; sudo "/System/Library/CoreServices/Setup Assistant.app/Contents/MacOS/Setup Assistant"

Also, you will have to create a new user account in order to complete the Setup Assistant — but don’t worry, you can delete the new account afterwards.

This trick doesn’t work anymore in recent OS X 10.8 versions.

Update: Here’s everything I know about custom keyboard layouts on OS X.