Whatever it might say on the keys that you press when typing, the characters that appear on your Mac are determined by a software keyboard layout. When you want to map your whole physical keyboard to a different arrangement or set of characters, the way to do this is using a keyboard layout. If you’re fluent in French and prefer an Azerty keyboard, if you write in Ukrainian, or you’re a fan of the Dvorak layout, using the right keyboard layout is the most efficient solution.

Keyboard basics

When you press the A key without any modifier keys held, your Mac recognises this as a Key Down event of Key Code 0 with modifiers 256, and in an English keyboard layout, that’s recognised as the character a. Do the same with the Shift key held, and the modifiers become 131330 although the Key Code is the same, and that generates the capital A instead.

There are four main modifier keys: Shift, Command, Option and Control, shown above in green, and the fn key is a fifth when available. They don’t generate Key Codes as such, but are reported as modifiers to regular Key Codes. Many keyboard layouts also support five dead keys; these are keys used in combination with the Option modifier to enter accented characters. For example, on most English keyboards pressing Option-E followed by E will result in the accented character é, e-acute.

When you create a custom keyboard layout, you normally specify each character to be generated by macOS for common combinations of Key Code and modifier, and you can also specify the dead keys.

Keyboard layouts

These go right back to the earliest days of Classic Mac OS, when they were defined in special Keyboard resources. They’re now stored in Keyboard Layouts folders in either your Home library folder ~/Library, or the main library. They normally consist of a text file containing an XML definition of the keyboard layout, with the extension .keylayout, and a separate file with the icon to be shown in the Input menu for that keyboard layout. Although macOS now uses plain black-and-white icons for the standard keyboard layouts, custom layouts can still use colour graphics.

Bundled layouts

macOS comes with a huge range of standard keyboard layouts to cater for the majority of languages and layout variants. These include specialist layouts such as left-handed Dvorak and Colemak, which I hadn’t even heard of. Before embarking on a project which might duplicate a layout already available in macOS, browse the list in System Settings > Keyboard, as explained below. Even if you want a variation, it’s easier to start making your own from a similar layout than creating one from scratch.

Creating custom layouts

Although keylayout files are text, they’re exceedingly tedious to write by hand, and easy to get wrong. Even if you only want to build a basic custom keyboard layout, you’ll be better off using a tool like Ukelele, available free from SIL.

Ukelele is a mature and powerful app to create almost anything you want by way of a custom keyboard. It also makes simpler tasks easy: features like its New from Current Input Source command, which creates a complete keyboard from the layout you’re currently using. You can then just drag and drop Unicode characters from the floating Emoji & Symbols window onto the keys to build your layout.

For this example, I’ve duplicated the regular British keyboard, then dragged and dropped emoji and other symbols to keys with the Option modifier held. Shown in orange are the standard dead keys used to enter accented characters for this keyboard layout, which I have avoided changing.

When you’re ready to test your new keyboard layout, Ukelele can install it for you, although you still need to log out and back in before you can start using it.

The final step is to add your custom keyboard layout to the Input list accessed through the menu bar.

Open System Settings > Keyboard, locate the Edit… button for Input Sources, and click on that. Click on the + tool at the lower left to browse the list, scroll to the end and open the last item Others. You should find your new keyboard layout there, ready to add to the Input list.

Few users need to create their own custom keyboard layouts. But if you do need a layout different from those bundled with macOS, they are the best and most efficient solution.