Contact Us


Initiative B@bel

WSI Guidelines


















Type Design


Design Tools



Font Downloads










Font FAQ



NRSI: Computers & Writing Systems


You are here: Input > Utilities
Short URL: http://scripts.sil.org/ukelele


Mac OS X Keyboard Layout Editor

John Brownie, 2014-03-08

Ukelele is a Unicode Keyboard Layout Editor for Mac OS X versions 10.2 and later. Version 2.0 and later are only for Mac OS X versions 10.4 and later.

Beginning with version 10.2 (Jaguar), Mac OS X supports an XML-based format for keyboard layouts (.keylayout files). These may be installed by copying them to the Keyboard Layouts folder within /Library or ~/Library; then they are enabled via the Input Sources (Input in 10.5 and earlier) tab of the Language & Text (International in 10.5 and earlier) module within System Preferences.

However, modifying keyboard layouts—let alone creating entirely new keyboard layouts, such as for a new script—by directly editing the XML text is tedious and error-prone.

Ukelele aims to simplify keyboard layout editing by providing a graphical interface to .keylayout files, where the desired characters can simply be dragged onto keys as needed. (The Character Viewer or Character Palette, available in the Input menu if it has been enabled in System Preferences, is a great place to find the characters.)

In addition to simple assignment of single character codes to keys, Ukelele can assign multiple-character strings and can create "dead keys", where a keystroke sets a new state that modifies the output of the following keystroke.

For more information about Mac OS X keyboard layouts, as well as existing layouts available for download, see Input Resources. For some types of layout, particularly with large numbers of dead-key sequences, creating a layout with the text-based tool KeyLayoutMaker may be a useful alternative.

Ukelele is written by John Brownie of SIL and is copyright ©2003-2014. This software is provided under SIL's standard  freeware license.

Latest Update

8 March 2014 — Released version 2.2.8

  • When creating a new key map as a copy of an existing map, the new key map had the same index as the old one, so the keyboard layout was invalid.


Latest release (universal binary, for Mac OS X 10.4 and later):

Ukelele 2.2.8
John Brownie, 2014-03-08
Download "Ukelele_2.2.8.dmg", Mac OS X disk image, 9MB [48292 downloads]

Previous stable release (universal binary, 1.8.4, 15 September 2009, Mac OS X 10.2 and later):

Ukelele 1.8.4
John Brownie, 2009-09-14
Download "Ukelele_1.8.4.dmg", Mac OS X disk image, 6MB [24100 downloads]


Feedback about the Ukelele tool is invited (see the Read Me file for contact information). This software is provided in the hope that it may be useful, but with no warranty, expressed or implied, and with no guarantee of support or future upgrades.

There is also a user forum at Google Groups, the Ukelele Users group, available at  http://groups.google.com/group/ukelele-users.


