Redefine the X11 Meta Key in Mac OS X

10/5/2006

Today I finally got fed up with the traditional X11 keyboard mapping in Mac OS X. I’m talking specifically about the meta key. Any Mac user who has not delved into the wonderful world of X11 will not know what a meta key is, so let me give some background here. The meta key is a function key, similar to the command key (on Macs) or the ctrl key (on Windows machines).X11 Its main use is in my favorite text-editor, Emacs, which requires X11 to run. The Emacs philosophy is something that would take hours to discuss, but in short, Emacs users believe that you shouldn’t have to move your hands from the home row typing position when editing text. No use of the mouse or the arrow keys is required. All moving around, deleting text, cutting, copying, etc. is done with a combination of the control key, the meta key, and the standard letters. Check out some of these common Emacs keyboard shortcuts to get an idea of what I’m talking about. Productivity is curbed in Emacs when there is no meta key or when it is in an unfamiliar keyboard spot.

There is a way to switch which key that Mac OS X recognizes as meta by using an X11 keyboard mapping preference file. First, uncheck the “Use the system keyboard layout” option in X11 preferences. You may also have to disable the “Enable keyboard shortcuts under X11″ option as well. Then, create (or add to) the file ~/.Xmodmap and insert the following six lines:

clear Mod1
clear Mod2
keycode 63 = Mode_switch
keycode 66 = Meta_L
add Mod1 = Meta_L
add Mod2 = Mode_switch

It clears the keymappings for alt and escape and then reassigns them to the reverse of what they were before. Restart X11 and it should pick up the changes.

