How to make a custom keyboard layout in OS X?

1. Open Ukelele and choose File > New From Current Input Source. In new versions of Ukelele, it also assigns a new ID to the keyboard layout automatically.
2. Edit the keyboard layout.
3. Save the keyboard layout to some temporary location like the desktop. (Saving directly to /Library/Keyboard Layouts/ fails silently.) You can use either of the two formats. The iOS-style popovers shown when holding keys only work with the bundle format. The single XML file (default) format is simpler though. When using XML, make sure that the file is saved with a .keylayout extension.
4. Move the keyboard layout to /Library/Keyboard Layouts/. Keyboard layouts in ~/Library/Keyboard Layouts/ can't be selected in password dialogs or on the login window.
5. Restart the computer. Logging out and back in is not enough.
6. Enable the new keyboard layout from System Preferences.

To apply changes to a keyboard layout, run sudo touch /Library/Keyboard\ Layouts/ and restart.

See https://web.archive.org/web/20151030180252/http://osxnotes.net/keylayout-files-and-ukelele.html for more information.

---

Update (October 2015): There is a new version of Ukelele (3.0.0) that includes the option to install the layout from within the app. I still needed to go to system preferences to activate it, but did not need to go through the command line at all.

Creating the keyboard layout file

I too used Ukelele to generate a keyboard layout. You can then export the .bundle or .keylayout file and copy it to /Library/Keyboard Layouts.

sudo cp KeyboardLayout.keylayout /Library/Keyboard\ Layouts/

If you want to have the icon for the keyboard bundled in one file Ukelele offers an export to Bundle option. So in this case copy the .bundle file instead. Alternatively, you can keep the icons separate and copy them with the same name to the same folder.

sudo cp KeyboardLayout.icns /Library/Keyboard\ Layouts/

After a reboot you can add the input source in System Preferences->Keyboard->Input Sources menu. Probably available under Others or the language if you attached a language to the keyboard in Ukelele.

How to create an .icns file

mkdir layout.iconset

Then add the following PNGs to the folder:

# All sizes necessary
icon_16x16.png
[email protected]
icon_32x32.png
[email protected]
icon_128x128.png
[email protected]
icon_256x256.png
[email protected]
icon_512x512.png
[email protected]

You don't need all these, but this is the official list. Some are redundant in pixel count, but indicate density.

iconutil --convert icns --output layout.icns layout.iconset/

Example project on GitHub

My Ukrainian-Russian project on GitHub is a demo that is currently working on Mavericks 10.9.5.

Ukelele might work for you, just be warned that it seems to be rebinding keys at the software level (rather than hardware level), so you'll probably start running into issues like some apps not recognizing modifier or special key rebindings, not being able to use it in password dialogs, etc.

If you're looking for a more robust solution, check out Karabiner.