vim

Fork of vim, an acceptable text editor
git clone git://git.laack.co/vim.git
Log | Files | Refs | README | LICENSE

os_win32.txt (15550B)


      1 *os_win32.txt*	For Vim version 9.2.  Last change: 2026 Jul 22
      2 
      3 
      4 		  VIM REFERENCE MANUAL	  by George Reilly
      5 
      6 
      7 						*win32* *Win32* *MS-Windows*
      8 This file documents the idiosyncrasies of the Win32 version of Vim.
      9 
     10 The Win32 version of Vim works on Windows 7, 8, 10 and 11.  There are both
     11 console and GUI versions.
     12 
     13 If you have Windows XP or Vista then Vim 9.0 up to patch level 495 can be
     14 used.
     15 
     16 The 32 bit version also runs on 64 bit MS-Windows systems.
     17 
     18 1. Known problems		|win32-problems|
     19 2. Startup			|win32-startup|
     20 3. Restore screen contents	|win32-restore|
     21 4. Using the mouse		|win32-mouse|
     22 5. Running under Windows 95	|win32-win95|
     23 6. Running under Windows 3.1	|win32-win3.1|
     24 7. Installation package		|win32-installer|
     25 8. Win32 mini FAQ		|win32-faq|
     26 
     27 Additionally, there are a number of common Win32 and DOS items in |os_dos.txt|:
     28 File locations			|dos-locations|
     29 Using backslashes		|dos-backslash|
     30 Standard mappings		|dos-standard-mappings|
     31 Screen output and colors	|dos-colors|
     32 File formats			|dos-file-formats|
     33 :cd command			|dos-:cd|
     34 Interrupting			|dos-CTRL-Break|
     35 Temp files			|dos-temp-files|
     36 Shell option default		|dos-shell|
     37 PowerShell defaults		|dos-powershell|
     38 
     39 Win32 GUI			|gui-w32|
     40 
     41 Credits:
     42 The Win32 version was written by George V. Reilly <george@reilly.org>.
     43 The original Windows NT port was done by Roger Knobbe <RogerK@wonderware.com>.
     44 The GUI version was made by George V. Reilly and Robert Webb.
     45 
     46 For compiling see "src/INSTALLpc.txt".			*win32-compiling*
     47 
     48 							*WSL*
     49 When using Vim on WSL (Windows Subsystem for Linux) the remarks here do not
     50 apply, `has('win32')` will return false then.  In case you need to know
     51 whether Vim is running on WSL you can use `exists('$WSL_DISTRO_NAME')`.
     52 
     53 ==============================================================================
     54 1. Known problems					*win32-problems*
     55 
     56 When doing file name completion, Vim also finds matches for the short file
     57 name.  But Vim will still find and use the corresponding long file name.  For
     58 example, if you have the long file name "this_is_a_test" with the short file
     59 name "this_i~1", the command ":e *1" will start editing "this_is_a_test".
     60 
     61 ==============================================================================
     62 2. Startup						*win32-startup*
     63 
     64 Current directory					*win32-curdir*
     65 
     66 If Vim is started with a single file name argument, and it has a full path
     67 (starts with "x:\"), Vim assumes it was started from the file explorer and
     68 will set the current directory to where that file is.  To avoid this when
     69 typing a command to start Vim, use a forward slash instead of a backslash.
     70 Example: >
     71 
     72 	vim c:\text\files\foo.txt
     73 
     74 Will change to the "C:\text\files" directory. >
     75 
     76 	vim c:/text\files\foo.txt
     77 
     78 Will use the current directory.
     79 
     80 
     81 Term option						*win32-term*
     82 
     83 The only kind of terminal type that the Win32 version of Vim understands is
     84 "win32", which is built-in.  If you set 'term' to anything else, you will
     85 probably get very strange behavior from Vim.  Therefore Vim does not obtain
     86 the default value of 'term' from the environment variable "TERM".
     87 
     88 Terminal Colors						*win32-term-colors*
     89 
     90 The Win32 console supports 16 colors by default |dos-colors|.  From Windows 10
     91 version 1703 (Creators Update) onwards, the console supports 256 colors and
     92 true color (24-bit) when 'termguicolors' is set and Vim is built with support
     93 for Virtual Terminal Processing (VTP) |+vtp|.
     94 
     95 Virtual Terminal Processing is automatically enabled if either the
     96 'termguicolors' option is set or the 't_Co' option is set to 256.  This
     97 enables ANSI escape sequences for colors, improves rendering of multi-byte
     98 characters and enables other terminal features in the Windows console.
     99 
    100 The actual color rendering depends on whether your terminal supports VTP (such
    101 as Windows Terminal or the modern Windows 10/11 console).
    102 
    103 $PATH							*win32-PATH*
    104 
    105 The directory of the Vim executable is appended to $PATH.  This is mostly to
    106 make "!xxd" work, as it is in the Tools menu.  And it also means that when
    107 executable() returns 1 the executable can actually be executed.
    108 
    109 Command line arguments					*win32-cmdargs*
    110 
    111 Analysis of a command line into parameters is not standardised in MS-Windows.
    112 Vim and gvim used to use different logic to parse it (before 7.4.432), and the
    113 logic was also depended on what it was compiled with.  Now Vim and gvim both
    114 use the CommandLineToArgvW() Win32 API, so they behave in the same way.
    115 
    116 The basic rules are:					*win32-backslashes*
    117       a) A parameter is a sequence of graphic characters.
    118       b) Parameters are separated by white space.
    119       c) A parameter can be enclosed in double quotes to include white space.
    120       d) A sequence of zero or more backslashes (\) and a double quote (")
    121 	is special.  The effective number of backslashes is halved, rounded
    122 	down.  An even number of backslashes reverses the acceptability of
    123 	spaces and tabs, an odd number of backslashes produces a literal
    124 	double quote.
    125 
    126 So:
    127 	"	is a special double quote
    128 	\"	is a literal double quote
    129 	\\"	is a literal backslash and a special double quote
    130 	\\\"	is a literal backslash and a literal double quote
    131 	\\\\"	is 2 literal backslashes and a special double quote
    132 	\\\\\"	is 2 literal backslashes and a literal double quote
    133 	etc.
    134 
    135 Example: >
    136 	vim "C:\My Music\freude" +"set ignorecase" +/"\"foo\\" +\"bar\\\"
    137 
    138 opens "C:\My Music\freude" and executes the line mode commands: >
    139 	set ignorecase; /"foo\ and /bar\"
    140 
    141 These rules are also described in the reference of the CommandLineToArgvW API:
    142     https://msdn.microsoft.com/en-us/library/windows/desktop/bb776391.aspx
    143 
    144 							*win32-quotes*
    145 There are additional rules for quotes (which are not well documented).
    146 As described above, quotes inside a file name (or any other command line
    147 argument) can be escaped with a backslash.  E.g. >
    148 	vim -c "echo 'foo\"bar'"
    149 
    150 Alternatively use three quotes to get one: >
    151 	vim -c "echo 'foo"""bar'"
    152 
    153 The quotation rules are:
    154 
    155 1. A `"` starts quotation.
    156 2. Another `"` or `""` ends quotation.  If the quotation ends with `""`, a `"`
    157    is produced at the end of the quoted string.
    158 
    159 Examples, with [] around an argument:
    160         "foo"           -> [foo]
    161         "foo""          -> [foo"]
    162         "foo"bar        -> [foobar]
    163         "foo" bar       -> [foo], [bar]
    164         "foo""bar       -> [foo"bar]
    165         "foo"" bar      -> [foo"], [bar]
    166         "foo"""bar"     -> [foo"bar]
    167 
    168 
    169 ==============================================================================
    170 3. Restore screen contents				*win32-restore*
    171 
    172 When 'restorescreen' is set (which is the default), Vim will restore the
    173 original contents of the console when exiting or when executing external
    174 commands.  If you don't want this, use ":set nors".	'restorescreen'
    175 
    176 ==============================================================================
    177 4. Using the mouse					*win32-mouse*
    178 
    179 The Win32 version of Vim supports using the mouse.  If you have a two-button
    180 mouse, the middle button can be emulated by pressing both left and right
    181 buttons simultaneously - but note that in the Win32 GUI, if you have the right
    182 mouse button pop-up menu enabled (see 'mouse'), you should err on the side of
    183 pressing the left button first.				|mouse-using|
    184 
    185 When the mouse doesn't work, try disabling the "Quick Edit Mode" feature of
    186 the console.
    187 
    188 ==============================================================================
    189 5. Running under Windows 95				*win32-win95*
    190 					*windows95* *windows98* *windowsme*
    191 Windows 95/98/ME support was removed in patch 8.0.0029  If you want to use it
    192 you will need to get a version older than that.
    193 
    194 ==============================================================================
    195 6. Running under Windows 3.1				*win32-win3.1*
    196 
    197 				*win32s* *windows-3.1* *gui-w32s* *win16*
    198 There was a special version of gvim that runs under Windows 3.1 and 3.11.
    199 Support was removed in patch 7.4.1364.
    200 
    201 ==============================================================================
    202 7. Installation package					*win32-installer*
    203 
    204 A simple installer for windows is available at http://www.vim.org/download.php
    205 (stable version) and nightly builds are also available at
    206 https://github.com/vim/vim-win32-installer/releases/
    207 
    208 The nightly builds include 32bit and 64bit builds, have most features enabled
    209 and usually also contain an extra cryptographic signed installer, so Windows
    210 will not complain.
    211 
    212 To use the installer, simply run the exe file.  The following switches are
    213 also supported: >
    214 
    215     gvim_<version>.exe /S           -> silent install without any dialogues
    216     gvim_<version>.exe /D=C:\vim    -> Install into directory c:\vim
    217                                     -> /D must be the last argument
    218     gvim_<version>.exe /S /D=c:\vim -> silent install into c:\vim
    219 <
    220 The default installation directory can alternatively be given by setting the
    221 $VIM environment variable.
    222 
    223 ==============================================================================
    224 8. Win32 mini FAQ					*win32-faq*
    225 
    226 Q. How do I change the font?
    227 A. In the GUI version, you can use the 'guifont' option.  Example: >
    228 	:set guifont=Lucida_Console:h15:cDEFAULT
    229 <  In the console version, you need to set the font of the console itself.
    230    You cannot do this from within Vim.
    231 
    232 Q. How do I type dead keys on Windows NT?
    233 A. Dead keys work on NT 3.51.  Just type them as you would in any other
    234    application.
    235    On NT 4.0, you need to make sure that the default locale (set in the
    236    Keyboard part of the Control Panel) is the same as the currently active
    237    locale.  Otherwise the NT code will get confused and crash!  This is a NT
    238    4.0 problem, not really a Vim problem.
    239 
    240 Q. I'm using Vim to edit a symbolically linked file on a Unix NFS file server.
    241    When I write the file, Vim does not "write through" the symlink.  Instead,
    242    it deletes the symbolic link and creates a new file in its place.  Why?
    243 A. On Unix, Vim is prepared for links (symbolic or hard).  A backup copy of
    244    the original file is made and then the original file is overwritten.  This
    245    assures that all properties of the file remain the same.  On non-Unix
    246    systems, the original file is renamed and a new file is written.  Only the
    247    protection bits are set like the original file.  However, this doesn't work
    248    properly when working on an NFS-mounted file system where links and other
    249    things exist.  The only way to fix this in the current version is not
    250    making a backup file, by ":set nobackup nowritebackup"     'writebackup'
    251 
    252 Q. I'm using Vim to edit a file on a Unix file server through Samba.  When I
    253    write the file, the owner of the file is changed.  Why?
    254 A. When writing a file Vim renames the original file, this is a backup (in
    255    case writing the file fails halfway).  Then the file is written as a new
    256    file.  Samba then gives it the default owner for the file system, which may
    257    differ from the original owner.
    258    To avoid this set the 'backupcopy' option to "yes".  Vim will then make a
    259    copy of the file for the backup, and overwrite the original file.  The
    260    owner isn't changed then.
    261 
    262 Q. How do I get to see the output of ":make" while it's running?
    263 A. Basically what you need is to put a tee program that will copy its input
    264    (the output from make) to both stdout and to the errorfile.  You can find a
    265    copy of tee (and a number of other GNU tools) at
    266    http://gnuwin32.sourceforge.net or http://unxutils.sourceforge.net
    267    Alternatively, try the more recent Cygnus version of the GNU tools at
    268    http://www.cygwin.com
    269    When you do get a copy of tee, you'll need to add >
    270 	:set shellpipe=\|\ tee
    271 <  to your _vimrc.
    272 
    273 Q. I'm storing files on a remote machine that works with VisionFS, and files
    274    disappear!
    275 A. VisionFS can't handle certain dot (.) three letter extension file names.
    276    SCO declares this behavior required for backwards compatibility with 16bit
    277    DOS/Windows environments.  The two commands below demonstrate the behavior:
    278 >
    279 	echo Hello > file.bat~
    280 	dir > file.bat
    281 <
    282    The result is that the "dir" command updates the "file.bat~" file, instead
    283    of creating a new "file.bat" file.  This same behavior is exhibited in Vim
    284    when editing an existing file named "foo.bat" because the default behavior
    285    of Vim is to create a temporary file with a '~' character appended to the
    286    name.  When the file is written, it winds up being deleted.
    287 
    288    Solution: Add this command to your _vimrc file: >
    289 	:set backupext=.temporary
    290 
    291 Q. How do I change the blink rate of the cursor?
    292 A. You can't!  This is a limitation of the NT console.  NT 5.0 is reported to
    293    be able to set the blink rate for all console windows at the same time.
    294 
    295 							*:!start*
    296 Q. How can I asynchronously run an external command or program, or open a
    297    document or URL with its default program?
    298 A. When using :! to run an external command, you can run it with "start".  For
    299    example, to run notepad: >
    300 	:!start notepad
    301 <   To open "image.jpg" with the default image viewer: >
    302         :!start image.jpg
    303 <   To open the folder of the current file in Windows Explorer: >
    304         :!start %:h
    305 <   To open the Vim home page with the default browser: >
    306         :!start http://www.vim.org/
    307 <
    308    Using "start" stops Vim switching to another screen, opening a new console,
    309    or waiting for the program to complete; it indicates that you are running a
    310    program that does not affect the files you are editing.  Programs begun
    311    with :!start do not get passed Vim's open file handles, which means they do
    312    not have to be closed before Vim.
    313    To avoid this special treatment, use ":! start".
    314    There are two optional arguments (see the next Q):
    315        /min  the window will be minimized
    316        /b    no console window will be opened
    317    You can use only one of these flags at a time.  A second one will be
    318    treated as the start of the command.
    319 						*windows-asynchronously*
    320 Q. How do I avoid getting a window for programs that I run asynchronously?
    321 A. You have three possible solutions depending on what you want:
    322    1) You may use the /min flag in order to run program in a minimized state
    323       with no other changes.  It will work equally for console and GUI
    324       applications.
    325    2) You can use the /b flag to run console applications without creating a
    326       console window for them (GUI applications are not affected).  But you
    327       should use this flag only if the application you run doesn't require any
    328       input.  Otherwise it will get an EOF error because its input stream
    329       (stdin) would be redirected to \\.\NUL (stdout and stderr too).
    330    3) Set the '!' flag in the 'guioptions' option |'go-!'|.  This will make Vim
    331       run the "start" command inside Vims terminal window and not open a
    332       console window.
    333 
    334    Example for a console application, run Exuberant ctags: >
    335         :!start /min ctags -R .
    336 <   When it has finished you should see file named "tags" in your current
    337    directory.  You should notice the window title blinking on your taskbar.
    338    This is more noticeable for commands that take longer.
    339    Now delete the "tags" file and run this command: >
    340         :!start /b ctags -R .
    341 <   You should have the same "tags" file, but this time there will be no
    342    blinking on the taskbar.
    343    Example for a GUI application: >
    344         :!start /min notepad
    345         :!start /b notepad
    346 <   The first command runs notepad minimized and the second one runs it
    347    normally.
    348 
    349 						*windows-icon*
    350 Q. I don't like the Vim icon, can I change it?
    351 A. Yes, place your favorite icon in bitmaps/vim.ico in a directory of
    352    'runtimepath'.  For example ~/vimfiles/bitmaps/vim.ico.
    353 
    354 
    355  vim:tw=78:ts=8:noet:ft=help:norl: