How do I run Normal mode commands in a script without triggering my custom mappings?

Explanation

:normal {keys} executes keystrokes as if typed in Normal mode — but it respects your custom mappings and abbreviations. Adding ! (:normal! {keys}) bypasses all user-defined mappings and uses only Vim's built-in key behaviour. This is critical in scripts, plugins, and macros intended to work consistently across different vimrc configurations.

How it works

• :normal {keys} — runs keys in Normal mode, honouring user mappings
• :normal! {keys} — runs keys in Normal mode, ignoring all mappings (uses default Vim behaviour)
• The ! form is always preferred in scripts and plugins to avoid interference from the user's vimrc
• Works across a range: :%normal! A; appends ; to every line in the file
• Combine with :g to target specific lines: :g/TODO/normal! I//

Example

If a user has mapped 0 to something custom:

nnoremap 0 ^   " go to first non-blank instead of column 0

Then :normal 0 would run ^, not go to column 0. But :normal! 0 always goes to column 0, regardless of mappings.

In a script that appends a semicolon to every non-empty line:

:g/./normal! A;

Tips

• In plugin development, always prefer :normal! over :normal for predictability
• You can use special keys in :normal! using execute: :execute "normal! i" . word . "\<Esc>" inserts a variable word
• :normal! cannot be followed by a colon (:) to start an Ex command — use feedkeys() for that
• The \<CR>, \<Esc>, \<C-v> etc. in execute strings work as expected for complex key sequences