Posted On 08/04/2014 By In How-To

HOW TO: Remap keys in OSX using KeyRemap4MacBook (now Karabiner)

In this tutorial, I will show you how to remap your keyboard in OSX. We’ll be using software called Karabiner (formerly KeyRemap4MacBook), which is very powerful and 100% free.

Before remapping your keyboard via software, check to see if your keyboard has a DIP switch setting for the key(s) you want to remap. Hardware remapping is preferable to software when possible, because any changes you make will work with ALL devices, not just the computer on which you’ve installed remapping software.

Basic Remapping

  • Step 1: Download and install Karabiner. If you’re planning to remap your Caps Lock key, also download and install Seil.
  • Step 2: Create a profile for the keyboard you want to remap. To do so, click Karabiner’s icon in the system tray at the top-right-hand side of the screen. Go to Preferences –> MenuBar and tap the plus (+) button.

Screen Shot 2014-08-03 at 7.41.40 PM

Screen Shot 2014-08-03 at 7.45.18 PM

  • Step 3: Select your new profile using Karabiner’s system tray icon.

Screen Shot 2014-08-04 at 12.47.03 AM (2)

  • Step 4: Open Karabiner’s Preferences page once again, and this time, go to the “Change Key” tab. Check the remaps you want. Karabiner has hundreds of built-in remapping options, and there’s a good chance you’ll find what you need as a one-click option. Use the search box to find the keys you want to remap. Note that you don’t need to hit the ReloadXML button — changes will be applied as soon as you check or uncheck a box.

Screen Shot 2014-08-03 at 7.49.36 PM

  • Step 5: Close Karabiner’s preference panel and test your new remapping. Karabiner’s EventViewer function can come in handy for this. Done!

Advanced Remapping

So, you want to perform a remap that you can’t find in Karabiner’s pre-configured list. No problem — you just need to edit your private.xml. If you don’t already have a code editor that handles XML, download and install Adobe Brackets, a free and open source code editor.

  • Step 1: If you haven’t already done so, create a new keyboard profile as per the above instructions.
  • Step 2: Open Karabiner’s Preferences page, go to the “Misc & Uninstall” tab, and click the button labeled “Open private.xml.” A new Finder window will open, in which you will see your private.xml file. Right click it and open it using Adobe Brackets.

Screen Shot 2014-08-03 at 8.02.15 PM

Screen Shot 2014-08-03 at 8.00.30 PM

  • Step 3: Edit and save changes to private.xml. Your default private.xml may be blank or have some basic template code. If in doubt, delete everything in private.xml and start fresh by pasting in this code:

<?xml version="1.0"?>
    <name>Swap Space and Tab</name>
    <autogen>__KeyToKey__ KeyCode::SPACE, KeyCode::TAB</autogen>
    <autogen>__KeyToKey__ KeyCode::TAB, KeyCode::SPACE</autogen>

    <name>Left command + backquote = escape</name>
        __KeyToKey__ KeyCode::BACKQUOTE, ModifierFlag::COMMAND_L, KeyCode::ESCAPE

    <name>F15 to volume up</name>
    <autogen>--KeyToConsumer-- KeyCode::F15, ConsumerKeyCode::VOLUME_UP</autogen>

This code will be your template for creating custom remaps. Each remap goes inside its own item tag, with a name and identifier of your choice (private._________________). Then, use __KeyToKey__ or –KeyToConsumer– (for media keys) inside autogen tags to reassign keys as shown.

To find the necessary KeyCodes, you can either use Karabiner’s EventViewer or the lists linked below. Use the English language codes in private.xml, not the hex codes.

You can copy and adapt these two examples to most remapping you will need to do. In the event you need to remap in a way that these examples don’t cover, such as remapping a key to multiple other keys, consult Karabiner’s extensive technical documentation.

Note that when a single key is involved in more than one remap, you must consolidate all the relevant autogens inside a single item tag or the XML file will not be parsed correctly.

  • Step 4: Save private.xml and hit the ReloadXML button in Karabiner’s “Change Key” tab. Find your new remaps in the list, check them, and you’re good to go! If you receive an error message after hitting ReloadXML, go back and find the problem in private.xml — likely a tag that wasn’t properly closed.

As I noted at the beginning of this post, you’ll need to install and use Seil if you want to remap caps lock. See here for instructions for remapping caps lock with Seil..

Did you successfully remap your keyboard using this tutorial? Leave a comment and let me know. If you’re struggling, leave a comment and I’ll help you out. ­čÖé

Tags : , , , , ,



7 Responses

  1. Avatar

    I’ve got a FC660m I’m using on a mac. Everything works here except the Fn is bound to the ‘a’ key with the exact same keycode. Any ideas for how to rebind the Fn key without messing with the home row a?

Leave a Reply