How do I define a mapping that only takes effect if the key is not already mapped?

Q: How do I define a mapping that only takes effect if the key is not already mapped?

`:map {key} {rhs}` The ` ` modifier causes Vim to **fail with an error** if you try to create a mapping for a key that is already mapped in that mode. Instead of silently overriding an existing binding, Vim surfaces the conflict so you can resolve it deliberately. This is most valuable in plugin scripts and modular vimrc setups where you want protection against accidental collisions. ## How it works ```vim :nnoremap f :Files ``` If ` f` is already mapped, Vim prints: ```text E227: mapping already exists for \f ``` And the mapping is NOT created. Without ` `, the new mapping silently replaces the old one. ## Example ```vim " In a plugin's autoload file — guard mappings defensively if !hasmapto(' MyPlugin') nnoremap mp MyPlugin endif ``` Combining ` ` with `hasmapto()` lets you provide a default binding while still respecting user overrides. ## Tips - Combine with ` ` and ` `: `:nnoremap ...` - To check if a key has a mapping: `:nmap {key}` or use `maparg('{key}', 'n')` in Vimscript - Plugin authors should use ` ` mappings and let users bind them — ` ` is a secondary defense - In Neovim Lua, `vim.keymap.set` has no built-in `unique` flag; use `vim.fn.hasmapto()` for the same guard pattern

Question

Accepted Answer

`:map {key} {rhs}` The `` modifier causes Vim to **fail with an error** if you try to create a mapping for a key that is already mapped in that mode. Instead of silently overriding an existing binding, Vim surfaces the conflict so you can resolve it deliberately. This is most valuable in plugin scripts and modular vimrc setups where you want protection against accidental collisions. ## How it works ```vim :nnoremap f :Files ``` If `f` is already mapped, Vim prints: ```text E227: mapping already exists for \f ``` And the mapping is NOT created. Without ``, the new mapping silently replaces the old one. ## Example ```vim " In a plugin's autoload file — guard mappings defensively if !hasmapto('MyPlugin') nnoremap mp MyPlugin endif ``` Combining `` with `hasmapto()` lets you provide a default binding while still respecting user overrides. ## Tips - Combine with `` and ``: `:nnoremap ...` - To check if a key has a mapping: `:nmap {key}` or use `maparg('{key}', 'n')` in Vimscript - Plugin authors should use `` mappings and let users bind them — `` is a secondary defense - In Neovim Lua, `vim.keymap.set` has no built-in `unique` flag; use `vim.fn.hasmapto()` for the same guard pattern

Answer

Explanation

How it works

Example

Tips

Related Tricks

How do I use lambda functions in Vimscript to filter or transform lists?

How do I create a dynamic abbreviation that inserts live content like the current date?

How do I change the cursor shape to a thin bar in insert mode and a block in normal mode in Neovim?

How do I set up a local leader key for file-type-specific mappings that don't conflict with global mappings?

How do I create a normal mode mapping that correctly captures and passes a count prefix to a function?