Vimの<Leader>キーとは？mapleaderの設定とキーマッピングの使い分け

他の人のvimrcを見ていると、必ずと言っていいほどlet mapleader = " "のような行が出てきます。最初はおまじないだと思って読み飛ばしていましたが、これを理解しないまま自己流のキーマッピングを増やしていくと、標準機能と衝突して思わぬ動作をする羽目になります。

目次（7項目）

• <Leader>キーが必要な理由
• mapleaderを設定する
• 設定する「順番」でハマる
• <Leader>を使ったマッピングの書き方
• 増やしすぎると結局覚えられない
• まとめ
• 関連記事

<Leader>キーが必要な理由

Vimはノーマルモードのほとんどのキーにすでに何らかの機能が割り当たっています。自分用のマッピングを増やそうとすると、既存の機能を上書きしてしまうことがよくあります（空いているキーを探したいなら未割り当てキーの一覧が参考になります）。<Leader>はそのための逃げ道で、「このキーに続けて入力したものは自分用のマッピングだ」という名前空間を作れます。公式ヘルプでは次のように説明されています。

To define a mapping which uses the "g:mapleader" variable, the special string "<Leader>" can be used. It is replaced with the string value of "g:mapleader". If "g:mapleader" is not set or empty, a backslash is used instead.

特に設定していない場合、<Leader>はバックスラッシュ（\）に割り当てられています。今の<Leader>キーを確認したい場合は次のコマンドで確認できます。

:echo mapleader

E121: Undefined variable: mapleaderと表示された場合は、まだ変更されておらずデフォルトの\のままです。

mapleaderを設定する

init.luaやvimrcの先頭に次のように書きます。Neovimではinit.luaにLuaで書くのが標準になりましたが、mapleaderそのものはVim script時代から変わっていないので、無印のVimでも同じ考え方で使えます。

" vimrcの場合
let mapleader = "\<Space>"

-- init.luaの場合
vim.g.mapleader = " "

どのキーに割り当てるかは好みですが、代表的な候補はこうです。

• <Space>：押しやすい位置にあり、ノーマルモードで単体のスペースキーはあまり使われていないため最も人気
• ,（カンマ）：ホームポジションに近く押しやすい
• _（アンダースコア）：既存のマッピングと衝突しにくい

どれが正解ということはなく、自分が押しやすい位置を選べます。

設定する「順番」でハマる

ここが<Leader>で最も多い落とし穴です。<Leader>はマッピングを定義したその瞬間に実際のキーへ置き換えられます。あとからmapleaderを変えても、すでに定義済みのマッピングは付け替わりません。

手元のVim 9.1で、mapleaderの設定を挟んで前後にマッピングを1つずつ定義して確かめました。

nnoremap <Leader>a :echo "A"<CR>   " 設定より前に定義
let mapleader = "\<Space>"
nnoremap <Leader>b :echo "B"<CR>   " 設定より後に定義

この状態で実際に割り当てられたキーを調べると、次のように分かれました。

つまりlet mapleaderは設定ファイルのいちばん先頭に置く必要があります。「スペースをLeaderにしたのに一部のマッピングだけ効かない」という症状は、ほぼこれが原因です。

効いているキーは:nmapで分かる

診断のこつは、:nmapなどの一覧が<Leader>ではなく展開後のキーを表示することです。先ほどの状態で:nmapを実行すると、こう出ました。

n  <Space>b    * :echo "B"<CR>
n  \a          * :echo "A"<CR>

意図した<Space>ではなく\側に並んでいるマッピングがあれば、それはmapleaderの設定より前に定義されたものです。

プラグインを読み込む前に設定する

同じ理由で、プラグインが定義するマッピングにも順番が効いてきます。プラグインマネージャの読み込みより後にmapleaderを設定すると、プラグイン側の<Leader>マッピングが\に付いてしまいます。lazy.nvimのドキュメントも、この点をブートストラップコードのコメントで明示しています。

Make sure to setup `mapleader` and `maplocalleader` before loading lazy.nvim so that mappings are correct.