If this was (or wasn’t) helpful, please let me know in the comments!

  • Hang Si

    It works, amazing! I’m really happy to find the artile. I’ve just migrated from Linux to MacOSX. Emacs is my all-day working editors. I was quite frustrating at the beginning that I found the meta key didn’t work. I tryed very hard to activate it by both combining different keys and changing the setting in .emacs file, but all effort was in vain. Then I came to your article after searching in the google for a while. Now I can keep working on my favorite editor. Thank you!

  • Nick

    Thanks that worked great for me too. I found you blog via Google also.

  • keycoffee

    Weyell – it works fine for me, if I’m just working on my local machine. This is indeed fabulous. But – when I try and log into a separate linux server this trick doesn’t work (sigh) – even with a .Xmodmap file in my home directory on the other machine.

    Its very frustrating – emacs is soo important to my work and keyboard happiness is crucial.

  • Oskar

    Thanks, it worked great! While we’re at it, how to copy/paste between OS X and X11 (and emacs in particular)? :)

  • http://snier.com Tyler

    I can copy from OS X to emacs using the standard Command-c in OSX then Ctrl-y in emacs.

    To go the other way, use Command-c in X11 and Command-v in your favorite OS X application.

    Hope that helps!

  • http://nowebsite.sorry.com Paolo

    Works great! Thanks for the tip, Tyler!

  • Peter

    As far as it working on other machines, I have in my local ~/.Xdefaults file the following lines:

    XTerm*VT100.metaSendsEscape: True
    XTerm*VT100.backarrowKeyIsErase: False

    This is (I think) what finally made it possible for me to get meta on remote machines working. Of course this only fixes the problem for xterm. Other terminal programs are still broken (and I’m afraid the OSX Terminal.app is hopeless.)

    I pretty much live in Emacs, and I’m trying very hard to be happy with OSX. But the pain of using this editor with OSX, and the uncertainty that DoubleCommand will continue to work with future verions of OSX makes me second guess the wisdom of buying a Mac. After all, a mondern user-oriented OS shouldn’t force me to abandon 20 years of burnt-in muscle memory, should it?

  • Roger

    Peter — your .Xdefaults modification works wonders. Thank you for sharing it!

  • David Brodbeck

    Wow, great article. I now have some consistency between my xterms and Terminal. I had previously checked ‘Use Option Key As Meta Key’ in the Terminal window settings to get the behavior I wanted there, but my xterms were still using Esc as meta until I found this article in Google.

    I never really understood why anyone would use emacs until I got a proper Meta key working. Without that it’s just plain tedious.

  • yashar

    awesome. thanks.

  • kourouma

    Hi there. I would like to create a Xmodmap file as well, but unfortunately I have not the slightest idea how to do that. Can somebody please tell me? the home folder your talking about is the one with house icon I take it?
    Thanks
    Kourouma

  • http://snier.com Tyler

    Yes, the home folder for your user account is the one with the house icon. If your username is foo, then the path of this folder is /Users/foo. Another way of referencing the home folder is by using the ~ character, which expands to /Users/foo.

    To create the file, either use TextEdit (or your favorite text editor), or use emacs or vi in the Terminal.

  • kourouma

    Thanks

  • Ian

    Thanks for this nice discussion and tips. I just got a new Mac, and when I followed your instructions it seemed to switch the alt/option key with the Command/Apple key, rather than switching the alt/option key with the esc key. Could this be because of my version of X11 (1.1.3), or because I did something wrong, …? Weird that it seemed to work for everyone else. After a lot of blind attempts and googling, though, I finally got alt/option and esc to be switched on my computer: now alt/option is the emacs meta key (both on local emacs in the X11 terminal window and when I ssh to an emacs session on a remote Linux machine). In case someone else runs into this same problem, here’s what I put in my .Xmodmap file (just these 2 lines):

    keysym Mode_switch = Escape
    keysym Escape = Mode_switch

  • Eugene

    I’m freaking out cause this makes NO sense
    When I run xmodmap (for Tiger OS X), the mods are listed as:

    mod1 Meta_L (0×42)
    mod2 Mode_switch (0x3f), Mode_switch (0×45)

    Why Are there 2 Mode_switches? I thought I was only assigning Escape to Mode_switch… but Apple Command is not ‘copying’ the way it did in Panther. Apple Command-c gives me a modified character ‘c’ with the little squiggly line coming underneath (like the French word facade)… WTF?!?!?!?!? I want Apple Command to do what it is supposed to do by default! No Mode_switch crap… I don’t even have an .xinitrc file… only a .Xmodmap file. It has exactly the 6 lines from this page. Why the hell are there two Mode_switch bindings???

  • Eugene

    One more time… My .Xmodmap:
    clear mod1
    clear mod2
    …. then I run xmodmap and I get:
    shift Shift_L (0×40), Shift_R (0×44)
    lock Caps_Lock (0×41)
    control Control_L (0×43), Control_R (0×46)
    with the mod’s being EMPTY.

    Now I put .Xmodmap to be:
    clear mod1
    clear mod2
    keycode 66 = Meta_L
    add mod1 = Meta_L

    This gives me an output from xmodmap:
    shift Shift_L (0×40), Shift_R (0×44)
    lock Caps_Lock (0×41)
    control Control_L (0×43), Control_R (0×46)
    mod1 Meta_L (0x3f), Meta_L (0×42)

    WHY THE HELL ARE TWO META_L’s BEING ASSIGNED??????????!!!!!!!!!!
    I’m gonna throw this freakin laptop out the window.

  • http://vilot.com Tom

    I’m confused … why did you need to do this?

    X11 on Mac OS X defaults to having the meta key be the command key (thank god. My hands are programmed for that key at that position from years of X11 on Linux / BSD)

    What does this remapping accomplish??? Does it make the option/alt key the meta key? eeew.

    > To go the other way, use Command-c in X11 and Command-v in
    > your favorite OS X application.

    That doesn’t work for me….

  • http://www.stevengharms.com Steven G. Harms

    Excellent post.

    This helped me immeasurably. I am now able to move through the bash shell as god intended ( with emacs bindings ). I don’t use emacs anymore though, it upset my carpal tunnel too much ( vi dvorak keyboard or Textmate dvorak has proved to be my savior ).

    Thanks again though,

    Steven

  • William Daffer

    > To go the other way, use Command-c in X11 and Command-v in
    > your favorite OS X application.

    This didn’t work for me either.

    Just to be completely explicit, I’d like a key binding in emacs that would put the copied region into the Mac clipboard so that I could then use Command-V in some non-X11 application to paste that text in.

    Is this possible?

  • Dancing with Penguins

    You don’t need to restart X11. Just run

    xmodmap ~/.Xmodmap

    should be sufficient. That way you can try out different settings without restarts.
    You should start with a

    xmodmap -pke > ~/.Xmodmap.default

    however, as this gives you the possibility to recover at any point by

    xmodmap ~/.Xmodmap.default

    to your initial keyboard mapping.

    Peter

  • Lance E Sloan

    It didn’t work with GIMP. That is, after the change, I expected to use the command key with the underlined letters in the UI in order to activate them, and that didn’t work. I thought that command-F would open the file menu, etc. But it doesn’t, it still requires option-F instead.

  • http://snier.com Tyler

    @Lance – That’s not the problem that this article is trying to solve. But to comment on your issue, a native port of Gtk+ for Mac OS X is currently being developed. Gtk+ is a graphics/windowing toolkit which is standard fare on Unix/Linux systems. When the port is completed, apps like Gimp will be able to be run on Macs without using X11. One of the features of this port is that ctrl+ shortcuts will be remapped to command+ shortcuts.

    See the Gtk+ for Mac OS X Development Page for more details.

  • Randy Bushq

    i LIKE meta being apple key. but why is it not working in emacs? lack of meta in emacs is killing me!

    [ long time bsd/emacs user with new macbook ]

  • Pingback: the jakbot - Redefine the X11 Meta Key in Mac OS X

  • Denali Lumma

    Hi There,

    You need to configure the mac ‘terminal’ application so the ‘alt / option’ key sends ‘meta’. In order to do this, go to:

    Terminal > Preferences > Settings > Keyboard

    and select the ‘Use option as meta key’ checkbox at the bottom of the window.

    I hope that helps,

    -Denali

  • Olga

    Denali, thanks for your tip! It solved my problem.

    Olga

  • Mahesh

    very helpful. thanks for the article. .Xmodmap change is helping me a lot while navigating in the bash interactive shell.
    –mahesh n

  • Christian

    Hi there,

    mapping meta to alt just works fine for me, too. But there is a large problem for people with a german keyboard layout: you need to type Alt-N to get ~ and Alt-L to get an @. But I am not able to type these 2 signs anymore, if I don’t have an alt key any longer. Are there any suggestions for this? Could I somehow map the key right to the right command key to be an alt key? And would this again be translated to meta?

  • Thulasinathan Kandasamy

    Mapping alt/option key to meta key woks just cool for me as well. Thanks :)

  • Bob

    You could of course, just use AquaEmacs (http://aquamacs.org/)

  • Kris

    Sure Bob, I use it too. My problem *was* TeXmacs (as cool as you can have for typing math). Thanks Tyler, greeting Down Under :-) )

  • Maks

    Same here, I wanted TeXmacs badly. Thanks for the article!

  • Milo

    Very useful. Your instructions helped me make the META key work when tunneling XEmacs on Linux via SSH to X11 running on my Mac (OS X 10.5.8). Thanks for writing this up!

  • Stegano

    No luck switching the Esc and Option Key for Meta function on Snowleopard and X11 XQuartz 2.3.4 (xorg-server 1.4.2-apple45). I tried both suggestions for .Xmodmap file and I can’t get it to work in emacs using X11 or xTerm or even remote emacs.

    Any help will be much appreciated. God I am beginning to hate Apple for slowing me down.

  • Mohit

    life saver!!

  • http://kurtkotheimer.com kurt

    thanks tons. emacs – metakey = awful.

  • http://www.mehryar.com Mehryar

    Life saver indeed! Spent an hour futzing with various options until I found this post. A copy and paste from your post into my .xmodmap fixed the issue.

  • http://leifjohnson.net Leif

    OMG, I am so happy I found your blog post. I’ve been trying (and failing) to fix this on my Macs for >2y now, and your .Xmodmap snippet totally works.

    Goodbye mrxvt ! Good night, Terminal.app ! Farewell, iTerm ! Finally I can use the key to the left of the space bar as meta, locally, through ssh, using screen, in emacs, and in all combinations of those things. Thanks again for your post !

  • http://internode.on.net upi

    Any idea how to get the Apple Command key to act like escape in the terminal or xterm?
    That is: in the shell you can use Command-f to move cursor forward a word or Command-b to move it back a word?

  • PiotR

    I have tried what was suggested above and still have troubles. I am running 10.6.2. I have Alt/Option working as Meta when I use /usr/bin/emacs or xemacs. However, for /sw/bin/emacs22 or /sw/bin/emacs23 this does not work and I have to use Esc for Meta. Any help would be appreciated.

  • David Strozzi

    Hi,

    I’ve used this page several times over the years, but on my most recent machine it’s falling short. I have a brand new intel macbook w/ OS 10.6.4. I generally use the most recent Xquartz app, not the X11 that ships from Apple.

    The .Xmodmap file described in the article maps the left option key to the right meta behavior in emacs, but the right option key does nothing.

    Any ideas?

    To quote an overheard geek OS discussion, “linux is nice but I prefer emacs.”

    Thanks,
    Dave

  • David Strozzi

    Actually, I figured out the answer:

    clear Mod1
    clear Mod2
    keycode 63 = Mode_switch
    keycode 66 = Meta_L
    keycode 69 = Meta_R
    add Mod1 = Meta_L Meta_R
    add Mod2 = Mode_switch

    Do you think this article counts as “knowledge” for wikipedia? They have a page on the option key. Given that every episode of Anime/Star Trek count, I think this does too……

  • Pingback: Alt as Meta key in X11 | Let's try that again

  • http://twitter.com/kabulykos Khalil Bey

    It’d probably fall victim to Wikipedia’s “original research” exclusion. :-)

  • Joelh

    Dude, you fixed it. Thank you.

  • Jon Lorusso

    This page is paying dividends almost 7 years later. You should put up a donation button!