Failed Vim Upgrade: Reinstall System Runtime vs. Restore Full Backup to Avoid Mixing Plugin Versions

Direct answer

Reinstall or rebuild the Vim package so the executable and $VIMRUNTIME come from the same build, and keep your existing ~/.vim. A full restore of both $VIMRUNTIME and ~/.vim is safer only when that backup is the exact state you want to return to and losing later changes is acceptable.

Why the mixed runtime is the real problem

After a failed upgrade, the most likely inconsistency is inside $VIMRUNTIME: some files may be from the old package while the binary is new, or vice versa. Because ~/.vim is normally additive and sits earlier in &runtimepath, preserving it during a package reinstall usually does not reintroduce the same class of mismatch. Restoring an old ~/.vim alongside a newer binary, however, recreates the mismatch in reverse and can hide the original failure.

When a full restore is the right choice

Choose the full backup only if:

• The backup predates the failed upgrade and represents a known-good state you want.
• You are willing to discard plugin or configuration changes made after that backup.
• The backup itself is verified to contain a consistent $VIMRUNTIME and ~/.vim pair.

If the backup was taken after the failed upgrade, it may already contain mixed files; restoring it blindly would not fix the inconsistency.

Handling local edits to system runtime files

Do not copy an old $VIMRUNTIME over a newer one, and do not assume a package reinstall preserves local edits—conffile and overwrite policies vary by distribution. Instead:

1. Diff your modified files against the package's clean versions and save the patch.
2. Reinstall or rebuild the Vim package to restore a clean, consistent runtime.
3. Reapply only the necessary changes through ~/.vim/after or another user runtimepath entry rather than editing $VIMRUNTIME directly.

The one diagnostic that changes the recommendation

Run vim --version and check :version inside Vim. If the installed binary is not the version you intend to run, the recommendation flips: force the exact package version or rebuild that version first, then reconcile plugins. If the binary is correct but the runtime is suspect, reinstall the matching package and keep ~/.vim.

Verification after recovery

Confirm the active version and loaded scripts:

vim --version
vim -u NONE -N -c 'echo $VIMRUNTIME' -c 'echo &runtimepath' -c 'qa!'

Then start normally and inspect :scriptnames and :messages for sourcing errors, duplicate plugin loads, or help-tag complaints. Exercise plugins that depend on newer script or API features in a scratch file. If they pass under vim --clean but fail with your configuration, the issue is plugin/config rather than runtime consistency.