Emacs: How to Define Keys

Buy Xah Emacs Tutorial. Master emacs benefits for life.
, , …,

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

For example, if you want 【F9】 for calendar, then, place this code (global-set-key (kbd "<f9>") 'calendar) 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 call eval-last-sexpCtrl+x Ctrl+e】. The new key will be active right away. 〔➤ Emacs: How to 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 --no-init-file.

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>") 'calendar)    ; F7 F8

More at: Emacs Keybinding Syntax Examples.

Common Questions

How to find key syntax?

Call describe-keyF1 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】. Call 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 Notations Explained (/r ^M C-m RET <return> M- meta).

What type of keys can i define?

Single Key. ⁖ 【F8】, 【▤ Menu】, 【⇟ Page ▽】, 【Numberpad 1

Sequence of single keys. ⁖ 【F9 8】, 【F9 ⇟ Page ▽】, 【F9 F9

Key combination (key chord). ⁖ 【Ctrl+8】, 【Ctrl+Alt+8

Sequence of single/combo keys. ⁖ 【Alt+7 8】, 【Alt+7 Ctrl+i

What's the “Meta” key?

The Meta key is a key on Lisp Machine keyboards in the 1980s. 〔➤ Photo of LISP Keyboards〕 GNU Emacs for Microsoft & Linux by default make Alt key type Meta. When you see “Meta” mentioned in emacs doc, just think of it as “Alt”.

On the Mac OS X, it's either ⌥ Opt or ⌘ Cmd, 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 Define Super & Hyper Keys.

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

How to unset a keybinding?

To unset a keybinding, set it to nil, or use global-unset-key. Example:

;; unset a key

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

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

Call describe-keyF1 k】, then type the key combination. Emacs will then show the command that key press is bound to.

To see a list of ALL keybindings that's active for your current buffer, call describe-bindingsF1 b】.

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. The following keys you should not redefine, 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 Esc key or 【Ctrl+[】. (The Esc key is tied to 【Ctrl+[】 and Meta. Esc 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 tied together.)

• 【Ctrl+i】 or Tab ↹ (These are tied together)

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. 〔➤ A Curious Look at GNU Emacs's 1000+ 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 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.

Good Spots for User Defined Keys
F5, F6, F7, F8, F9, F11, F12Excellent
F1, F2, F3, F4, F10, F11Good if you don't use their defaults actions.
Ctrl+F1】 to 【Ctrl+F12Excellent (be sure they are not used by the OS)
Alt+F1】 to 【Alt+F12Excellent. (be sure they are not used by the OS)
⇧ Shift+F1】 to 【⇧ Shift+F12Excellent
Ctrl+0】 to 【Ctrl+9】, 【Alt+0】 to 【Alt+9Excellent, if you don't use their default action. By default they are digit-argument. Use universal-argumentCtrl+u】 for digit argument instead.
Keys on number pad, with or without a modifierVery useful, but depending on which emacs distro/OS you are using, or terminal vs GUI, binding these keys may not work. Same thing can be said for those {Insert, ⌦ Delete, ↖ Home, ↘ End, ⇞ Page △, ⇟ Page ▽, …} keys.
Hyper or ❖ SuperAny combination with these is good. You can set them to ❖ Win or ▤ Menu or ⌥ Opt. 〔➤ How to Define Super & Hyper Keys

Bind Keys for Major Mode

Emacs: How to Bind Keys for Major Mode? What's a Hook?

Override Minor Mode Keybinding

Emacs: How to Override Minor Mode Keybinding

Define Super & Hyper Keys

Emacs: How to Define Super & Hyper Keys

Define Menu/App Key

Emacs: How to Define Menu/App Key

Power of Key Sequences

Emacs Keybinding: the Power of Key Sequences

How to Remap Keys

Emacs: Remapping Keys Using key-translation-map

How to Set Mouse Buttons & Wheel

Emacs: How to Set Mouse Buttons

Practical Examples

Emacs Custom Keybinding to Enhance Productivity.


Operating System Wide Key Keybinding Setup

Like it? Buy Xah Emacs Tutorial.
blog comments powered by Disqus