Emacs: How to Define Keys

By Xah Lee. Date: . Last updated: .

In emacs, you can create any keyboard shortcut to any command. This page shows you how.

For example, if you want 【F9】 for whitespace-mode, then, place this code (global-set-key (kbd "<f9>") 'whitespace-mode) in your emacs init file and restart emacs.

If you are experimenting, and don't want to restart emacs every time you try to define a new key, you can place cursor at the end of parenthesis and Alt+x eval-last-sexpCtrl+x Ctrl+e】. The new key will be active right away. [see Evaluate Emacs Lisp Code]

If you made some mistake and need to start emacs without loading your init file, you can start emacs from terminal like this: emacs -q.

Emacs Keybinding Syntax Examples

(global-set-key (kbd "M-a") 'backward-char) ; Alt+a

(global-set-key (kbd "C-a") 'backward-char) ; Ctrl+a

(global-set-key (kbd "C-c t") 'backward-char) ; Ctrl+c t

(global-set-key (kbd "<f7> <f8>") 'whitespace-mode)    ; F7 F8

More examples at Emacs Keybinding Syntax Examples.

Common Questions

How to find key syntax?

Alt+x describe-keyCtrl+h k】, then press the key you want. Emacs will then display its syntax.

For example, suppose you want to know the syntax for the key press of 【Ctrl+Alt+F8】. Alt+x describe-key, then press 【Ctrl+Alt+F8】, then emacs will print “<C-M-f8> is undefined”. That means, you can use (kbd "<C-M-f8>") to represent that key combination in lisp code.

For examples, see: Emacs Keybinding Syntax Examples.

Note: emacs has lot syntax variations for a given keyboard shortcut, but the one printed by describe-key is guaranteed to work. For details of emacs's keystroke syntax variation, see: Emacs's Key Syntax Explained.

What's “Meta” key?

Symbolics's Lisp Machine keyboard PN 365407 Rev C. (Photo by Joey Devilla. Used with permission.)

[see Lisp Machine Keyboards]

The Meta key is a key on Lisp Machine keyboards in the 1970s and 1980s.

GNU Emacs for Microsoft and Linux by default make the Alt key do Meta.

On the Mac OS X, it's either ⌥ option or ⌘ command, depending on which emacs distribution you are using. There's usually a menu that lets you chose. You can set them yourself, see: Emacs: How to Bind Super Hyper Keys.

In emacs documenation, the Meta key's notation is M-. For example, M-x means 【Meta+x】.

How to remove a keybinding?

To unset a keybinding, set it to nil.

;; unset a key
(global-set-key (kbd "C-b") nil)

Or use global-unset-key.

;; unset a key
(global-unset-key (kbd "C-b"))

How to find out the what command is bound to a given key?

Alt+x describe-keyCtrl+h k】, then type the key combination.

How to list current major mode's keys?

Alt+x describe-modeCtrl+h m】.

How to list ALL keybinding?

Alt+x describe-bindingsCtrl+h b】.

Each major mode or minor mode usually add or change some keys. So, key list generated is specific to current buffer.

How to swap Caps Lock and Control key?

You cannot do it within emacs, because these are at the OS level. See:

Keys to Avoid

Emacs has its quirks. It's best not to define the following keys, unless you know what you are doing.

• 【Ctrl+?】. (due to emacs technical implementation quirk. (info "(elisp) Ctl-Char Syntax"))

• 【F1】 or 【Ctrl+h】. (This key is used for emacs help system and have a special status in emacs's key system. For example, type 【Ctrl+x】, then type 【Ctrl+h】, it'll list what valid keys can follow and the associated command.) (info "(elisp) Help Functions")

• The Escape key or 【Ctrl+[】. (The Escape key is tied to 【Ctrl+[】 and Meta. Escape by itself has complicated meanings depending when it is pressed and how many times it is pressed.)

• 【Ctrl+Shift+letter】. In text terminals, it cannot distinguish shifted and unshifted versions of such combination. Works fine if you always use emacs in a GUI environment. (info "(elisp) Other Char Bits")

• 【Ctrl+m】 or Enter. These are the same by default. It sends ASCII carriage return character.

• 【Ctrl+i】 or Tab. These are the same by default. It sends ASCII horizontal tab character.

What's the difference between emacs "<tab>" and "TAB" key notation?

See: Emacs's Key Notation: What's the difference between "<return>" and "RET"?

Good Key Choices

Emacs has some 7 thousand commands. By default, 800 of them have key shortcuts. [see List of Emacs Default Keybinding] All the common key spots are used. If you define your own keys without care, you may find that many major mode or minor mode override your keys, because they have priority.

By official emacs documentation (info "(elisp) Key Binding Conventions"), the key space reserved for users are the function keys F5 to F9, and 【Ctrl+c letter】. This is very restrictive.

The following keys are good spots for your own definitions, and does not cause any problems in practice.

F5, F6, F7, F8, F9, F11, F12 → Good. Combination with Alt or Ctrl or Shift is also good. Make sure they are not used by the OS.

F1, F2, F3, F4, F10, F11 → Good if you don't use their defaults actions.

For their default actions, see Emacs Key Layout Diagram

Ctrl+0】 to 【Ctrl+9】 → Good. By default they are digit-argument. Use universal-argumentCtrl+u】 instead.

Alt+0】 to 【Alt+9】 → good.

Number Pad Keys → Very useful, but depending on which emacs distro/OS you are using, or if you use emacs in terminal or GUI, binding these keys may not work. [see Emacs: Bind Number Pad Keys]

Hyper or Super → Any combination with these is good. You can set them to ❖ Window or ▤ Menu or ⌥ option. [see How to Define Super and Hyper Keys]

Bind Keys for Major Mode

Major mode usually define its own set of keys, and have priority over global keys.

You can use a hook to override major-mode keys.

Emacs: Change Major Mode Keys

Override Minor Mode Keybinding

Minor mode keys overrides global keys and major mode keys.

Emacs: Change Minor Mode Keys

Define Menu/App Key

Emacs: How to Define Menu Key

Define Key Sequences

Emacs: Define Key Sequence

Number Pad Keys

Number pad keys gives you some 16 extra function keys.

Emacs: Bind Number Pad Keys

Define Super and Hyper Keys

Super Hyper are modifiers on lisp machine keyboards. You can set ❖ Window or ⌥ option to do them.

The advantage of Super Hyper is that you'll never have annoying problem of your key being overridden by some mode, because emacs do not bind them by default.

Emacs: How to Bind Super Hyper Keys

How to Remap Keys

Emacs: Remapping Keys Using key-translation-map

How to Set Mouse Buttons

Emacs: How to Set Mouse Buttons

Practical Examples

Emacs Custom Keybinding to Enhance Productivity.


Operating System Wide Key Keybinding Setup

Emacs Keybinding How-To Topic

  1. How to Define Keys
  2. Change Major Mode Keys
  3. Change Minor Mode Keys
  4. Fix Minor Mode Key Priority
  5. Define Key Sequence
  6. How to Bind Super Hyper Keys
  7. How to Define Menu Key
  8. Remapping Keys Using key-translation-map
  9. Bind Number Pad Keys
  10. How to Set Mouse Buttons

Emacs Customization

  1. Emacs init file
  2. Install Packages
  3. Install Package Manually
  4. Define Keys
  5. M-x customize
  6. What's Major Mode?
  7. What's Minor Mode?
  8. Set File to Open in a Major Mode
  9. Organize Init File
  10. Byte Compile Elisp
  11. What's Hook?
  12. Environment Variables in Emacs
  13. Set Default Window Size
  14. Font Setup
  15. Set Color Theme
  16. Turn Off Auto Backup; Set Backups into a Directory; How to Delete Backup Files
  17. Elisp: Determine OS, Emacs Version, Machine Host Name
  18. Elisp: Check If a {function, variable, feature} is Defined/Loaded
Patreon me $5 patreon

Or Buy Xah Emacs Tutorial

Or buy a nice keyboard: Best Keyboards for Emacs

If you have a question, put $5 at patreon and message me.