Xah Lee, 2005, ..., 2009-07, 2009-12-17
In emacs, you can create any keyboard shortcut to any command. This page shows you how.
The act of creating a keyboard shortcut is called keybinding. For example, if you want “Ctrl+z” to be undo, then, place this code “(global-set-key (kbd "C-z") 'undo)” in your emacs init file and restart emacs. If you are experimenting, and don't want to restart emacs everytime you try to define a new shortcut, you can select the lisp code then type “Alt+x eval-region”.
Here are sample code you need to place in your emacs init file for defining various key press combinations. The “cmd” is the name of the command you want the keypress to invoke.
The “Meta” key is a key on some keyboards in the 1980s. (see: Why Emacs's Keyboard Shortcuts Are Painful) The Meta key doesn't exist in today's keyboards, but emacs remap it to PC keyboard's Alt key by default. When you see “Meta” mentioned in emacs, just think of it as Alt key.
Example of shortcuts with a single modifier key:
(global-set-key (kbd "M-a") 'cmd) ; Meta+a (global-set-key (kbd "C-a") 'cmd) ; Ctrl+a
Example of shortcuts with a special key:
(global-set-key (kbd "<f2>") 'cmd) ; F2 key (global-set-key (kbd "<kp-2>") 'cmd) ; the “2” key on the number keypad (global-set-key (kbd "<insert>") 'cmd) ; the Ins key (global-set-key (kbd "<delete>") 'cmd) ; the Del key (global-set-key (kbd "<home>") 'cmd) (global-set-key (kbd "<end>") 'cmd) (global-set-key (kbd "<next>") 'cmd) ; page down key (global-set-key (kbd "<prior>") 'cmd) ; page up key (global-set-key (kbd "<left>") 'cmd) ; ← (global-set-key (kbd "<right>") 'cmd) ; → (global-set-key (kbd "<up>") 'cmd) ; ↑ (global-set-key (kbd "<down>") 'cmd) ; ↓ (global-set-key (kbd "RET") 'cmd) ; the Enter/Return key (global-set-key (kbd "SPC") 'cmd) ; the Space bar key
(info "(elisp) Function Keys")
Example of shortcuts with a modifier key and a special key:
(global-set-key (kbd "M-<f2>") 'cmd) ; Meta+F2 (global-set-key (kbd "C-<f2>") 'cmd) ; Ctrl+F2 (global-set-key (kbd "S-<f2>") 'cmd) ; Shift+F2 (global-set-key (kbd "M-<up>") 'cmd) ; Meta+↑ (global-set-key (kbd "C-<up>") 'cmd) ; Ctrl+↑ (global-set-key (kbd "S-<up>") 'cmd) ; Shift+↑
Example of shortcuts with 2 modifier keys pressed simultaneously, plus a letter key:
(global-set-key (kbd "M-A") 'cmd) ; Meta+Shift+a (global-set-key (kbd "C-A") 'cmd) ; Ctrl+Shift+a (global-set-key (kbd "C-M-a") 'cmd) ; Ctrl+Meta+a
Example of 2 modifier keys with a digit key:
(global-set-key (kbd "M-@") 'cmd) ; Meta+Shift+2 or Meta+@ (global-set-key (kbd "C-@") 'cmd) ; Ctrl+Shift+2 or Ctrl+@ (global-set-key (kbd "C-M-2") 'cmd) ; Ctrl+Meta+2 (global-set-key (kbd "C-S-<kp-2>") 'cmd); Ctrl+Shift+“numberic pad 2”
Example of 3 modifier keys:
(global-set-key (kbd "C-M-S-a") 'cmd) ; Ctrl+Meta+Shift+a (global-set-key (kbd "C-M-!") 'cmd) ; Ctrl+Meta+Shift+1 or Ctrl+Meta+! (global-set-key (kbd "C-M-\"") 'cmd) ; Ctrl+Meta+Shift+' or Ctrl+Meta+" (global-set-key (kbd "C-M-S-<up>") 'cmd); Ctrl+Meta+Shift+↑
Example of shortcuts with a sequence of keystrokes:
(global-set-key (kbd "C-c a") 'cmd) ; Ctrl+c a (global-set-key (kbd "C-c SPC") 'cmd) ; Ctrl+c Space (global-set-key (kbd "C-c <f2>") 'cmd) ; Ctrl+c f2 (global-set-key (kbd "C-c <up>") 'cmd) ; Ctrl+c ↑ (global-set-key (kbd "C-c C-c <up>") 'cmd); Ctrl+c Ctrl+c ↑
A shortcut can be created without any modifier keys.
(global-set-key (kbd "2") 'cmd) (global-set-key (kbd "a") 'cmd) (global-set-key (kbd "é") 'cmd) (global-set-key (kbd "α") 'cmd) (global-set-key (kbd "π") 'cmd) (global-set-key (kbd "(") 'cmd) (global-set-key (kbd "你") 'cmd)
Emacs has its quirks. The following keys you should not redefine:
Emacs has some 7 thousand commands and by default has about 800 shortcuts. 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 "Key Binding Conventions") , the key space for users are the function keys F5 to F9, and key stroke sequence starting with “Ctrl+c” followed by a single letter key. This is very restrictive.
The following keys are good spots for your own definitions, and does not cause any problems in practice.
You should just use the above ones. But if you really want, you can also use the number pad keys, with or without a modifier. However, depending on which emacs distribution you are using, and on what operating system you are running, binding these keys may not work. Same thing can be said for those Insert, Delete, Home, End, Page Up, Page Down keys.
A keypress combination such as “Meta+Shift+2” can also be considered as “Meta+@”. So, in emacs, you might be thinking that both of these code: “(kbd "M-S-2")” and “(kbd "M-@")” will work. Actually, only the latter will work.
When writing a keybinding definition, for a key combination that is “Meta+Shift+‹key›”, you must use a code without the “-S” if possible. But for key combination that is “Ctrl+Shift+‹key›”, you must use the “-S”. Examples:
| GOOD | BAD | Keystroke |
|---|---|---|
| (kbd "M-A") | (kbd "M-S-a") | Meta+Shift+a |
| (kbd "M-@") | (kbd "M-S-2") | Meta+Shift+2 |
| (kbd "M-:") | (kbd "M-S-;") | Meta+Shift+; |
| (kbd "C-S-a") | (kbd "C-A") | Ctrl+Shift+a |
A easy way to find out the proper syntax, is to call “Alt+x describe-key”, then type the keystroke.
Note also, that keys involving “Ctrl+Shift+‹key›” cannot be distinguished from “Ctrl+‹key›” when emacs runs in a text terminal (telnet/ssh). Therefore, it is best to avoid binding with both Control and Shift.
Example of shortcut with a punctuation key that are typed with Shift:
(global-set-key (kbd "C-:") 'cmd) ; Ctrl+Shift+; or Ctrl+: (global-set-key (kbd "C-\"") 'cmd) ; Ctrl+Shift+' or Ctrl+" ; note: the question mark “?” cannot be used in shortcut.
Example of 2 modifier keys with a special key:
(global-set-key (kbd "M-S-<f1>") 'cmd) ; Meta+Shift+F1 (global-set-key (kbd "C-S-<kp-2>") 'cmd) ; Ctrl+Shift+“numberic pad 2” (global-set-key (kbd "C-M-<up>") 'cmd) ; Ctrl+Meta+↑
When there are more than one modifier keys, such as “C-M-a”, the order of the modifier in the string does not matter. It is recommended that they be alphabetical. So, use “C-M-a”, not “M-C-a”.
Emacs support lisp machine keyboards, which has Super and Hyper modifier keys. In today's Windows keyboard or Mac keyboard, there's no such modifier keys, but you can make the Windows keyboard's Windows key, Menu key, or Mac keyboard's Option key to function as Super or Hyper within emacs.
; setting the PC keyboard's various keys to ; Super or Hyper, for emacs running on Windows. (setq w32-pass-lwindow-to-system nil w32-pass-rwindow-to-system nil w32-pass-apps-to-system nil w32-lwindow-modifier 'super ;; Left Windows key w32-rwindow-modifier 'super ;; Right Windows key w32-apps-modifier 'hyper) ;; Menu key
Note: in Microsoft Windows, several keybindings with the Windows key is bound at a low level, and applications do not see them. For example, “Win+r” is for launching apps by name. (See: Microsoft Windows Keyboard Shortcuts.) There's no way around that unless you use other tools such as AutoHotKey.
(info "(emacs) Windows Keyboard")
; setting Hyper and Super keys for the Mac keyboard, for emacs running in OS X (setq mac-option-modifier 'hyper) ; sets the Option key as Hyper (setq mac-option-modifier 'super) ; sets the Option key as Super (setq mac-command-modifier 'meta) ; sets the Command key as Meta (setq mac-control-modifier 'meta) ; sets the Control key as Meta
(info "(emacs) Mac Input")
The syntax for defining keys with the Super or Hyper modifier keys is the same as Meta and Control. Use “H” for Hyper, “s” for Super. Example:
(global-set-key (kbd "H-b") 'backward-word) ; H is for hyper (global-set-key (kbd "s-b") 'backward-word) ; lower case “s” is for super (global-set-key (kbd "M-H-b") 'backward-word) ; Meta+Hyper+b (global-set-key (kbd "M-s-b") 'backward-word) ; Meta+Super+b
How to unset a keybinding?
To unset a keybinding, use “global-unset-key”. For example, you have defined a keystroke for undo, and wants to kick the habit of the hitting the default shortcut for undo:
(global-unset-key (kbd "C-_"))
How to find out the current keybinding to a key?
Type “Ctrl+h k” (or “Alt+x describe-key”), then type the key combination. Emacs will then show the function that key press is bound to.
To see a list of ALL current keybindings, use describe-bindings (Ctrl+h b).
How to find out the syntax for a particular key combination?
Type “Ctrl+h k” (or “Alt+x describe-key”), then press the key combination. Emacs will then display its syntax. For example, you want to know the syntax for the key press of “Ctrl+Alt+F8”. Type “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.
Note: There is a lot syntax variations, but the one printed by “describe-key” is guaranteed to work. For details of emacs's keystroke syntax variation, see: The Confusion of Emacs's Keystroke Representation.
How to have a keyboard shortcut set only when a particular mode is active?
Use a hook for the mode. A hook will load your code whenever that mode is activated. Here's a usable example:
; define some keys only when the major mode html-mode is active (add-hook 'html-mode-hook (lambda () (define-key html-mode-map (kbd "C-c w") 'bold-word) (define-key html-mode-map (kbd "C-c b") 'blue-word) (define-key html-mode-map (kbd "C-c p") 'insert-p) (define-key html-mode-map (kbd "M-4") 'tag-image) (define-key html-mode-map (kbd "M-5") 'wrap-url) ) )
(info "(emacs) Hooks")
How to change major mode or minor mode's keys?
How to swap Caps Lock and Control key?
This is not possible within emacs, because these are at the OS level. See:
Here are some practical real-world ideas on how defining keyboard shortcut is used.
You can create a shortcut to insert frequently used unicode characters. You can add few chars, or a systematic character set.
(global-set-key (kbd "<kp-6>") "→") ; numeral keypad 6 (global-set-key (kbd "M-i a") "α") ; Alt+i a (global-set-key (kbd "M-i b") "β") (global-set-key (kbd "M-i t") "θ")
See also:
;; make cursor movement keys under right hand's home-row. (global-set-key (kbd "M-i") 'previous-line) ; was tab-to-tab-stop (global-set-key (kbd "M-j") 'backward-char) ; was indent-new-comment-line (global-set-key (kbd "M-k") 'next-line) ; was kill-sentence (global-set-key (kbd "M-l") 'forward-char) ; was downcase-word (global-set-key (kbd "M-SPC") 'set-mark-command) ; was just-one-space
;; type parens in pairs with Hyper and right hands's home-row (global-set-key (kbd "H-j") (lambda () (interactive) (insert "{}") (backward-char 1))) (global-set-key (kbd "H-k") (lambda () (interactive) (insert "()") (backward-char 1))) (global-set-key (kbd "H-l") (lambda () (interactive) (insert "[]") (backward-char 1)))
For a more systematic change, see A Ergonomic Keyboard Shortcut Layout For Emacs.
; make some function keys insert templates when in html-mode (add-hook 'html-mode-hook (lambda () (define-key html-mode-map (kbd "<F5>") 'insert-my-header) (define-key html-mode-map (kbd "<F6>") 'insert-my-footer) (define-key html-mode-map (kbd "<F7>") 'insert-signature) (define-key html-mode-map (kbd "<F8>") 'insert-paragraph-tag) ; ... ) ) ;; example of defining a template insertion command (defun 'insert-paragraph-tag () "Insert <p></p> at cursor point." (interactive) (insert "<p></p>") (backward-char 4))
(global-set-key (kbd "<F5>") 'open-unicode-template) (global-set-key (kbd "<F6>") 'open-my-file1) (global-set-key (kbd "<F7>") 'open-my-file2) ; ... (defun open-unicode-template () "Open a file containing frequently used unicode chars" (interactive) (find-file "~/web/emacs/unicode.txt"))
References and further readings: