A guide to using Ukelele
In this article you’ll create a custom keyboard layout for Mac OS that you can use to enter special Unicode characters or unsupported languages.
Mac OS offers a lot of language options and keyboard layouts out of the box. You can find them by going to System Preferences > Keyboard > Input Sources. Then click the + plus button to add another one.
However, if you speak a minority language or need some other special purpose keyboard, you may not be able to find it.
As a case in point, I’m teaching an English phonetics class this term, and while online keyboards like ipa.typeit.org work fine, I need a more convenient solution to type the International Phonetic Alphabet (IPA) directly on my computer. I also need another keyboard to write traditional Mongolian script, which isn’t included in the Mac OS supported keyboard list.
Creating a custom keyboard
Follow along with me as I make my IPA keyboard. You can adjust the steps to meet your own needs.
Find the Unicode symbols
Your keyboard will be inputting Unicode characters, so first of all you should gather the characters that you’ll need. Here are some places that you can do that:
- Character Viewer (preinstalled app on Mac OS)
- Official Unicode site (find by language block)
- Unicode Lookup (find codes by cut and paste)
- Unicode Character Recognition (find characters by freehand drawing)
- Unicode search (find characters by category or by describing them)
- Unicode code converter (find code numbers for Unicode characters)
For me, ipa.typeit.org has most of the special characters that I need:
Download Ukelele from the official site and install it.
When you open it the first time it should look something like this:
Create a new keyboard layout
This article will teach you to make a new keyboard layout completely from scratch. Although opening an existing keyboard and editing it may be a faster way to get a finished product, it can be more complicated to understand when making a keyboard layout for the first time.
In the menu choose File > New Keyboard Layout.
You’ll get a popup asking you to name your layout. Since I’m making an IPA keyboard I’ll name mine IPA. I want to start from scratch, so I’m choosing Empty as the base keyboard layout. I want Command shortcuts like Cmd+C to still work, so I’ll choose QWERTY for the layout with the command key.
Press OK to create your layout.
Then in the menu choose File > Save and save it as ipa.keylayout in a location of your choice. You’re saving it now to ensure you don’t loose your work later.
Note: You can also save as a Bundle, but this isn’t necessary unless you want to do more advanced things like add an icon. For this first keyboard layout we’ll just use the basic .keylayout extension, which is an XML file.
You can close the original Ukelele window that was showing when you first opened the program. Just keep open the IPA keyboard layout that you just created.
Double-click a key to edit it
The way to enter a value for a key is to double-click it.
Start by double-clicking what would be the a key on most keyboards and then pasting in the IPA ɑ value that I collected earlier:
Press the Done button to save your change. Your key should now look like the following:
You may notice that single-clicking a key or pressing a key on your keyboard highlights the key in Ukelele. That doesn’t matter. You can click or press the key again to deselect it. Pressing Shift or Command or one of the other modifier keys will turn it green. You’ll be doing that later.
If you want to enter a character by its Unicode value rather than pasting it in, you can do that by entering the value in XML format. For example, the Unicode hex value of
0251. To put that in XML format you would write it like so:
That is, prefix the value with
&#x and end it with
;. (If you’re using decimal rather than hexadecimal, then leave off the
x.) Here is what it looks like entering the hexadecimal value:
Repeat for all the empty keys
Double-click all of the empty keys on the keyboard to give them a value. I’m using the following values:
Row 1: ` eɪ aɪ aʊ ɔɪ oʊ ɜː ɑr ɛr ɪr ɔr ‿ =
Row 2: ə w ɛ r t ʊ u i o p [ ] \
Row 3: ɑ s d f g h j k l ː ˈ
Row 4: z ɝ ʧ v b n m ˌ . /
Row 5: (space)
Note: Don’t forget to add a space to the space bar key!
Save your work with File > Save. The layout looks like this now:
I don’t really care about the keypad on the right but if you wanted to be complete you could fill it with values like this:
Adding more values using modifier keys
There are still more Unicode values that I want to add but the keyboard is already full. The primary way to add more values is to use the modifier keys. These include Shift, Option, Command, Control, and Caps Lock. Use Shift and Option as your first choice since Command may be used for various shortcuts on your computer.
For the IPA keyboard I’m making, I’ll be able to get all the characters I need just using Shift. However, you could use Option or Shift+Option to get even more ways to enter characters if you need that many.
Press Shift now. You’ll notice that the Shift buttons on your Ukelele layout turn green and that all of your other key values disappear:
With the Shift key held down, double-click an empty key to add a value to it. I’ll add the character æ to what would be a capital A on a normal English QWERTY keyboard.
When the keyboard layout is finished, this will allow me to enter æ by pressing the Shift key in combination with that key.
Repeat for all remaining characters using modifiers
Holding down Shift and double-clicking empty keys, add all the remaining characters you need.
There are the characters I still need to add:
Row 2: ʍ e ɾ θ ʊ ɪ ɔ
Row 3: æ ʃ ð ʰ ɫ
Row 4: ʒ ɚ ʤ ʌ ŋ ʔ
After filling those in, the keyboard with the Shift modifier looks like this:
There are a number of blank keys that don’t have anything, but that’s OK with me since they are just Shift modifier keys.
Save your work again with File > Save.
Install the keyboard
There are a few steps you need to do to install the keyboard.
In Ukelele go to File > Install > Show Organizer. You should see your keyboard in the left column.
Right-click the ipa keyboard item and choose Install for Current User:
You’ll get the following warning. Choose Close.
As the warning says, you shouldn’t edit the file after you’ve installed it. Installing for the current user moved
ipa.keylayout to the hidden folder
Library/Keyboard Layouts in your home directory. You can view hidden folders and files in Finder by pressing
Log out and log in
As Ukelele recommends, log out of your current Mac user session and then log back in again. Alternatively, restart your computer.
Add your keyboard as an input source
Like you saw at the beginning of this article, go to System Preferences > Keyboard > Input Sources. Then click the + plus button to add another one.
Scroll down and choose Others from the list on the left. Then choose the IPA keyboard on the right. Finally, press the Add button.
Note: If you want to associate your keyboard with a specific language, then you need to create a collection bundle rather than a single keylayout file.
Choose your keyboard
As long as you have the input source showing in your toolbar, you can switch keyboard layouts by selecting the icon. Choose IPA from the list:
naʊ ju kæn raɪt wɪθ jɝ nu kibɔrd!
Updating your layout
You will probably discover that you want to make a few changes after you’ve finished your keyboard. For example, in that last line of the section above I had to switch keyboards in order to enter the
!. It would be nice to add a little punctuation back into that keyboard.
Uninstall the current keyboard layout
Open Ukelele and go to View > Show Organizer.
Then right-click ipa and choose Uninstall or just drag it to the Not Installed column.
Edit the keyboard layout
Since the layout is uninstalled now, it’s safe to edit. You can open the file by going to File > Open Recent and choosing ipa.keylayout.
Make your changes and then save the file.
Reinstall the layout
In Ukelele go to View > Show Organizer again drag ipa back to the Installed for Current User column.
Select Close when prompted.
Log out and log in
Log out of your Mac user and then log back in again. The changes should have taken effect. If not, try restarting your computer.
You can learn a lot more by reading the documentation. In Ukelele go to Help > Ukelele Manual (PDF). Also check out the tutorials in the Documentation folder in the dmg image that you got when you downloaded Ukelele.
Starting from an existing layout
In this article you created a layout from scratch, but an easier way would be to start with a similar layout and just edit that. An easy way to do that is to go to File > New from Current Input Source. There are also a lot of layouts in the Resources folder that came with the Ukelele download. See the documentation for instructions.
More advanced layouts
In addition to modifier keys, you can also set up dead keys to give you even more options for input. You can make almost any key a dead key. A dead key is like a modifier key but when you press it, nothing happens until you press another key. For example you could make the
` key add an accent to whatever key comes next.
Sharing your layout with other people
Anyone can use your layout if they just copy it to the
Library/Keyboard Layouts folder of their home folder. For less technical users, Ukelele can also make a dmg file that will help people install the layout.