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: