My local-set-key and local-unset-key, used interactively M-x ..., are not working as expected, namely to bind or unbind a key for a specific buffer.

Case in point: I am editing a LaTeX (.tex) file in AucTeX's LaTeX major mode. LaTeX mode binds C-TAB (same as C-M-i) to TeX-complete-symbol. However, flyspell minor mode is enabled (and is otherwise useful), but for some very lame reason this minor mode binds the (rather useless) flyspell-auto-correct-word command to not just one, but two different keys, namely C-. and C-M-i

For the life of me, I cannot figure out how to bind C-M-i to TeX-complete-symbol restoring AucTeX's intended functionality, except by disabling flyspell minor mode. When called interactively from my .tex buffer, local-set-key fails to actually set the key to TeX-complete-symbol, the original mapping to flyspell-auto-correct-word remains in place. I also tried local-unset-symbol, but the darned flyspell mapping remains in place. After convincing myself that what I'm doing should be changing the binding (but doesn't), I decided to post here. I am stumped. Nothing I seem to do using local/global-set/unset-key is working to change default mappings. Nothing! It just seems that the active bindings are carved in stone.

I've restarted emacs a half-dozen times troubleshooting this. Needless to say, no change.

My .emacs does nothing fancy. I cannot imagine that my customization could have anything to do with this abhorrent behavior. What's up, emacs?! Non-customization?!!!

Version data follows below:

GNU Emacs 26.1 (build 1, x86_64-w64-mingw32) of 2018-05-30. AUCTeX-version is a variable defined in ‘tex-site.el’. Its value is "12.1.1"

C-M-i runs the command flyspell-auto-correct-word (found in flyspell-mode-map), which is an interactive compiled Lisp function in ‘flyspell.el’. It is bound to C-., C-M-i.


My local-set-key and local-unset-key, used interactively ("M-x ..."), are failing to do exactly what they supposed to, namely to bind or unbind a key for a specific buffer.

That's not what they're supposed to do. Can you please point to any documentation or article which caused you to think this? (If it's a documentation problem, it should be fixed.)

What those commands do is to bind/unbind a key sequence in the local keymap, which is usually the keymap for the current major mode.

  1. That affects all buffers (current and future) using that major mode.

  2. The local keymap is just one of a larger set of keymaps which are checked in priority sequence when looking up a key binding. If the key sequence is bound in any higher-priority keymap than the local map, the local binding will not be used.

Mastering Emacs provides an excellent article explaining much of the complexities of Emacs keymaps, and you should definitely read it.

  • Thanks for the answer. Emacs keymaps are complex. Reading the documentation for local-set-key (I am reading it right now), I still fail to see how, in the absence of an entire mini-course on emacs keymaps, a sensible reader could reach any conclusion other than that the effect of the function would be to rebind a key for the buffer (and also for other buffers in the same major mode). There is absolutely no mention that active minor modes can de facto nullify the effect of local-set-key. As a user, I would more than welcome a footnote to the docstring clarifying this. – Eduardo Dueñez Jun 8 at 15:03
  • Which docstring? Where did you look? You can always open a documentation bug and see if things can be improved. BTW, don't asnwer the question here: comments in EmacsSE are not for bug reporting. But if you can answer these questions clearly and/or have a suggestion of how to improve things, by all means open a bug: that's the only way things can improve. – NickD Jun 8 at 17:39
  • 1
    @NickD I was referring to the docstring for local-set-key. Reading it, I would never have guessed that it was not the "right" way to change keybinding for emacs (on the fly). I know that EmacsSE is not for bug reporting. I'm not sure if this counts as a "bug" best reported upstream to emacs developers, but I'm sure it's confusing to other non-experts like me. – Eduardo Dueñez Jun 8 at 23:05

flyspell-mode only optionally binds flyspell-auto-correct-word to <M-tab> and to C-.. That has been so for a very long time (at least Emacs 23).

Switch the binding for <M-tab> off by the customizing the option flyspell-use-meta-tab to off. One way to do so is by clicking the menu item
Options->Customize Emacs->Specific Option and typing flyspell-use-meta-tab RET
another by typing M-x customize-option RET flyspell-use-meta-tab RET.
You can use tab-completion for the input of flyspell-use-meta-tab.

If the value of that option is on toggle it of.

If you dislike Customize for any reason, you can also set flyspell-use-meta-tab to nil in your init file.

  • Thanks. This is useful to solve the immediate problem I'm having, but I accepted phils's answer because it explains what the real reason for failure is. – Eduardo Dueñez Jun 8 at 15:04

You should complain to the flyspell maintainers: they are wasting a key sequence.

That said, the reason the above is not working is that emacs checks a sequence of keymaps: first the keymap specified by the keymap property (text or overlay), then the keymaps of the enabled minor-modes, then the local keymap that the major mode installs and then the global map. local-set/unset-key operates on the local map, so it cannot override the minor mode keymap. These details can be found in the elisp manual.

One way to deal with the problem is to zap the offending entry in the flyspell keymap:

(define-key flyspell-mode-map (kbd "C-M-i") nil)
  • Thanks, Nick. This clarification essentially answers my question. I wish I could accept two answers. I accepted @phils 's because I found the Mastering Emacs article much more helpful than the elisp documentation. – Eduardo Dueñez Jun 8 at 15:10
  • Just fyi: you can only accept a single answer but you can upvote (or downvote) as many answers as you wish. – NickD Jun 8 at 17:30
  • And BTW, reading things like "Mastering Emacs" is fine, but I guarantee that eventually you will have to go to the elisp manual for answers: why not start early? ;-) – NickD Jun 8 at 17:35
  • Actually, the upvoting part is not quite true: you need a small amount of reputation (15 if I read things correctly). And there are limits to how many upvotes you can make per day. – NickD Jun 8 at 17:44

Not the answer you're looking for? Browse other questions tagged or ask your own question.