For support, either use the Ukelele Users Group ( http://groups.google.com/group/ukelele-users) or contact the author directly (contact details in the Read Me file on the Ukelele disk image).


9 January 2014 — Released version 2.2.7

  • When creating a new key map as a copy of an existing map, the selected index was off by one.
  • Updated the manual and help with reference to Mavericks.

18 November 2013 — Released version 2.2.6

  • Some user keyboard layouts cause the converter to fail when using New From Current Input Source, and that caused a crash in Ukelele 2.2.5. Now you will get an error message about the XML file being invalid. It would be better to use New Based On… and open the original XML file.

9 November 2013 — Released version 2.2.5

  • When creating a keyboard layout based on an existing keyboard layout or from the current keyboard input source, a random keyboard ID is generated.
  • New state names are validated to avoid some obscure problems (basically, don’t call a state “0” or “none”).

14 December 2012 — Released version 2.2.4

  • Code-signing should now be correct for Gatekeeper on OS X 10.8 (Mountain Lion).
  • Updated Ukelele Help.

1 October 2012 — Released version 2.2.3

  • Creating a new keyboard layout from the current keyboard input source was crashing on PowerPC machines due to the tool used being Intel-only. That tool is now a universal binary, so it should work correctly on PowerPC.

29 September 2012 — Released version 2.2.2

  • Fix a crashing bug when creating a new modifier combination and choosing a copy of an existing key map.
  • Ensure that you cannot create a dead key state with no name, which would cause the keyboard layout to be invalid and hence not usable.
  • Code-signed for Gatekeeper.
  • Toolbar buttons updated for high-resolution (Retina) displays.

20 June 2012 — Released version 2.2.1

  • There is a new option in the preferences to generate pre-10.5 compatible bundles. These should still work in 10.7 and later for “press and hold”.
  • Fixed a problem in the Save As Bundle dialog where the Save button was labelled inaccurately as Open.
  • The interface is partly adapted for high-resolution displays such as the Retina MacBook Pro. Text should appear sharp, but the toolbar buttons and other graphic elements such as icons are not yet converted for high-resolution display.

31 May 2012 — Released version 2.2

By saving a keyboard layout in a bundle, it will become compatible with the “press and hold” mechanism for entering diacritics, introduced in OS X 10.7 (Lion). For this purpose, an “intended language” can be supplied (default is the system language), which will determine which possibilities are offered in the pop-up. However, such bundles may not work with OS X 10.4 (Tiger) and earlier.

Change the colour themes to allow more choices. For each category of key (normal, dead key, selected) and state (up or down), the gradient type, colours and text colour can be set individually.

Automatically repair missing key maps when opening a keyboard layout, putting empty key maps with only the special keys defined.

Detect and repair an invalid keyboard ID when opening a keyboard layout, automatically generating a valid keyboard ID for the script specified in the keyboard layout.

Open files now remember the colour theme, keyboard type and zoom level after quitting Ukelele and restarting, as long as files are automatically reopened (Lion and later).

When editing output of a special key, there is now a button to insert the standard output automatically.

Updated the manual extensively to reflect recent changes and newer versions of OS X.

14 February 2012 — Released version 2.1.10

Restore a missing file which caused the button to add a modifier set to be invisible.

Further fixed the behaviour of adding a creation comment (in 2.1.9 it was adding a comment every time the file was opened).

Fixed some situations where the selected colour theme was ignored and the default theme was used.

3 February 2012 — Released version 2.1.9

Restore a missing file which caused colour themes not to work for most people.

Fix the print dialog extension (PDE) so that the Ukelele options in the print dialog now appear and work again.

New keyboard layouts now get the appropriate creation comment added.

Fixed some problems with adding comments.

21 October 2011 — Released version 2.1.8

Reenable the “New From Current Input Source” command when running in Mac OS X 10.7 (Lion), as there is a new version of the helper utility.

Add a preference to allow the user to choose whether to reopen the documents that were open when Ukelele was last quit. This only applies to Mac OS X 10.7 (Lion), and allows the new default behaviour (resume) or the old behaviour (the user’s choice of creating a new document, opening an existing document, or doing nothing).

Update the Unicode tables to the current draft of the Unicode Character Database, version 6.1. Note that this is a beta version, with the formal 6.1 specification due in February 2012.

Minor updates to the manual to reflect changes with Lion.

3 August 2011 — Released version 2.1.7

Disable “New From Current Input Source” when running in Mac OS X 10.7 (Lion), as it uses some helper utilities that do not run on Lion (they are PPC-only). It is still available on earlier versions of OS X.

7 June 2011 — Released version 2.1.6

Fix a bug that could lead to a new keyboard ID being set to 0 instead of the value in the dialog.

Show the default output for special keys in the status bar when editing a key within the window.

12 March 2011 — Released version 2.1.5

Write characters outside the Basic Multilingual Plane as hexadecimal values, to get around an apparent bug in Apple’s XML parser.

Now using Cocoa versions of the Inspector and Toolbox.

17 December 2010 — Released version 2.1.4

When a new modifier combination was added, it did not affect the display in the Ukelele window immediately. This is fixed so that it shows up properly.

6 December 2010 — Released version 2.1.3

Fix a crash when trying opening a keyboard layout within a bundle when either the bundle did not contain any keyboard layouts, no keyboard layout was chosen, or the cancel button was pressed.

24 November 2010 — Released version 2.1.2

Made some changes to the property list which may help with the problem of Ukelele appearing to claim non-Ukelele documents, particularly bundles.

12 November 2010 — Released version 2.1.1

Change the line endings to Unix line endings in the XML output file.

Improved formatting for XML files with multi-line comments.

30 October 2010 — Released version 2.1

Added a new preference which enables the user to choose to use a sheet dialog for editing key output on double-click (the previous behaviour, and the default) or edit in the same window.

Updated the Unicode database to version 6.0.

11 August 2010 — Released version 2.0.1

  • Corrected a problem which made keyboard layouts with no dead key states fail to work.

22 July 2010 — Released version 2.0

  • Corrected issues with French and Belgian keyboard layouts supplied with Ukelele which caused them not to open.
  • Made changes to the manual to better explain what is going on with control key combinations.
  • Improved a few error messages.

10 June 2010 — Released version 2.0b8

  • Fixed a bug that caused intermittent crashing when saving a file.
  • Fixed some problems with adding and deleting modifier combinations, some causing crashes, others creating keyboard layouts that could not be opened.

26 April 2010 — Released version 2.0b7

  • Fixed an issue with adding and deleting modifier combinations, which could lead to a keyboard layout that could not be used.
  • Implemented software update.
  • Found a work-around for keyboard layouts that have actions with an empty string for the id.
  • Updated the manual with a few fixes.

1 April 2010 — Released version 2.0b6

  • Replaced the colour options with a new preference panel, colour themes, which are now accessible from the View menu as well. Colour themes control all the colours of the keyboard, including background and text.
  • Updated the manual to incorporate changes since 2.0b1.
  • New feature to look up key strokes for a given output string. This is accessed from the Find item in the Edit menu.
  • Adjusted some code to prevent Ukelele producing a keyboard layout file that cannot be used by the operating system. Opening and saving a file should fix the problems in existing keyboard layouts.
  • Relaxed some restrictions related to using keyboard layouts with unusual key maps using base maps.
  • Created a user forum on Google Groups, Ukelele-Users.

9 February 2010 — Released version 2.0b5

  • Modified the code to save a file, hopefully avoiding a crash.

27 January 2010 — Released version 2.0b4

  • Instead of a black frame on dead keys, they are now a red colour, and the selected keys (for swapping keys) are framed.
  • The grey for printed keys that are down has been made a little lighter.
  • Support for opening files which are considered to be plain text has been re-enabled. Hopefully this solves problems in opening old files, without causing problems with saving them.
  • Key elements with empty output should be handle correctly now.
  • Symbols for non-printing characters should show up on non-standard keys.

25 January 2010 — Released version 2.0b3

  • Key colours are now user-configurable in preferences. Key up and key down have inner and outer colours, with a gradient from the outer colour at the corners to the inner colour in the centre of the key cap.
  • Key colours are swapped, so that the darker colour is now in the centre of the key, the lighter at the edges.
  • Crashes when moving from comment to comment have been fixed.
  • The problem solved in 1.8.4 with hand-edited files with gaps in numbering key maps has been solved in 2.0b3 as well.
  • Found a more robust solution for positioning text on the key cap.
  • A word of explanation about removing plain text support: This was only necessary for opening some old files, and was not a supported save format. Removing support avoids saving an unusable file.

20 January 2010 — Released version 2.0b2

  • Solved the problem of not launching on Mac OS X 10.4 (Tiger).
  • Changed the colour of the key caps to a darker blue, to increase contrast.
  • Moved the text down a bit on the key cap to provide more space for diacritics. This may not work all that well for different font sizes, and I will look at a more robust solution.
  • Printing now uses more printer-friendly colours — black on white, with no background colour, and grey highlights on modifiers that are down.
  • Fixed a crash if you clicked the “Create” button on the toolbar twice in a row.
  • Added QWERTZ as an option for new key maps.
  • Experimentally removed support for plain text files. If this causes problems opening files, then let me know.
  • Avoided creating empty action names, a potential problem.

15 January 2010 — Released version 2.0b1

  • Major rewrite, based on the Nano framework, meaning that it is restricted to Mac OS X 10.4 and later, but utilising many more modern features, such as sheets and drawers.
  • Redesigned interface, with a toolbar window and a drawer, bringing most elements into a single window.
  • The keyboard window is more scalable, allowing any value between 50% and 500%, including an option to fit the keyboard to the screen.
  • Printing is now implemented, with options of printing the keyboard layout with all dead key states and/or all modifier combinations.
  • Many interactions have been reworked, using a status bar to give instructions, leading to fewer dialogs that have to be navigated.
  • More information is now available about code points in the info inspector palette, based on the Unicode 5.2 standard.
  • Combining diacritics are now shown with a placeholder character, which is configurable in the preferences.
  • Comment handling is much improved, now handling all comments in the file, not just those at the beginning, and allowing comments longer than 255 characters.
  • New icons.
  • Support for bundles, so that keyboard layouts can be saved as bundles, or into existing bundles, optionally grouping the keyboard layout file with an icon file (usually the flag icon).
  • It is now possible to capture the current keyboard input source to create a keyboard layout. This allows easier conversion of older resource-based keyboard layouts, and use of the system’s keyboard layouts (which are no longer provided as XML as of 10.5, Leopard). Note that this facility requires Rosetta on Intel-based Macs.
  • The manual and tutorial have been rewritten to reflect the new version of Ukelele.

Notes from earlier releases can be found here.

Backlinks (20 most popular; affiliated sites and popular search engines removed)

© 2003-2015 SIL International, all rights reserved, unless otherwise noted elsewhere on this page.
Provided by SIL's Non-Roman Script Initiative. Contact us here.