Vim Editor Set Number (default)

Tip 626PrintableMonobookPreviousNextcreated 2003 · complexity basic · version 6.0

What is vimrc?Edit

The vimrc file contains optional runtime configuration settings to initialize Vim when it starts. On Unix based systems, the file is named .vimrc, while on Windows systems it is named _vimrc. :help vimrc

You can customize Vim by putting suitable commands in your vimrc. Here is a very simple example:

" Always wrap long lines:
set wrap

Lines that begin with ” are comments and are not read by vim.

Search for file vimrc_example.vim in your Vim files for another example. :help vimrc-intro:help vimrc_example.vim

To customize Vim for editing a specific file, or a specific type of file, you can use modelines, or auto commands, or filetype plugins. :help auto-setting:help filetype

Location of vimrcEdit

In Vim, your home directory is specified with $HOME. On Unix systems, this is your ~ directory. On Windows systems, the best way to find the value of $HOME is from within Vim, as follows. These commands are useful to see what directories your Vim is using:

:echo expand('~')
:echo $HOME
:echo $VIM

Note the ‘system vimrc file’ and ‘user vimrc file’ paths displayed by the :version command. The system vimrc file can be created by an administrator to customize Vim for all users. In addition, each user can have his or her own user vimrc.

The output from :version includes the paths of the system and user vimrc and gvimrc files. For example:

If the gvimrc files exist, they are used to configure Vim when the GUI version (gvim) runs (after settings from vimrc are applied).

Settings for gvim can also be placed in the vimrc file using a has('gui_running') check:

Although this can be useful to avoid the clutter of both a vimrc and gvimrc file, using the gvimrc file has distinct benefits over the “gui_running” check. The most notable being that a gvimrc file is sourced when using the :guicommand to change a vim session into a gvim session. Anything that was in the vimrc inside a “gui_running” check will not be applied since the vimrc is only sourced when Vim initially starts.

Vim can be configured so that, when starting, it reads commands from a vimrc file in the current directory, after reading the primary vimrc. This is configured by adding set exrc to the primary vimrc file. Setting 'exrc' can be a security problem because it means Vim will execute commands from any vimrc file in the directory where Vim is started. :help ‘exrc’ For that reason, set the ‘secure’ option if you use this option, and you may also want to limit setting this option to when Vim is started from known “safe” directory trees:

If Vim finds your vimrc file during startup, Vim will set the MYVIMRC environment variable to the full path of the vimrc file. Similarly, if your gvimrc file is found, the MYGVIMRC variable is set. Therefore, you can easily edit these files from within Vim:

Using file name completion, you could type :e $M then press Tab until you see the desired variable. If you only want to see the path, type :echo $M then press Tab to see the variable, and press Enter.

In gvim, the Edit menu includes “Startup Settings” which will use $MYVIMRC to edit your vimrc file. If $MYVIMRCdoes not exist, “Startup Settings” will create a new file using the “user vimrc file” path shown by the :versioncommand.

After you have saved changes to your vimrc file, you can see the results by exiting from Vim, then starting Vim again.

If you are making frequent changes, you might want to “source” (execute) the changed vimrc file without exiting:

Warning You may need to plan your vimrc so re-sourcing does not cause problems. If you define commands, functions, or autocmds, you must make them remove or override the previous version when sourced, or you will get errors (for commands and functions) or duplicates (for autocmds). Here are some examples that will work correctly when re-sourced:

Some errors in your vimrc may prevent Vim from starting successfully. A reliable way to handle that would be to rename your vimrc file, then edit the renamed file, then give it the correct name. Alternatively, you could start Vim with a command like this (or use “gvim” if that is how you run Vim):

The -N starts in “not compatible” mode (that is, with extra Vim features). The NONE argument (must be uppercase) skips initializations and does not read any vimrc file (-u), and does not read any gvimrc file (-U).

You could now use the :version command to show the vimrc path, then enter a command to edit that file.


  • What else is needed to explain what vimrc is, and how to use it, for a beginner?
  • Do something with the following text from the original tip (if keep it, need to fix text because it assumes you have used some standard setup for installation, and assumes $VIM and $HOME are some default, and of course is for Windows):

