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.

Find Key Syntax

Alt+x describe-key, 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.

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?

lisp-machine-keyboard-2-left
Symbolics's Lisp Machine keyboard PN 365407 Rev C. (Photo by Joey Devilla [http://www.globalnerdy.com/2009/02/05/hacklabtos-lisp-machine-keyboard/]. 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.

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

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"))

Find the Command of a Given Key

Alt+x describe-key, then type the key combination.

List Current Major Mode's Keys

Alt+x describe-mode.

List ALL Keybinding

Alt+x describe-bindings.

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

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.

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

Emacs 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 A Curious Look at Emacs's One Thousand Keybindings] 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]

Practical Examples

Emacs Custom Keybinding to Enhance Productivity.

Operating System Wide Key Keybinding Setup

Get Programable Keyboard

These days, best option is to get a programable keyboard. This way, you don't have to worry about OS keyboard config. Just plug it in in any OS and the keys do what you want.

see Programable Keyboards with Onboard Memory

If you have a question, put $5 at patreon and message me on xah discord.
Or support me by Buy Xah Emacs Tutorial

Emacs Tutorial

Emacs Init

Emacs Keys

ELisp

ELisp Examples

ELisp Write Major Mode


Emacs Keys

Overview

Keybinding How-To

Key Tips

Emacs Pinky

Keybinding Design

Misc