faq.txt (19284B)
1 *faq.txt* Nvim 2 3 NVIM REFERENCE MANUAL 4 5 6 Frequently asked Questions *faq* 7 8 Type |gO| to see the table of contents. 9 10 ============================================================================== 11 General Questions *faq-general* 12 13 14 ------------------------------------------------------------------------------ 15 WHERE SHOULD I PUT MY CONFIG (VIMRC)? 16 17 See |config|; you can copy (or symlink) your existing vimrc. |nvim-from-vim| 18 19 20 ------------------------------------------------------------------------------ 21 HOW STABLE IS THE DEVELOPMENT (PRE-RELEASE) VERSION? 22 23 The unstable (pre-release) 24 https://github.com/neovim/neovim/releases/tag/nightly version of Nvim 25 ("HEAD", i.e. the `master` branch) is used to aggressively stage new features 26 and changes. It's usually stable, but will occasionally break your workflow. 27 We depend on HEAD users to report "blind spots" that were not caught by 28 automated tests. 29 30 Use the stable (release) https://github.com/neovim/neovim/releases/latest 31 version for a more predictable experience. 32 33 34 ------------------------------------------------------------------------------ 35 CAN I USE LUA-BASED VIM PLUGINS (E.G. NEOCOMPLETE)? 36 37 No. Starting with Nvim 0.2 PR #4411 38 https://github.com/neovim/neovim/pull/4411 Lua is built-in, but the legacy 39 Vim `if_lua` interface is not supported. 40 41 42 ------------------------------------------------------------------------------ 43 HOW CAN I USE "TRUE COLOR" IN THE TERMINAL? 44 45 Truecolor (24bit colors) are enabled by default if a supporting terminal is 46 detected. If your terminal is not detected but you are sure it supports 47 truecolor, add this to your |init.vim|: 48 >vim 49 set termguicolors 50 < 51 52 ------------------------------------------------------------------------------ 53 NVIM SHOWS WEIRD SYMBOLS (`�[2 q`) WHEN CHANGING MODES 54 55 This is a bug in your terminal emulator. It happens because Nvim sends 56 cursor-shape termcodes by default, if the terminal appears to be 57 xterm-compatible (`TERM=xterm-256color`). 58 59 To workaround the issue, you can: 60 61 - Use a different terminal emulator 62 - Disable 'guicursor' in your Nvim config: >vim 63 64 :set guicursor= 65 " Workaround some broken plugins which set guicursor indiscriminately. 66 :autocmd OptionSet guicursor noautocmd set guicursor= 67 < 68 See also |$TERM| for recommended values of `$TERM`. 69 70 71 ------------------------------------------------------------------------------ 72 HOW TO CHANGE CURSOR SHAPE IN THE TERMINAL? 73 74 - For Nvim 0.1.7 or older: see the note about `NVIM_TUI_ENABLE_CURSOR_SHAPE` in `man nvim`. 75 - For Nvim 0.2 or newer: cursor styling is controlled by the 'guicursor' option. 76 - To _disable_ cursor-styling, set 'guicursor' to empty: >vim 77 78 :set guicursor= 79 " Workaround some broken plugins which set guicursor indiscriminately. 80 :autocmd OptionSet guicursor noautocmd set guicursor= 81 < 82 - If you want a non-blinking cursor, use `blinkon0`. See 'guicursor'. 83 - 'guicursor' is enabled by default, unless Nvim thinks your terminal doesn't 84 support it. If you're sure that your terminal supports cursor-shaping, set 85 'guicursor' in your |init.vim|, as described in 'guicursor'. 86 - The Vim terminal options |t_SI| and `t_EI` are ignored, like all other |t_xx| options. 87 - Old versions of libvte (gnome-terminal, roxterm, terminator, ...) do not 88 support cursor style control codes. #2537 89 https://github.com/neovim/neovim/issues/2537 90 91 92 ------------------------------------------------------------------------------ 93 HOW TO CHANGE CURSOR COLOR IN THE TERMINAL? 94 95 Cursor styling (shape, color, behavior) is controlled by 'guicursor', even in 96 the terminal. Cursor color (as opposed to shape) only works if 97 'termguicolors' is set. 98 99 'guicursor' gives an example, but here's a more complicated example 100 which sets different colors in insert-mode and normal-mode: 101 >vim 102 :set termguicolors 103 :hi Cursor guifg=green guibg=green 104 :hi Cursor2 guifg=red guibg=red 105 :set guicursor=n-v-c:block-Cursor/lCursor,i-ci-ve:ver25-Cursor2/lCursor2,r-cr:hor20,o:hor50 106 < 107 108 ------------------------------------------------------------------------------ 109 CURSOR STYLE ISN'T RESTORED AFTER EXITING OR SUSPENDING AND RESUMING NVIM 110 111 Nvim uses the "Se" terminfo capability to reset the cursor style on exit. If 112 your terminal's terminfo does not define this capability, use autocommands to 113 manage the cursor style: 114 >vim 115 au VimEnter,VimResume * set guicursor=n-v-c:block,i-ci-ve:ver25,r-cr:hor20,o:hor50 116 \,a:blinkwait700-blinkoff400-blinkon250-Cursor/lCursor 117 \,sm:block-blinkwait175-blinkoff150-blinkon175 118 119 au VimLeave,VimSuspend * set guicursor=a:block-blinkon0 120 121 Alternatively, consider setting the desired cursor shape in your shell (e.g. 122 with PROMPT_COMMAND in bash). 123 124 ------------------------------------------------------------------------------ 125 CURSOR SHAPE DOESN'T CHANGE IN TMUX 126 127 tmux decides that, not Nvim. See |tui-cursor-shape| for a fix. 128 129 See #3165 https://github.com/neovim/neovim/pull/3165 for discussion. 130 131 132 ------------------------------------------------------------------------------ 133 CURSOR FLICKER IN TMUX? 134 135 If cursor `_` appears and disappears very quickly when opening nvim without a 136 document under tmux, and you set |ctermbg| in `EndOfBuffer` and `Normal`, try 137 setting these to `NONE`: 138 >vim 139 hi EndOfBuffer ctermbg=NONE ctermfg=200 cterm=NONE 140 hi Normal ctermbg=NONE ctermfg=200 cterm=NONE 141 < 142 143 ------------------------------------------------------------------------------ 144 WHAT HAPPENED TO --remote AND FRIENDS? 145 146 |--remote| is partly supported. |clientserver| 147 148 If you require flags from Vim that are missing in Nvim, you can use 149 https://github.com/mhinz/neovim-remote instead. 150 151 ============================================================================== 152 Runtime issues *faq-runtime* 153 154 155 ------------------------------------------------------------------------------ 156 COPYING TO X11 PRIMARY SELECTION WITH THE MOUSE DOESN'T WORK 157 158 `clipboard=autoselect` is not implemented yet 159 https://github.com/neovim/neovim/issues/2325. You may find this workaround to 160 be useful: 161 >vim 162 vnoremap <LeftRelease> "*ygv 163 vnoremap <2-LeftRelease> "*ygv 164 < 165 166 ------------------------------------------------------------------------------ 167 MY CTRL-H MAPPING DOESN'T WORK 168 169 This was fixed in Nvim 0.2. If you are running Nvim 0.1.7 or older, 170 adjust your terminal's "kbs" (key_backspace) terminfo entry: 171 >vim 172 infocmp $TERM | sed 's/kbs=^[hH]/kbs=\\177/' > $TERM.ti 173 tic $TERM.ti 174 < 175 (Feel free to delete the temporary `*.ti` file created after running the above 176 commands). 177 178 179 ------------------------------------------------------------------------------ 180 <HOME> OR SOME OTHER "SPECIAL" KEY DOESN'T WORK 181 182 Make sure |$TERM| is set correctly. 183 184 - For screen or tmux, `$TERM` should be `screen-256color` (not `xterm-256color`!) 185 - In other cases if "256" does not appear in the string it's probably wrong. 186 Try `TERM=xterm-256color`. 187 188 189 ------------------------------------------------------------------------------ 190 :! AND SYSTEM() DO WEIRD THINGS WITH INTERACTIVE PROCESSES 191 192 Interactive commands are supported by |:terminal| in Nvim. But |:!| and 193 |system()| do not support interactive commands, primarily because Nvim UIs use 194 stdio for msgpack communication, but also for performance, reliability, and 195 consistency across platforms (see 196 https://vimhelp.org/gui_x11.txt.html#gui-pty). 197 198 See also #1496 https://github.com/neovim/neovim/issues/1496 and #8217 199 https://github.com/neovim/neovim/issues/8217#issuecomment-402152307. 200 201 202 ------------------------------------------------------------------------------ 203 PYTHON SUPPORT ISN'T WORKING 204 205 Run |:checkhealth| in Nvim for automatic diagnosis. 206 207 Other hints: 208 209 - Read |provider-python| to learn how to install `pynvim`. 210 - Be sure you have the latest version of the `pynvim` Python module: >bash 211 212 uv tool install --upgrade pynvim 213 < 214 See |provider-python| for other installation options. 215 - If you're manually creating a Python virtual environment for the `pynvim` module 216 https://pypi.org/project/pynvim/, you must set `g:python3_host_prog` to 217 the virtualenv's interpreter path. 218 - Try with `nvim -u NORC` to make sure your config (|init.vim|) isn't causing a 219 problem. If you get `E117: Unknown function`, that means there's a runtime 220 issue: |faq-runtime|. 221 - The python `neovim` module was renamed to `pynvim` (long ago). 222 223 224 ------------------------------------------------------------------------------ 225 :CHECKHEALTH REPORTS E5009: INVALID $VIMRUNTIME 226 227 This means |$VIMRUNTIME| or 'runtimepath' is broken. 228 229 - |$VIMRUNTIME| must point to Nvim's runtime files, not Vim's. 230 - The |$VIMRUNTIME| directory contents should be readable by the current user. 231 - Verify that `:echo &runtimepath` contains the $VIMRUNTIME path. 232 233 ------------------------------------------------------------------------------ 234 NEOVIM CAN'T FIND ITS RUNTIME 235 236 This is the case if `:help nvim` shows `E149: Sorry, no help for nvim`. 237 238 Make sure that |$VIM| and |$VIMRUNTIME| point to Nvim's (as opposed to 239 Vim's) runtime by checking `:echo $VIM` and `:echo $VIMRUNTIME`. This should 240 give something like `/usr/share/nvim` resp. `/usr/share/nvim/runtime`. 241 242 Also make sure that you don't accidentally overwrite your runtimepath 243 (`:set runtimepath?`), which includes the above |$VIMRUNTIME| by default (see 244 'runtimepath'). 245 246 247 ------------------------------------------------------------------------------ 248 NEOVIM IS SLOW 249 250 251 Use a fast terminal emulator: 252 253 - kitty https://github.com/kovidgoyal/kitty 254 - alacritty https://github.com/jwilm/alacritty 255 256 257 Use an optimized build: 258 259 `:version` should report one of these "build types": 260 > 261 Build type: RelWithDebInfo 262 Build type: MinSizeRel 263 Build type: Release 264 < 265 If it reports `Build type: Debug` and you're building Nvim from source, see 266 https://github.com/neovim/neovim/blob/master/BUILD.md. 267 268 269 ------------------------------------------------------------------------------ 270 COLORS AREN'T DISPLAYED CORRECTLY 271 272 Ensure that |$TERM| is set correctly. 273 274 From a shell, run `TERM=xterm-256color nvim`. If colors are displayed 275 correctly, then export that value of `TERM` in your user profile (usually 276 `~/.profile`): 277 >bash 278 export TERM=xterm-256color 279 < 280 If you're using `tmux`, instead add this to your `tmux.conf`: 281 >bash 282 set -g default-terminal "tmux-256color" 283 < 284 285 For GNU `screen`, configure your `.screenrc` 286 <https://wiki.archlinux.org/index.php/GNU_Screen#Use_256_colors>: 287 > 288 term screen-256color 289 < 290 291 NOTE: Nvim ignores `t_Co` and other |t_xx| terminal codes. 292 293 294 ------------------------------------------------------------------------------ 295 NEOVIM CAN'T READ UTF-8 CHARACTERS 296 297 Run the following from the command line: 298 >bash 299 locale | grep -E '(LANG|LC_CTYPE|LC_ALL)=(.*\.)?(UTF|utf)-?8' 300 < 301 If there's no results, you might not be using a UTF-8 locale. See these issues: 302 - https://github.com/neovim/neovim/issues/1601 303 - https://github.com/neovim/neovim/issues/1858 304 - https://github.com/neovim/neovim/issues/2386 305 306 307 ------------------------------------------------------------------------------ 308 ESC IN TMUX OR GNU SCREEN IS DELAYED 309 310 This is a common problem 311 https://www.google.com/?q=tmux%20vim%20escape%20delay in `tmux` / `screen` 312 (see also https://github.com/tmux/tmux/issues/131#issuecomment-145853211). The 313 corresponding timeout needs to be tweaked to a low value (10-20ms). 314 315 `.tmux.conf`: 316 > 317 set -g escape-time 10 318 # Or for tmux >= 2.6 319 set -sg escape-time 10 320 < 321 `.screenrc`: 322 > 323 maptimeout 10 324 < 325 326 "WHY DOESN'T THIS HAPPEN IN VIM?" 327 328 It does happen (try `vim -N -u NONE`), but if you hit a key quickly after 329 ESC then Vim interprets the ESC as ESC instead of ALT (META). You won't 330 notice the delay unless you closely observe the cursor. The tradeoff is that 331 Vim won't understand ALT (META) key-chords, so for example `nnoremap <M-a>` 332 won't work. ALT (META) key-chords always work in Nvim. 333 See also `:help xterm-cursor-keys` in Vim. 334 335 Nvim 0.3 mimics the Vim behavior while still fully supporting ALT mappings. See 336 |i_ALT|. 337 338 339 ------------------------------------------------------------------------------ 340 ESC IN GNU SCREEN IS LOST WHEN MOUSE MODE IS ENABLED 341 342 This happens because of a bug in screen https://savannah.gnu.org/bugs/?60196 : 343 in mouse mode, screen assumes that `ESC` is part of a mouse sequence and will 344 wait an unlimited time for the rest of the sequence, regardless of 345 `maptimeout`. Until it's fixed in screen, there's no known workaround for 346 this other than double-pressing escape, which causes a single escape to be 347 passed through to Nvim. 348 349 350 ------------------------------------------------------------------------------ 351 CALLING INPUTLIST(), ECHOMSG, ... IN FILETYPE PLUGINS AND AUTOCMD DOES NOT WORK 352 353 - https://github.com/neovim/neovim/issues/10008 354 - https://github.com/neovim/neovim/issues/10116 355 - https://github.com/neovim/neovim/issues/12288 356 - https://github.com/vim/vim/issues/4379 357 358 This is because Nvim sets `shortmess+=F` by default. Vim behaves the same way 359 with `set shortmes+=F`. There are plans to improve this, but meanwhile as a 360 workaround, use `set shortmess-=F` or use `unsilent` as follows. 361 >vim 362 unsilent let var = inputlist(['1. item1', '2. item2']) 363 autocmd BufNewFile * unsilent echomsg 'The autocmd has been fired.' 364 < 365 366 ------------------------------------------------------------------------------ 367 G:CLIPBOARD SETTINGS ARE NOT USED. 368 369 If the clipboard provider is already loaded, you will need to reload it after 370 configuration. Use the following configuration. 371 >vim 372 let g:clipboard = { 'name' : ... } 373 if exists('g:loaded_clipboard_provider') 374 unlet g:loaded_clipboard_provider 375 runtime autoload/provider/clipboard.vim 376 endif 377 < 378 379 Or, if you want automatic reloading when assigning to |g:clipboard|, set 380 |init.vim| as follows. 381 >vim 382 function! s:clipboard_changed(...) abort 383 if exists('g:loaded_clipboard_provider') 384 unlet g:loaded_clipboard_provider 385 endif 386 runtime autoload/provider/clipboard.vim 387 endfunction 388 389 if !exists('s:loaded") 390 call dictwatcheradd(g:, 'clipboard', function('s:clipboard_changed')) 391 endif 392 let s:loaded = v:true 393 < 394 395 ============================================================================== 396 Build issues *faq-build* 397 398 399 ------------------------------------------------------------------------------ 400 GENERAL BUILD ISSUES 401 402 Run `make distclean && make` to rule out a stale build environment causing the 403 failure. 404 405 406 ------------------------------------------------------------------------------ 407 SETTINGS IN LOCAL.MK DON'T TAKE EFFECT 408 409 CMake caches build settings, so you might need to run `rm -r build && make` 410 after modifying `local.mk`. 411 412 413 ------------------------------------------------------------------------------ 414 CMAKE ERRORS 415 416 `configure_file Problem configuring file` 417 418 This is probably a permissions issue, which can happen if you run `make` as the 419 root user, then later run an unprivileged `make`. To fix this, run 420 `rm -rf build` and try again. 421 422 423 ------------------------------------------------------------------------------ 424 GENERATING HELPTAGS FAILED 425 426 If re-installation fails with "Generating helptags failed", try removing the 427 previously installed runtime directory (if `CMAKE_INSTALL_PREFIX` is not set 428 during building, the default is `/usr/local/share/nvim`): 429 >bash 430 rm -r /usr/local/share/nvim 431 < 432 433 ============================================================================== 434 Design *faq-design* 435 436 437 ------------------------------------------------------------------------------ 438 WHY NOT USE JSON FOR RPC? 439 440 - JSON cannot easily/efficiently handle binary data 441 - JSON specification is ambiguous: https://seriot.ch/parsing_json.php 442 443 444 ------------------------------------------------------------------------------ 445 WHY EMBED LUA INSTEAD OF X? 446 447 - Lua is a very small language, ideal for embedding. The biggest advantage of 448 Python/Ruby/etc is their huge collection of libraries, but that isn't 449 relevant for Nvim, where Nvim is the "batteries included" library: 450 introducing another stdlib would be redundant. 451 - Lua 5.1 is a complete language: the syntax is frozen. This is great for 452 backwards compatibility. 453 - Nvim also uses Lua internally as an alternative to C. Extra performance is 454 useful there, as opposed to a slow language like Python or Vim9script. 455 - LuaJIT is one of the fastest runtimes on the planet, 10x faster than Python 456 and "Vim9script" https://vimhelp.org/vim9.txt.html , 100x faster than 457 Vimscript. 458 - Python/JS cost more than Lua in terms of size and portability, and there are 459 already numerous Python/JS-based editors. So Python/JS would make Nvim 460 bigger and less portable, in exchange for a non-differentiating feature. 461 462 See also: 463 464 - Why Lua https://web.archive.org/web/20150219224654/https://blog.datamules.com/blog/2012/01/30/why-lua/ 465 - The Design of Lua https://cacm.acm.org/research/a-look-at-the-design-of-lua/ 466 - Scripting architecture considerations http://oldblog.antirez.com/post/redis-and-scripting.html 467 - LuaJIT performance https://julialang.org/benchmarks/ 468 - Discussion of JavaScript vs Lua https://github.com/vim/vim/pull/5198#issuecomment-554693754 469 - Discussion Python embedding https://lobste.rs/s/pnuak4/mercurial_s_journey_reflections_on#c_zshdwy 470 471 472 ------------------------------------------------------------------------------ 473 WHY LUA 5.1 INSTEAD OF LUA 5.3+? 474 475 Lua 5.1 is a different language than 5.3. The Lua org makes breaking changes 476 with every new version, so even if we switched (not upgraded, but switched) to 477 5.3 we gain nothing when they create the next new language in 5.4, 5.5, etc. 478 And we would lose LuaJIT, which is far more valuable than Lua 5.3+. 479 480 Lua 5.1 is a complete language. To "upgrade" it, add libraries, not syntax. 481 Nvim itself already is a pretty good "stdlib" for Lua, and we will continue to 482 grow and enhance it. Changing the rules of Lua gains nothing in this context. 483 484 485 ------------------------------------------------------------------------------ 486 WILL NEOVIM TRANSLATE VIMSCRIPT TO LUA, INSTEAD OF EXECUTING VIMSCRIPT DIRECTLY? 487 488 We have no plans for transpiling Vimscript. It was explored in https://github.com/tjdevries/vim9jit 489 490 491 ------------------------------------------------------------------------------ 492 ARE PLUGIN AUTHORS ENCOURAGED TO PORT THEIR PLUGINS FROM VIMSCRIPT TO LUA? DO YOU PLAN ON SUPPORTING VIMSCRIPT INDEFINITELY? 493 494 We don't anticipate any reason to deprecate Vimscript, which is a valuable DSL 495 https://en.wikipedia.org/wiki/Domain-specific_language for text-editing tasks. 496 Maintaining Vimscript compatibility is less costly than a mass migration of 497 existing Vim plugins. 498 499 Porting from Vimscript to Lua just for the heck of it gains nothing. Nvim is 500 emphatically a fork of Vim in order to leverage the work already spent on 501 thousands of Vim plugins, while enabling new types of plugins and 502 integrations. 503 504 That being said, reimplementing legacy plugins in Lua in order to make use of 505 Nvim API and to integrate with Nvim-specific features such as treesitter can 506 be worthwhile. 507 508 vim:tw=78:ts=8:noet:ft=help:norl: