Installing Vim and Learning with vimtutor
Check which Vim build you have, install a full one on Linux, macOS or Windows, make it the editor Git and cron use, and get started with vimtutor.
By The Dark DebuggerUpdated 19 min read
This article gets a proper Vim onto your machine and wires it into the rest of your tools. You will check which build you have and what it can do, install a full build where needed, make Vim the editor that Git and crontab -e open, go through vimtutor, and write a small starter vimrc that does not break Vim's defaults. It assumes you have read Introduction to Vim and know how to quit.
Why the build you have matters
"Vim" is not one program. Distributions ship several builds compiled with different feature sets, and the differences show up as confusing failures rather than clear errors:
- You yank text with
"+yto paste it into a browser, and nothing arrives. Your build has no clipboard support, and Vim does not complain. - You copy your vimrc to a minimal server, type
vi, and the first thing you see isE319: Sorry, the command is not available in this version. - You create a two-line
~/.vimrc, and suddenly search no longer highlights as you type and the screen stops scrolling early.
All three are explained, reproduced and fixed below. It starts with one command.
Check what you already have
vim --version | head -n 5VIM - Vi IMproved 9.1 (2024 Jan 02, compiled Aug 24 2026 22:13:04)
Included patches: 1-16, 647, 678, 697
Modified by team+vim@tracker.debian.org
Compiled by team+vim@tracker.debian.org
Huge version without GUI. Features included (+) or not (-):Line 1 is the version (9.1). Line 2 lists the patches applied on top of it; distributions backport security fixes, so "9.1 with patches 1-16, 647, 678, 697" is how Ubuntu 24.04's package describes itself. Line 5 names the build: Huge here. After that comes a long table of features, each marked + (compiled in) or - (missing). Search it instead of reading it:
vim --version | grep clipboard-clipboard +keymap +printer +vertsplit
+ex_extra +mouse_netterm +syntax -xterm_clipboard-clipboard means this Vim cannot talk to the system clipboard. Inside Vim you can ask the same question with :echo has("clipboard"), which printed 0 (false) in the status line.
The features worth checking:
| Feature | What breaks without it |
|---|---|
+clipboard | "+y and "+p cannot reach the desktop clipboard |
+syntax | No syntax highlighting; syntax on is an error |
+eval | No Vimscript: if, let, functions and most plugins fail |
+python3 | Plugins written in Python do not load |
+terminal | No :terminal window inside Vim |
+persistent_undo | Undo history cannot survive closing the file |
Vim 9 comes in three feature sets: Tiny (the minimum), Normal and Huge (everything). Here is the full vim and the vim.tiny that Ubuntu also installs, side by side:
for v in vim vim.tiny; do
echo "$v: $($v --version | grep -oE '(Tiny|Normal|Huge) version|[+-](syntax|eval|clipboard|python3|terminal|persistent_undo)\>' | tr '\n' ' ')"
donevim: Huge version +terminal +persistent_undo -clipboard +python3 +eval +syntax
vim.tiny: Tiny version -terminal -persistent_undo -clipboard -python3 -eval -syntax vim-tiny vs full Vim on Ubuntu
Ubuntu and Debian ship two packages: vim-tiny (the Tiny build, /usr/bin/vim.tiny) and vim (the Huge build, /usr/bin/vim.basic). Minimal and desktop installs often have only vim-tiny, and then the vi command points at it. Check what vi really runs on your machine:
readlink -f "$(command -v vi)"/usr/bin/vim.basicOn the test machine both packages are installed, and the alternatives system picked the full build. If yours prints /usr/bin/vim.tiny, expect the following.
The tiny build reads your ~/.vimrc too, but it cannot run half of what a normal vimrc contains. With a two-line vimrc (set number and syntax on), starting vim.tiny stopped on this (the first line, Error detected while processing followed by the vimrc's full path, is trimmed):
[…]
line 2:
E319: Sorry, the command is not available in this version: syntax on
Press ENTER or type command to continueText objects and Visual mode do work in the tiny build, but there is no syntax highlighting, no Vimscript, no plugins and no :help unless the runtime files happen to be installed. It is fine for a one-line fix on a server. It is not something to learn on.
The fix is to install the full package. Check what your package manager has first; this is read-only and needs no root:
apt-cache policy vim vim-tiny vim-gtk3 | grep -E '^[a-z]|Installed|Candidate'vim:
Installed: 2:9.1.0016-1ubuntu7.20
Candidate: 2:9.1.0016-1ubuntu7.20
vim-tiny:
Installed: 2:9.1.0016-1ubuntu7.20
Candidate: 2:9.1.0016-1ubuntu7.20
vim-gtk3:
Installed: (none)
Candidate: 2:9.1.0016-1ubuntu7.20Installing on Linux
Pick the line for your distribution:
# Debian, Ubuntu, Linux Mint, WSL Ubuntu
sudo apt update && sudo apt install vim
# Same, but with clipboard support (+clipboard) for desktop use
sudo apt install vim-gtk3
# Fedora, RHEL, Rocky, AlmaLinux (the "vim" command comes from vim-enhanced)
sudo dnf install vim-enhanced
# Arch Linux
sudo pacman -S vimvim-gtk3 is worth knowing about even if you never use the GUI. It installs a vim that runs in the terminal like any other but is compiled with +clipboard, so "+y puts text where Ctrl-V in your browser can find it. On a headless server there is no desktop clipboard to talk to, so plain vim is the right choice there.
After installing, run vim --version | head -n 5 again and check that the build line says Huge (or at least Normal).
Installing on macOS
macOS includes a vim in /usr/bin, but it is Apple's build and lags behind. The usual route is Homebrew:
brew install vim # current terminal Vim
brew install --cask macvim # optional: a native macOS GUI versionHomebrew puts its vim ahead of /usr/bin/vim on your PATH. Open a new terminal, then confirm which one you get with command -v vim and vim --version | head -n 5.
Installing on Windows
You have three realistic options:
- Vim inside WSL. If you already use WSL, install Vim there with
aptexactly as on Ubuntu. Every example in this path was tested this way. - The Vim that comes with Git for Windows. Git Bash includes a Vim, and it is what
git commitopens by default on Windows. On the Windows 11 machine I tested on (Git for Windows 2.35.1), PowerShell showed:
& 'C:\Program Files\Git\usr\bin\vim.exe' --version | Select-Object -First 3
& 'C:\Program Files\Git\usr\bin\vim.exe' --version | Select-String -Pattern 'clipboard|vimrc file'VIM - Vi IMproved 8.2 (2019 Dec 12, compiled Nov 22 2021 19:31:05)
Included patches: 1-3582
Compiled by <https://www.msys2.org/>
+clipboard +keymap +printer +vertsplit
+emacs_tags -mouse_gpm +statusline -xterm_clipboard
system vimrc file: "/etc/vimrc"
user vimrc file: "$HOME/.vimrc"
2nd user vimrc file: "~/.vim/vimrc"It is an older Vim 8.2, but it has +clipboard and reads ~/.vimrc like Linux Vim does. A newer Git for Windows ships a newer Vim.
- Native Vim for Windows (gVim). Install it with
winget install vim.vim, or use the installer from vim.org. It gives yougvim(a GUI window) and a consolevim, both with+clipboard. Native Windows Vim reads_vimrc(underscore, not dot) from your user profile folder, orvimfiles\vimrc.
A note on Neovim
Neovim installs as nvim (sudo apt install neovim, brew install neovim, winget install Neovim.Neovim) and reads its configuration from ~/.config/nvim/init.vim or init.lua instead of ~/.vimrc. Everything in this path works the same in Neovim's Normal mode. It was not installed on the test machine, so nothing here was run in it.
Make Vim your default editor
Programs that need an editor look at environment variables. VISUAL is the full-screen editor and EDITOR the fallback; most tools try VISUAL first. Put both in ~/.bashrc:
export EDITOR=vim VISUAL=vimGit has its own order of precedence, and git var GIT_EDITOR shows which editor Git will actually start. I ran it with different settings, starting from a clean configuration:
git var GIT_EDITOR
EDITOR=vim git var GIT_EDITOR
VISUAL=nvim EDITOR=vim git var GIT_EDITOR
git config --global core.editor vim
VISUAL=nano git var GIT_EDITOR
GIT_EDITOR=nano git var GIT_EDITOReditor
vim
nvim
vim
nanoReading those top to bottom: with nothing set, Git falls back to editor (on Ubuntu that resolves to nano). EDITOR beats the fallback, VISUAL beats EDITOR, core.editor in your Git config beats both, and the GIT_EDITOR environment variable beats everything. If you only do one thing, run git config --global core.editor vim; it works no matter what your shell variables say.
Debian and Ubuntu add one more layer: sensible-editor, which crontab -e uses when VISUAL and EDITOR are unset. The first time you run crontab -e with neither variable set, you get a menu:
no crontab for sid - using an empty one
Select an editor. To change later, run 'select-editor'.
1. /bin/nano <---- easiest
2. /usr/bin/vim.basic
3. /usr/bin/vim.tiny
4. /bin/ed
Choose 1-4 [1]:Choose 2 (full Vim, not vim.tiny). The choice is stored in your home directory:
cat ~/.selected_editor# Generated by /usr/bin/select-editor
SELECTED_EDITOR="/usr/bin/vim.basic"I quit that crontab -e session with :q without editing, and crontab replied No modification made, so it is a safe way to set the choice. select-editor shows the same menu any time. The system-wide editor command is a separate setting (update-alternatives --config editor), which needs root and was not changed on the test machine.
Learn the basics with vimtutor
vimtutor is a 30-minute interactive lesson that ships with Vim. It is a shell script that copies the tutorial text to a temporary file and opens Vim on the copy, so you can edit it freely; your real files are never touched. Run it:
vimtutorOn the test machine, whose locale is C.UTF-8, it first printed a note about the missing translation and then fell back to English:
The file /usr/share/vim/vim91/tutor/tutor.C..utf-8 does not exist.
Copying English version: /usr/share/vim/vim91/tutor/tutorThen it opened the lesson (trimmed):
===============================================================================
= W e l c o m e t o t h e V I M T u t o r - Version 1.7 =
===============================================================================
Vim is a very powerful editor that has many commands, too many to
explain in a tutor such as this. This tutor is designed to describe
enough of the commands that you will be able to easily use Vim as
an all-purpose editor.
The approximate time required to complete the tutor is 30 minutes,
depending upon how much time is spent with experimentation.
[…]
"/tmp/tutorAqM4db" 972 lines, 33583 bytesThe last line shows the copy in /tmp. The script also starts Vim with -u NONE, so your vimrc is ignored and the tutor looks the same for everyone. vimtutor es, vimtutor de and so on open translations.
The tutor has 33 short sections in 7 lessons:
| Lesson | Sections |
|---|---|
| 1 | Moving the cursor; exiting Vim; deletion; insertion; appending; editing a file |
| 2 | Deletion commands; operators and motions; counts with motions; counts to delete more; operating on lines; undo |
| 3 | Put; replace; the change operator; more changes using c |
| 4 | Cursor location and file status; search; matching parentheses; substitute |
| 5 | External commands; writing files; selecting text to write; retrieving and merging files |
| 6 | Open; append; another way to replace; copy and paste; setting options |
| 7 | Getting help; creating a startup script; completion |
Lessons 1 to 3 overlap with the next three articles in this path, and that repetition is useful. Do vimtutor once now and again after Editing Text; the second pass takes ten minutes and the commands stick much better.
A minimal, safe starter vimrc
Before you write a vimrc, you need to know about the trap that catches almost everyone. When Vim finds no user vimrc, it loads defaults.vim, a file of sensible settings: incremental search, a 5-line scroll margin, showing partial commands, and more. The moment ~/.vimrc exists, even an empty one, defaults.vim is no longer loaded. I checked four options with :set incsearch? scrolloff? showcmd? in both situations.
Without any vimrc:
incsearch
scrolloff=5
showcmdWith an empty ~/.vimrc:
noincsearch
scrolloff=0
noshowcmdSo the fix is to load the defaults yourself, first, and build on them. This is a starter file I am comfortable recommending to anyone; the full tour of options, mappings and plugins is in Configuring Vim:
" ~/.vimrc -- a small, safe starting point.
" Creating this file stops Vim from loading defaults.vim on its own,
" so load it explicitly first and build on top of it.
unlet! skip_defaults_vim
source $VIMRUNTIME/defaults.vim
set number " show line numbers
set hlsearch " highlight every match of the last search
set ignorecase " searches ignore case...
set smartcase " ...unless the pattern contains a capital letter
set expandtab " the Tab key inserts spaces
set shiftwidth=4 " >> and << shift by 4 columns
set softtabstop=4 " Tab and Backspace move 4 columns in Insert mode
set autoindent " a new line starts with the previous line's indentLines starting with " are comments. unlet! skip_defaults_vim undoes a variable some systems set to block defaults.vim, and source reads the file. With the file in place, :set number? hlsearch? ignorecase? smartcase? expandtab? shiftwidth? softtabstop? autoindent? incsearch? scrolloff? printed:
number
hlsearch
ignorecase
smartcase
expandtab
shiftwidth=4
softtabstop=4
autoindent
incsearch
scrolloff=5Everything from the file is on, and incsearch and scrolloff=5 survived because defaults.vim was loaded. When an option has a value you did not expect, :verbose set tells you which file set it and on which line:
:verbose set shiftwidth? shiftwidth=4
Last set from ~/.vimrc line 12Things I deliberately left out: set clipboard=unnamedplus (it does nothing on a -clipboard build and hides the real problem), set noswapfile (swap files are what let you recover from a crash), and set mouse=a (defaults.vim already enables the mouse where the terminal supports it).
Where you'll use this
Every new machine (a fresh laptop, a WSL install, a jump host, a dev container) needs the same few steps: check the build, set the editor variables, point Git at Vim and drop in a starter vimrc. A short script that is safe to run more than once does all of it:
#!/usr/bin/env bash
# setup-editor.sh - make Vim the editor for the shell and for git.
# Safe to run more than once: it only adds what is missing.
set -euo pipefail
if ! command -v vim >/dev/null 2>&1; then
echo "vim not found; on Ubuntu/Debian run: sudo apt install vim" >&2
exit 1
fi
echo "Using: $(vim --version | head -n 1)"
if vim --version | grep -q '+clipboard'; then
echo "Clipboard support: yes"
else
echo "Clipboard support: no (\"+y stays inside Vim)"
fi
line='export EDITOR=vim VISUAL=vim'
if grep -qxF "$line" ~/.bashrc 2>/dev/null; then
echo "EDITOR/VISUAL already set in .bashrc"
else
echo "$line" >> ~/.bashrc
echo "Added EDITOR/VISUAL to .bashrc"
fi
git config --global core.editor vim
echo "git core.editor = $(git config --global core.editor)"
if [ -e ~/.vimrc ]; then
echo ".vimrc exists; leaving it alone"
else
cat > ~/.vimrc <<'VIMRC'
unlet! skip_defaults_vim
source $VIMRUNTIME/defaults.vim
set number hlsearch ignorecase smartcase
set expandtab shiftwidth=4 softtabstop=4 autoindent
VIMRC
echo "Wrote a starter .vimrc"
fiIt passes shellcheck cleanly. The first run on a fresh account:
bash bin/setup-editor.shUsing: VIM - Vi IMproved 9.1 (2024 Jan 02, compiled Aug 24 2026 22:13:04)
Clipboard support: no ("+y stays inside Vim)
Added EDITOR/VISUAL to .bashrc
git core.editor = vim
Wrote a starter .vimrcThe second run changes nothing, which is the point. You can put it in a dotfiles repository or a provisioning step and run it on every machine:
Using: VIM - Vi IMproved 9.1 (2024 Jan 02, compiled Aug 24 2026 22:13:04)
Clipboard support: no ("+y stays inside Vim)
EDITOR/VISUAL already set in .bashrc
git core.editor = vim
.vimrc exists; leaving it aloneAnd the result, checked from a new shell:
tail -n 2 ~/.bashrc
bash -c 'source ~/.bashrc; echo "EDITOR=$EDITOR VISUAL=$VISUAL"'
git var GIT_EDITORalias ll="ls -alF"
export EDITOR=vim VISUAL=vim
EDITOR=vim VISUAL=vim
vimgrep -qxF matches the whole line literally (-x whole line, -F fixed string), which is what keeps the script from appending the export a second time. If the [ -e ... ] test and the heredoc are unfamiliar, Your First Scripts covers both.
Common mistakes
"+y "works" but nothing reaches the clipboard. On a -clipboard build, Vim does not report an error for the + register. It quietly uses its own unnamed register instead. On the test machine, "+yy followed by "+p duplicated the line inside Vim exactly as if the clipboard worked:
server {
server {
listen 80;
}But nothing ever left Vim. Check vim --version | grep clipboard. If it says -clipboard, install vim-gtk3 on a Linux desktop, or Homebrew Vim or gVim elsewhere. Over SSH there is no local clipboard for Vim to reach at all; you would need the terminal's own copy feature.
Your new vimrc "broke" Vim. Creating ~/.vimrc stops defaults.vim from loading, so incremental search, the scroll margin and partial-command display all switch off, as shown above. Start every vimrc with the two defaults.vim lines from the starter file.
A vimrc copied from Windows fails line by line. Windows line endings (CRLF) leave an invisible carriage return at the end of every line, and Vim reads it as part of the command (the Error detected while processing line is trimmed):
[…]
line 1:
E488: Trailing characters: number^M
line 2:
E521: Number required after =: shiftwidth=4^M
Press ENTER or type command to continue^M is the carriage return. file confirms it, and sed strips it:
cd ~
file .vimrc
sed -i 's/\r$//' .vimrc
file .vimrc.vimrc: ASCII text, with CRLF line terminators
.vimrc: ASCII textE319 when you type vi on a server. That is the tiny build reading a vimrc written for full Vim. Install the vim package, or run the full build explicitly with vim instead of vi where both exist.
Summary
vim --version | head -n 5tells you the version and build (Tiny, Normal, Huge); grep the feature list forclipboard,syntax,evalandpython3.- On Ubuntu/Debian,
vim-tinycannot runsyntax onor Vimscript (E319). Installvim, orvim-gtk3on a desktop for+clipboard. - Without
+clipboard,"+ysilently stays inside Vim. Check the build before you blame your mappings. - Git picks its editor in this order:
GIT_EDITOR,core.editor,VISUAL,EDITOR, then the system default.git config --global core.editor vimis the reliable fix, andgit var GIT_EDITORshows the result. - On Debian/Ubuntu,
crontab -eusessensible-editor;select-editorrecords your choice in~/.selected_editor. vimtutorworks on a temporary copy with your vimrc disabled: 7 lessons, about 30 minutes.- Any
~/.vimrc, even an empty one, stopsdefaults.vimfrom loading. Start yours withunlet! skip_defaults_vimandsource $VIMRUNTIME/defaults.vim, and use:verbose set option?to find where a setting came from.
Exercises
With one command, print your Vim's build size and whether it has clipboard and Python 3 support.
Show Solution
vim --version | grep -oE '(Tiny|Small|Normal|Big|Huge) version|[+-]clipboard|[+-]python3'Huge version
-clipboard
+python3grep -o prints only the matching parts. The test machine has a Huge build with Python 3 but no clipboard. (Small and Big are in the pattern because older Vims used those names too.)
Make Git use Vim for commit messages no matter what EDITOR says, and prove it without making a commit.
Show Solution
git config --global core.editor vim
git config --global --get core.editor
git var GIT_EDITORvim
vimgit var GIT_EDITOR resolves the full precedence chain, so it is the honest answer to "what will git commit open?". Only a GIT_EDITOR environment variable could override this setting.
Install the starter vimrc from this article as ~/.vimrc. Then, from inside Vim, find out which file and line turned expandtab on.
Show Solution
Save the file, open any file in Vim, and run:
:verbose set expandtab? expandtab
Last set from ~/.vimrc line 11Line 11 of the starter file is set expandtab. If a plugin or filetype script changes an option later, :verbose names that file instead, which is how you track down "why is my indentation wrong in this one file type".
Create a broken vimrc and repair it:
printf 'set number\r\nset shiftwidth=4\r\n' > ~/.vimrcStart Vim and read the errors. Fix the file from the shell, then confirm inside Vim that both settings took effect.
Hint
The errors end in ^M. That character is \r, and it sits at the end of every line.
Show Solution
cd ~
file .vimrc
sed -i 's/\r$//' .vimrc
file .vimrc.vimrc: ASCII text, with CRLF line terminators
.vimrc: ASCII textIn Vim, :set number? shiftwidth? now shows:
number
shiftwidth=4Remember to put your real vimrc back afterwards. When you edit dotfiles on Windows for use in WSL, set your Windows editor to LF line endings for those files.
The tutor text lives at /usr/share/vim/vim91/tutor/tutor on Ubuntu 24.04. Count its numbered sections (headings like Lesson 2.3) from the shell.
Show Solution
grep -cE 'Lesson [0-9]\.[0-9]' /usr/share/vim/vim91/tutor/tutor33-c counts matching lines. The pattern matches Lesson 1.1 to Lesson 7.3 but not the Lesson 1 SUMMARY lines, which have no dot.
Tested with: Vim 9.1.0016 (Ubuntu packages vim and vim-tiny 2:9.1.0016-1ubuntu7.20), Git 2.43.0 and ShellCheck 0.9 on Ubuntu 24.04 (WSL2), November 2026.
The Git for Windows Vim 8.2 output was captured with read-only --version calls on a Windows 11 host. No packages were installed or removed. The apt, dnf, pacman, brew and winget commands are shown but were not run (no root in the lab, and I did not change the Windows host), and Neovim was not tested.
Written by The Dark Debugger
Engineer documenting the things that took me too long to learn, so they take you less time. Every Vim tutorial here is tested end to end before publishing.