You are here: Input > Utilities
Short URL: http://scripts.sil.org/ukelele
Mac OS X Keyboard Layout Editor
Ukelele is a Unicode Keyboard Layout Editor for Mac OS X versions 10.2 (Jaguar) and later. Version 2.0 through 2.2.8 are only for Mac OS X versions 10.4 (Tiger) and later. Version 3.0 and later require Max OS X 10.8 (Mountain Lion) or 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 folder within or ; then they are enabled via the ( in 10.5 and earlier) tab of the ( in 10.9 and earlier, in 10.5 and earlier) module within .
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 or , available in the Input menu if it has been enabled in , and shown with , 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-2016. This software is provided under SIL's standard freeware license.
25 August 2016 — Released version 3.1b1
This release, the first beta release of Ukelele 3.1, includes some new or reworked features and several bug fixes.
- Reworked the code to display the output of a key. It now should look correct with multiple diacritics, though clipping may occur.
- When changing the scale of the keyboard view, the output also changes scale.
- Add a button to remove the language attribute of a keyboard layout.
- Update terminology from bundle to collection.
- Fix a bug that made the scale combo button show the wrong value.
- Work around a bug that caused a crash when the pointer was over a key that had a non-ASCII character in the information (such as $).
- Deleting the last keyboard layout in a collection and trying to undo the deletion caused a crash. Fixed.
- Change the New Keyboard Layout behaviour to offer choices in the base layout, caps lock and command modifier combinations, as in a new standard keyboard layout in a collection.
- The display now updates correctly after changing the modifier combinations.
- Updated and extended the tutorial, which is now a PDF document rather than HTML.
- Since changing the output of the F-keys (F1 through F19) was of no use, the F-keys are no longer editable.
- When a user tries to edit the output of a special key the first time, a warning dialog is presented to offer alternatives.
- Updated the manual.
Latest release (for Mac OS 10.8 and later):
Current stable release (3.0.5, 8 August 2016, for OS X 10.8 and later):
Previous stable release (universal binary, 2.2.8, 8 March 2014, for Mac OS X 10.4 and later):
Older stable release (universal binary, 1.8.4, 15 September 2009, Mac OS X 10.2 and later):
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).
8 August 2016 — Released version 3.0.5
This release of Ukelele fixes several bugs.
- Buttons and menu items are enabled only as appropriate when a keyboard layout collection contains no keyboard layouts.
- Importing a dead key did not work, with various ways that it could crash. These have been fixed, so it should be working as expected now.
- When opening a keyboard layout, some checking is done to identify and report some errors that might arise with keyboard layouts that have had the XML file directly edited (in a text editor, not in Ukelele).
- Updated the Unicode database to version 9.0.0.
- Disable deleting a modifier combination if it’s the only one defined.
- When adding a new key map, the dialog now picks the empty key map as the default, rather than whatever was previously chosen, which wasn’t working correctly.
- If a keyboard layout collection had internal folders named without normal capitalisation, Ukelele would report that the bundle was invalid. This has been fixed.
10 June 2016 — Released version 3.0.4
This release of Ukelele fixes several bugs.
- Fixed issues of printing and saving with keyboard layouts not part of a keyboard layout collection.
- Drag and drop of modifier combinations now works correctly.
- Creating a new key map as a copy of an existing key map produced an invalid keyboard layout. This has been fixed.
- The remove button for modifier combination sets is enabled appropriately.
- Fixed the symbol for the help key.
30 March 2016 — Released version 3.0.3
This release of Ukelele fixes a bug and updates some features.
- Updated Sparkle (automatic update support) to version 1.14.0. This removes some issues. Ukelele was never susceptible to the http flaw, as it has always used https for updates.
- Updated Boost (utility framework) to version 1.60.
- Preferences were not being updated correctly, making some impossible to change (particularly the keyboard type). This has been fixed.
- The XML output has been tweaked so that attributes now appear in the order that you would expect. In theory, this makes no difference, but it does make the XML easier to understand for a human reader.
- Updated the manual in various places, including more explanation of unlinking, of creating keyboard layouts with different key maps for command and/or caps lock keys, and an updated list of the languages supported by Apple for Press and Hold.
- Updated to the latest version of the Language Subtag Registry.
14 January 2016 — Released version 3.0.2
This release of Ukelele fixes a bug and introduces some new features.
- When double-clicking a key, sometimes the output would appear as doubly encoded XML (e.g. &#x001e; rather than ). This has been fixed.
- All of the sample keyboard layouts have been converted to Unicode rather than other scripts.
- You can now remove an icon or language for a keyboard layout in a keyboard layout collection.
- Removed some unused code and cleaned up some other internal things to make preparation for some future features.
- Keyboard IDs are now set automatically, so that they will always match the selected script, and the user is never asked to set the ID, though it can be seen in the inspector window.
15 December 2015 — Released version 3.0.1
This is a bug-fix release of Ukelele.
- When running on a recent Mac (iMac 5K, MacBook 12", possibly others), Ukelele didn't recognise the keyboard type, and showed a blank keyboard window. Try to change the keyboard type from the View menu also failed. In these cases, Ukelele will use a default keyboard type.
20 October 2015 — Released version 3.0.0
This is the first full release of version 3.0, after the beta testing period has finished.
- Corrected the problem that the alias to the Keyboards Layout folder did not work as expected. This also resulted in a smaller file size for the created disk image.
- The name of the keyboard layout collection or keyboard layout is now suggested as the initial name for the disk image..
14 October 2015 — Released version 3.0b6
- A new feature has been added, to create a disk image for distributing keyboard layouts. The disk image has the keyboard layout collection (or plain keyboard layout) and an alias to the Keyboard Layouts folder in Library, which allows the user to drag and drop the keyboard layout (collection) to install.
- Temporary files created when creating a keyboard layout from the current keyboard input source are now cleaned up, rather than leaving them to be removed on the next system reboot.
2 October 2015 — Released version 3.0b5
- There were issues when starting Ukelele without any previous documents open, leading to a non-functional keyboard layout window. This has been fixed.
- When opening a keyboard layout not in a collection, two windows would be opened. This has been fixed.
- If Ukelele’s preferences had an old colour theme name, but there was no colour theme with that name present, the keyboard layout window would be black. Ukelele will now use the Default colour theme in this situation.
- Changed the menu item from just “New” to “New Keyboard Layout Collection” to make it clearer what would be created.
- Assorted internal changes for compatibility with Xcode 7’s compiler.
21 September 2015 — Released version 3.0b4
- When saving a keyboard layout collection (a bundle), the file names of the files for the keyboard layout(s) included in the collection have their names set so that they are consistent with the keyboard layout name. This is necessary for the language of the keyboard layout to be recognised by the system.
- Bundle identifiers had two dots in a row, and this has been fixed.
10 September 2015 — Released version 3.0b3
- Colour themes are now available again, with an editor so that you can change or create themes.
- Earlier betas implemented pasting a key incorrectly, which led to the keyboard layout being invalid, so that it could neither be used nor opened by Ukelele. This has been fixed.
- Trying to install a keyboard layout that had not been saved caused a crash. A warning is now shown, asking the user to save the keyboard layout before installing it.
- Some fixes were made to show error messages correctly.
- When an invalid keyboard layout was in a bundle, error messages were generated multiple times. Now only one error message will be shown, and Ukelele will not attempt to open it again.
- The manual was updated to include the colour theme editor.
3 August 2015 — Released version 3.0b2
- A change was made so that Ukelele should work successfully on systems running OS X 10.8 (Mountain Lion).
- An error in the XML generated by Ukelele 3.0b1 caused the system to reject keyboard layouts. This has been fixed.
- The preferences to change the default theme from Default to Print failed to work. It now works as expected.
- Text in key caps for small sizes (such as function keys and arrow keys on MacBook models) was positioned too high, and the top was cut off in print view. This has been repositioned.
- When changing output of a key using the popover (default, rather than sheet), the input text is accepted if the user clicks outside the popover, not just when the Done button is clicked or the user presses the return key. As the change can always be undone, this was seen as more in keeping with Apple’s guidelines.
27 July 2015 — Released version 3.0b1
- Ukelele 3.0 is a completely new version, rewritten almost entirely apart from the core code that handles the actual keyboard layout structure.
- Ukelele uses the new document model introduced by Apple. This means that all changes are automatically saved rather than having to be saved by the user. To create a new document, choose Duplicate from the File menu, give a new name, and save to the new location.
- The preferred document format is now the keyboard layout collection, which is also referred to as a bundle, after the way that it is packaged. Keyboard layout collections can contain one or more keyboard layouts, with optional icons and intended languages for each of them.
- The main keyboard layout window now uses a tabbed interface rather than having a drawer for the modifiers and the (somewhat confusing) comments view.
- Ukelele now has the capability to install keyboard layouts itself. You can install for yourself, or for all users on your computer, without having to save the keyboard layout and drag it into the correct folder in the Finder.
- Some interactions have been simplified by introducing the idea of selecting a key and then operating on it. So, for example, you could select a key and then turn it into a dead key with a single click and a single dialog.
- Ukelele provides a Quick Look capability, giving you a way to see a keyboard layout from the Finder.
- A concept of “simplified modifiers” has been introduced. Since no current Apple keyboard, or any Cocoa-based application, distinguishes between left and right shift, option or control keys, treating them all as the left modifier key, it is only worthwhile using left keys. Ukelele can simplify the modifier combinations defined by a keyboard layout to eliminate use of separate left and right modifier keys. This makes the modifier combinations easier to understand, without losing anything in current Apple systems.
Editing key output is now done with a popover, hopefully an easier way to do it.
- The inspector window has been redesigned with a tabbed interface. New information fields include which modifiers are currently active and which modifier set they match.
- When creating a new keyboard layout, you have a wider choice of standard keyboard layouts: QWERTY, AZERTY (French), QWERTZ (German), Dvorak and Colemak. Also, you can create a keyboard layout that combines two or three, with the command and/or caps lock key switching between them.
- Many dialogs have been redesigned, sometimes combining two or more in a series so that an interaction is completed in a single dialog.
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.
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.
© 2003-2016 SIL International, all rights reserved, unless otherwise noted elsewhere on this page.
Provided by SIL's Non-Roman Script Initiative. Contact us here.