これはlazy.nvimに限った話ではなく、プラグインを読み込む仕組み全般に当てはまります。Neovim 0.12から本体に入ったvim.packを使う場合も同じで、vim.pack.add()より前にvim.g.mapleaderを書いておかないと、プラグイン側の<Leader>マッピングが\に付きます。設定ファイルの1行目に置く、と覚えておくのが確実です。

maplocalleaderという別枠もある

mapleaderと対になるのがmaplocalleaderで、<LocalLeader>として使います。特定のファイルタイプでだけ有効にしたいマッピング（ftpluginの中で定義するもの）に使い分けるのが本来の用途です。手元でlet maplocalleader = ','としてから<LocalLeader>cを定義すると、期待どおり,cに割り当たりました。全体用と各ファイルタイプ用でキーを分けておくと、衝突がさらに減ります。

スペースにすると押した直後に1秒待たされる

<Space>をLeaderにすると、スペースを押してから何も入力しなかったときに一拍置いてカーソルが右へ動きます。Vimは「後続のキーが来て<Space>wのようなマッピングになるのか、それとも<Space>単体なのか」を判断するために待つからです。この待ち時間は'timeoutlen'で決まり、VimもNeovimも既定は1000ミリ秒でした。

:set timeoutlen?
  timeoutlen=1000

実際、let mapleader = "\<Space>"としてマッピングを足しても、<Space>単体には何も割り当たりません。手元でmaparg()を引くと空が返り、Vim標準の「1文字右へ移動」がそのまま残っている状態です。この右移動が邪魔なら、単体のスペースを潰しておきます。

nnoremap <Space> <Nop>
let mapleader = "\<Space>"

<Nop>は「何もしない」を意味する特別な指定です。これを当てても<Space>wのような後続付きのマッピングは生きたままであることを確認しました。待ち時間そのものを短くしたい場合はset timeoutlen=500のように詰められますが、短くしすぎると<Leader>に続くキーを打つ前に打ち切られるので、300ミリ秒を下回るあたりから使いにくくなります。

<Leader>を使ったマッピングの書き方

-- init.luaの場合
vim.keymap.set('n', '<Leader>w', ':w<CR>', { desc = '保存' })
vim.keymap.set('n', '<Leader>q', ':q<CR>', { desc = '終了' })

" vimrcの場合
nnoremap <Leader>w :w<CR>
nnoremap <Leader>q :q<CR>

nnoremap（Luaならvim.keymap.set('n', ...)）を使うのが基本です。nmap系ではなくnoremap系を使うことで、マッピングの中で他のマッピングが再解釈されず、意図しない挙動を防げます。

増やしすぎると結局覚えられない

<Leader>を使えば衝突を気にせずマッピングを増やせますが、増やせば増やすほど自分でも覚えていないマッピングが溜まっていきます。今どんなマッピングを定義済みか忘れたときは:verbose mapで一覧を確認できます。よく使う操作だけに絞り、たまにしか使わない操作はコマンドラインで直接打つほうが結局は速い、ということも少なくありません。

数を減らしたくないなら、覚える負担のほうを機械に肩代わりさせる手もあります。which-key.nvim（Vimならvim-which-key）を入れると、<Leader>を押した時点で候補のキーと説明がポップアップで出るので、思い出せなくても一覧から選べます。vim.keymap.setのdescに書いた説明がそのまま表示されるため、マッピングを足すときに一言添えておくと後から効いてきます。

まとめ

<Leader>キーは、既存の機能と衝突せずに自分用のマッピングを増やすための仕組みです。mapleaderを押しやすいキーに設定し、noremap系で定義します。増やしすぎず、実際に使うものだけに絞るのが長続きのコツです。

関連記事

• Vimで独自キーマッピングに使える未割り当てキー一覧
• 設定したキーマッピングの一覧を確認する（:map / :verbose map）
• ESCキーの代わりになるキー（Ctrl-[ と Ctrl-c の違い）