Learn Vim Safely with the Installed vimtutor

You will finish with the Vim tutor open in a disposable practice copy, know how to select a translated tutor, and understand what happens when you close it. The tutor is designed for hands-on work, so expect about 30 minutes if you follow the exercises rather than only reading them.

This guide is for the Vim 9.1.0016 package installed on this machine, provided by vim-runtime version 2:9.1.0016-1ubuntu7.20. The exact lesson text and available translations can differ on another Vim package.

1. Check the installed command

Run these ordinary, read-only checks from a shell. You do not need sudo:

$ command -v vimtutor
/usr/bin/vimtutor
$ vim --version | sed -n '1,4p'
VIM - Vi IMproved 9.1 (2024 Jan 02, compiled Aug 24 2026 22:13:04)
Included patches: 1-16, 647, 678, 697
Modified by [email protected]
Compiled by [email protected]
$ dpkg-query -W -f='${Package} ${Version}\n' vim-runtime
vim-runtime 2:9.1.0016-1ubuntu7.20

Your build date and patch list may change after an update. The useful checkpoint is that the command resolves to an installed Vim runtime, rather than a wrapper from an unexpected directory.

2. Start the English tutor

Run:

$ vimtutor

Vimtutor first copies the tutor file, then starts Vim on that copy. Vim is launched without your normal Vim configuration, so your aliases, plugins and personal key mappings do not distract from the lesson. The installed manual says Vim is started in Vi compatible mode during the copy step; the launcher then starts the tutor with compatibility disabled and command feedback visible.

Inside the tutor, follow the on-screen instruction to move down to the first lesson. The lesson changes the text as you practise. That is intentional: the file is a sandbox, not a document you should expect to keep.

3. Understand the temporary copy

The original tutor is installed under the Vim runtime, currently at /usr/share/vim/vim91/tutor/tutor. Vimtutor does not ask you to edit that file directly. It creates a uniquely named copy below TMPDIR, or below /tmp when TMPDIR is unset, and removes the copy when the program exits.

This boundary matters:

• your exercises cannot overwrite the packaged lesson;
• you do not need elevated privileges to practise;
• changes in the tutor disappear when you close it unless you deliberately save a copy elsewhere.

Do not use sudo vimtutor. It is unnecessary for the packaged runtime and makes any accidental files or configuration changes harder to reason about. If you need to keep notes, use Vim's save-as command from inside the tutor to write to a path you own, for example :saveas ~/vim-practice.txt. Check the path before confirming the write. The temporary tutor will still be removed when you leave, but the separately saved file will remain.

4. Choose a language explicitly

The optional argument is a two-letter language name. For French, use:

$ vimtutor fr

If the requested translation is installed, it is used. Otherwise the launcher falls back to English. The same applies when you omit the argument: the current locale is considered first, and English is the fallback when a matching tutor is unavailable.

Language selection is not a shell translation feature. It chooses a tutor file, and the available names depend on the files installed by your vim-runtime package. To see the local candidates without changing anything:

$ find /usr/share/vim/vim91/tutor -maxdepth 1 -type f -name 'tutor.*' -printf '%f\n' | sort | head

Seeing a file such as tutor.fr.utf-8 is evidence that a French UTF-8 tutor is present. It does not mean every possible locale name has a translation. Use the short code documented by the command's manual, then let the launcher choose the matching encoding.

5. Use the GUI only when it is installed

The -g option asks vimtutor to use gvim if a GUI Vim is available. If it is not, the launcher falls back to Vim:

$ vimtutor -g

This option changes the editor frontend, not the lesson or the safety boundary. The tutor is still copied before it is opened. A headless server will normally have no gvim, so expect a terminal Vim session there.

Check before choosing the option:

$ command -v gvim || echo 'gvim is not installed; use terminal Vim'
gvim is not installed; use terminal Vim

Do not install a GUI package solely to make the tutor work. Terminal Vim is the normal, supported path on a remote shell, container or server.

6. Exit without losing control of the terminal

When you have finished a lesson, leave Vim with:

:q!

Press Esc first if you are in Insert mode, type the command, then press Enter. :q! quits without saving the temporary tutor. That is a safe default when you only want to practise. If you used :saveas for notes, that separate file has already been written; quitting the tutor does not remove it.

If Vim refuses to quit because it considers the buffer changed, use :q!, not repeated control keys. If you accidentally leave Vim in a strange mode, press Esc two or three times, then type the command. If the terminal remains in an odd display state after an interrupted session, run reset at the shell and press Enter. This resets terminal presentation; it does not restore unsaved tutor edits.

7. Diagnose the common failures

If the shell reports vimtutor: command not found, the launcher is absent or not on PATH. Check the package and command lookup:

$ dpkg-query -W -f='${Status} ${Version}\n' vim-runtime
$ command -v vim
/usr/bin/vim

If vim-runtime is not installed, use your normal package-management process to install it. That is an administrative change and may require elevated privileges. Do not work around a missing runtime by editing files under /usr/share/vim by hand.

If a requested language prints a message that its tutor file does not exist, the launcher is doing what it should: it copies the English version. Rerun with a translation confirmed by the file check, or omit the language argument.

If the copy step fails, inspect the temporary directory without deleting anything:

$ printf 'TMPDIR=%s\n' "${TMPDIR:-/tmp}"
$ test -d "${TMPDIR:-/tmp}" && test -w "${TMPDIR:-/tmp}" && echo 'temporary directory is writable'

A read-only or unavailable temporary directory prevents vimtutor from creating its practice copy. Fix the directory through your system's normal administration, then rerun the command. Avoid changing permissions on a broad shared directory just to get one lesson started.