On Windows, when you start Vim normally, it *either* runs the file “C:\Documents and Settings\(user name)\_vimrc” (where “(user name)” is replaced by the actual user name); *or*, if that file doesn’t exist (it usually doesn’t, for most users), it runs the file “C:\Program Files\vim\_vimrc”. Note that if you have more than one disk your home may be different; do an “:echo $HOME” to know where is your home. You should also see the _viminfo file in that directory.

  • Include information for Windows:
    • When $HOME is not defined, it is created by combining $HOMEDRIVE and $HOMEPATH (if defined).
    • The recommended method to define $HOMEDRIVE and $HOMEPATH is to set the “Home folder … Local path” on the Profile tab of the User properties in Local Users and Groups (run lusrmgr.msc).
    • I’d say that this (the item above) is the recommended method to set your home folder in Windows. The recommendes method to specify where your _vimrc is located (if it differs from your home folder) is to set the $HOME environment variable. (Spiiph 00:16, 29 July 2009 (UTC))
  • Link to the #vim-approved .vimrc? 😉 (Spiiph 00:18, 29 July 2009 (UTC))

Proposal Omit suggestions like the following that attempt to auto-source vimrc. I suspect that anyone needing to read a tip to do this could get themselves in quite a bit of trouble. IMHO it’s a lot more sensible to map a key to source a script so you can control when it is sourced. I haven’t bothered to put such a mapping in the tip so far because the :so % info seems more helpful, and entirely adequate. —JohnBeckett 11:56, 23 August 2008 (UTC)

To source changes immediately, add to vimrc:

Why not use a BufWritePost instead of BufLeave, so it will source whenever you save?

Getting started tip … I hit this page because I could not remember the “mkvim” command. I found it elsewhere and thought I’d throw it in here. If you open vim, change some settings and get things how you like you can use this command

to automatically make a vimrc file based on your current settings. The [file] part is optional; vim will use ~/.vimrc by default. If you already have a .vimrc and you attempt this you we will be warned that .vimrc already exists. You can use

to overwrite the existing file if you like. However once you do this your original .vimrc file is gone so you may want to back up any existing .vimrc before you try this.

Using :mkvimrc to create .vimrc isn’t a terribly good idea, since it saves mappings and abbreviations setup by plugins. It can be useful to copy currently set options to .vimrc however. (Spiiph 14:51, 27 July 2009 (UTC))

It is sometimes useful to display line numbers in the left margin, for reference. Or to display current line/column in the status line, `set ruler` in your ~/.vimrc file.

Enabling left-margin display

To display line numbers:

:set number


:set nu


This will turn off the line number display:

:set nonumber


:set nonu

The following command is useful because it toggles the display of line numbers. Assuming no numbers are currently displayed, this command will display them. Entering the command again will hide them.

:set nu!

Mapping to toggle line numbers

You can also define a mapping to toggle the option, for example:

:nmap <C-N><C-N> :set invnumber<CR>

By pressing Ctrl-N twice in normal mode, Vim toggles between showing and hiding line numbers.

If you want to be able to toggle line numbers both in normal and insert mode, you can define these two mappings (in this example, they’re bound to the F3 key):

noremap <F3> :set invnumber<CR>
inoremap <F3> <C-O>:set invnumber<CR>

Enabling line numbers on startupEdit

To enable line numbers on startup, simply add the following to your vimrc.

set number

Adding line numbers only to certain filesEdit

Create a filetype plugin for each filetype where you’d like to have numbering enabled (see :help ftplugin-overrule) and add the following line:

setl number

Changing gutter column widthEdit

If you have Vim version 7 or greater, you can change the width of the “gutter” column used for numbering:

:set numberwidth=3

You can use the number column for the text of wrapped lines:

:set cpoptions+=n

Finally, you can change the color used for the line numbers. For example:

:highlight LineNr term=bold cterm=NONE ctermfg=DarkGrey ctermbg=NONE gui=NONE guifg=DarkGrey guibg=NONE

Relative line numbersEdit

For some commands, it is easier to know how many lines a given bit of text is, relative to the current cursor position. For example, moving with j and k with a count like 5j; or deleting 8 lines with 8dd can be easier if you have an at-a-glance view of distance from the cursor line instead of distance from the top of the file as with :set number.

To display line numbers relative to the line with the cursor, use:

:set relativenumber


:set norelativenumber

‘relativenumber’ is not a complete replacement for ‘number’; rather, these two options interact so that you can show only relative numbers (number off and relativenumber on), only absolute line numbers (relativenumber off and number on), or show the absolute number on the cursor line and relative numbers everywhere else (both relativenumber and number on).