I recently moved to OS X and I find the system "Russian Phonetic" layout unsatisfying (it's not the one that I'm used to). How can I create a custom layout?

I've read about Ukelele, but the layout I created and copied to Library/Keyboard Layouts doesn't show up in Keyboard Preferences.

I'm using OS X 10.9 Mavericks. I searched for solutions in internet, but most of them were outdated.


4 Answers 4

  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.

  • 1
    Thank you! I have one important note, though: XML files saved by Ukelele need to have .keylayout extension. This way it worked :)
    – mik01aj
    Oct 29, 2013 at 0:09
  • Using the bundle format allows one to put an .icns icons file inside the bundle (same location as .keylayout) and an icon of choice can appear next to the input source. (Ukelele can add an icon to the bundle through the menu. You do need an .icns).
    – ebukva
    Jan 23, 2014 at 4:24
  • 1
    You can also add an icon for an XML keylayout file by for example saving the icns file as /Library/Keyboard Layouts/My Keyboard Layout.icns.
    – Lri
    Jan 26, 2014 at 9:25
  • instead of saving it somewhere and moving it manually, you can start ukelele as root so that it can directly save to /library/keyboard layouts
    – Rayjax
    Oct 24, 2014 at 9:22
  • 1
    Somehow the system-wide install with Ukulele failed in my case. Instead I copied the whole bundle to /Library/Keyboard\ Layouts and then ran sudo touch /Library Keyboard\ Layouts. No need to restart or relogin. Aug 18, 2018 at 7:07

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.

Input Source Menu

How to create an .icns file

mkdir layout.iconset

Then add the following PNGs to the folder:

# All sizes necessary
[email protected]
[email protected]
[email protected]
[email protected]
[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.

  • 2
    +1 for the Ukrainian-Russian project link. Sharing it with some mates now. Thanks, man! Dec 1, 2014 at 15:46
  • You're very welcome! Dec 2, 2014 at 9:32
  • 1
    Very much +1 for the Ukrainian-Russian project link. We support you, @CameronLowellPalmer (and others)! Jun 27, 2015 at 19:47

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.

  • Karabinier is also better because you don't have to copy configuration file, it is directly working. And you can enable it at starting in misc / system default configuration
    – bormat
    Oct 3, 2018 at 4:41

Use older stable Ukelele version 1.8.4... No restart necessary

I have OS X 10.10.5 (Yosemite). Ukelele's current version did not work even after I tried several other suggestions. Finally I uninstalled the current version and installed the older stable version (1.8.4). After that it worked just fine. No restart was necessary. Just save the new layout within Library/Keyboard Layouts. Then open keyboard preferences, input sources. Add by clicking the +, and you should see the new layout in 'Others'.


You must log in to answer this question.

Not the answer you're looking for? Browse other questions tagged .