Neovim installation on WSL2 Debian Sid under Windows 11
Table of Contents
- 1. Philosophy
- 2. Installation
- 3. Post-installation tasks
- 4. Tips
- 5. Troubleshooting
- 6. Future direction
- 6.1. DONE init.vim vs. init.lua
- 6.2. NEXT Go through the old vimrc and migrate config to init.lua
- 6.3. NEXT Config: Try relative vs. absolute line numbers
- 6.4. NEXT Config: Setup persistent undo
- 6.5. NEXT Plugins to experiment
- 6.5.1. DONE nvim-orgmode/orgmode
- 6.5.2. WAIT Telescope-orgmode.nvim
- 6.5.3. NEXT Org-roam.nvim
- 6.5.4. DONE org-list.nvim
- 6.5.5. NEXT RLDX.nvim
- 6.5.6. NEXT csvview.nvim
- 6.5.7. NEXT Harper.nvim
- 6.5.8. NEXT Vale
- 6.5.9. NEXT OVIWrite
- 6.5.10. NEXT fzf-lua
- 6.5.11. NEXT Plugins for writers
- 6.5.12. NEXT record-key.nvim
- 6.5.13. NEXT Plugin and init.lua configurations by others
- 6.6. DONE Try Neovide
1. Philosophy
I've been using Vim since ~2008, but Neovim has meanwhile gathered a very vibrant plugin community for writing, note taking and task management, which is my main Vim use case. These are my notes how to set up Neovim to support that.
2. Installation
Neovim is in Debian but its latest stable lags several major versions behind the upstream stable, so installing with bob.
Install dependencies for bob:
$ sudo aptitude install rustup
$ cd ~/sources
$ wget https://github.com/MordechaiHadad/bob/releases/download/v2.8.3/bob-linux-x86_64.zip
$ unzip bob-linux-x86_64.zip
$ cd bob-linux-x86_64/
$ chmod +x bob
$ ./bob use stable
Nvim is now installed. Check the release installed:
$ ./bob list ┌────────────────────┬─────────────┐ │ Version │ Status │ ├────────────────────┼─────────────┤ │ v0.9.5 │ Used │ └────────────────────┴─────────────┘
And what that release version consists of:
$ nvim -V1 -v
NVIM v0.9.5-dev-2947+ge1ca7a7bf Build type: RelWithDebInfo LuaJIT 2.1.1710088188 Compilation: /usr/bin/gcc-10 -O2 -g -Og -g -flto=auto -fno-fat-lto-objects -Wall -Wextra -pedantic -Wno-unused-parameter -Wstrict-prototypes -std=gnu99 -Wshadow -Wconversion -Wvla -Wdouble-promotion -Wmissing-noreturn -Wmissing-format-attribute -Wmissing-prototypes -fsigned-char -fstack-protector-strong -Wno-conversion -fno-common -Wno-unused-result -Wimplicit-fallthrough -fdiagnostics-color=always -DUNIT_TESTING -DHAVE_UNIBILIUM -D_GNU_SOURCE -DINCLUDE_GENERATED_DECLARATIONS -I/home/runner/work/neovim/neovim/.deps/usr/include/luajit-2.1 -I/home/runner/work/neovim/neovim/.deps/usr/include -I/home/runner/work/neovim/neovim/build/src/nvim/auto -I/home/runner/work/neovim/neovim/build/include -I/home/runner/work/neovim/neovim/build/cmake.config -I/home/runner/work/neovim/neovim/src -I/usr/include system vimrc file: "$VIM/sysinit.vim" fall-back for $VIM: "/usr/local/share/nvim"
Run :checkhealth in nvim for more info.
:checkhealth will show warnings, but unless a certain config requires them as dependencies, warnings can be ignored.
Then keep your installation up-to-date:
$ ./bob update |nightly|stable|--all|
3. Post-installation tasks
3.1. DONE Symlink nvim
So that sudo nvim works with bob-installed nvim.
Otherwise $ sudo nvim gives:
sudo: nvim: command not found
$ sudo ln -s /home/pyyhttu/.local/share/bob/nvim-bin/nvim /usr/bin/nvim
3.2. DONE Install a sane config
Here's one to start with:
$ git clone https://github.com/meuter/nvim ~/.config/nvim
After this you have relatively understandable config under $XDG_CONFIG_HOME/nvim/lua you can start tweak further. I've modified it mostly to disable plugins I don't need, and ones I need under plugins/:
~/.config/nvim/lua$ tree
.
├── disabled
│ ├── aosp-vim-syntax.lua
│ ├── bufdelete.lua
│ ├── clangd_extensions.lua
│ ├── cmake-tools.lua
│ ├── crates.lua
│ ├── dap-ui.lua
│ ├── dap-virtual-text.lua
│ ├── diffview.lua
│ ├── dressing.lua
│ ├── gitsigns.lua
│ ├── indent-blankline.lua
│ ├── inlay-hints.lua
│ ├── lsp-config.lua
│ ├── lsp-format.lua
│ ├── lsp-zero.lua
│ ├── mason-lspconfig.lua
│ ├── mason.lua
│ ├── mason-nvim-dap.lua
│ ├── mason-tool-installer.lua
│ ├── neodev.lua
│ ├── nibbler.lua
│ ├── rust-tools.lua
│ ├── schemastore.lua
│ ├── toggleterm.lua
│ ├── trouble.lua
│ └── venv-selector.lua
├── plugins
│ ├── catppuccin.lua
│ ├── cmp.lua
│ ├── colorizer.lua
│ ├── lastplace.lua
│ ├── lualine.lua
│ ├── orgmode.lua
│ └── telescope.lua
Here's my ~/.config/nvim/init.lua.
First install folke/lazy.nvim as your plugin manager.
Then get the plugins and place them at ~/.config/nvim/lua/plugins/
3.3. DONE Install manual
In order to do $ man nvim:
As neovim binary was installed with bob, the manual isn't copied, so remember to copy the manual to its place:
$ sudo cp ~/.local/share/bob/v0.10.2/share/man/man1/nvim.1 /usr/local/share/man/man1/
3.4. DONE Install clipboard support
So that copying / pasting into / to nvim works under WSL2 works. There are two ways.
Install first xclip so that in :checkhealth clipboard support is satisfied (OK).
3.4.1. win32yank
Easiest way (tested) to do this is with Winget and win32yank.
Launch cmd.exe and issue:
winget install win32yank
Then restart Expolorer/computer for win -> win32yank is registered as an executable.
After this also mouse right click menu with its copy/paste works, as will "*y-yanking in visual selection.
See this reddit thread for more info.
3.4.2. clipboard-osc52
: Copy to/from WSL neovim also works after added to by init.lua:
vim.g.cliboard = {
name = 'OSC 52',
copy = {
['+'] = require('vim.ui.clipboard.osc52').copy('+'),
['*'] = require('vim.ui.clipboard.osc52').copy('*'),
},
paste = {
['+'] = require('vim.ui.clipboard.osc52').paste('+'),
['*'] = require('vim.ui.clipboard.osc52').paste('*'),
},
}p
Note: This will make copy paste operations dreadfully slow, even with workaround, don't implement.
3.5. DONE Install LuaRocks support for Lazy.nvim
Not strictly needed, but if I have plugins that need it.
4. Tips
Getting started with Neovim: :h vimtutor, vim-adventures.com, :h usr_toc.txt.
A good cheatsheet for keys.
Ctrl-c exits the insert mode, easier than pressing esc.
4.1. Command-line usage
As mentioned here. Invoked with q: and by pressing Ctrl-f
4.2. Motions for editing
ca and ci are game-changing. E.g. ca[ (“change around [”) or ci( (“change inside (”). They even work when you’re currently inside or outside the bracket/parenthesis/quote/whatever on the same line.
5. Troubleshooting
Basically, it's always either your config ~/.config/nvim/init.lua or plugins ~/.config/nvim/plugins/ causing problems. Problems can be various. Usually it's
- your keymaps not working.
First run nvim without config:
nvim -u NONE
The plugins are still loaded. If the issue persist, then it is some of your plugins. Disable by bisecting plugins until you find the plugin overriding the keymap.
If you have whichkey.nvim installed, you can also do in nvim:
:checkhealth which-key and/or if q for example does not work (recording does not work) then you can do :lua print(vim.inspect(vim.api.nvim_get_keymap('q'))) and inspect output and :messages.
6. Future direction
6.1. DONE init.vim vs. init.lua
Both config files are not supported at the same time, but I can "nest" init.vim config into init.lua, so write config to init.lua with that option in mind.
Here's a helpful lua-guide to get started. There's also kickstart.nvim which goes through the config. Here's vhyrro's video on understanding Neovim.
6.2. NEXT Go through the old vimrc and migrate config to init.lua
Pay attention to differences between vim and nvim when going through .vimrc. You can see differences by doing :h vim_diff-txt.
6.3. NEXT Config: Try relative vs. absolute line numbers
Whether in insert mode vs. normal mode.
6.4. NEXT Config: Setup persistent undo
6.5. NEXT Plugins to experiment
- State "NEXT" from ""
6.5.1. DONE nvim-orgmode/orgmode
Syntax highlighting doesn't work until you have org grammar installed. Install with:
:lua require('orgmode.config'):reinstall_grammar()
After install run :checkhealth orgmode to check everything is working:
6.5.2. WAIT Telescope-orgmode.nvim
6.5.3. NEXT Org-roam.nvim
6.5.4. DONE org-list.nvim
6.5.5. NEXT RLDX.nvim
6.5.6. NEXT csvview.nvim
6.5.7. NEXT Harper.nvim
6.5.8. NEXT Vale
For better writing.
6.5.9. NEXT OVIWrite
As this is a whole writing environment, install this on separate bob version.
6.5.10. NEXT fzf-lua
Consider using fzf-lua instead of Telescope.
6.5.11. NEXT Plugins for writers
6.5.12. NEXT record-key.nvim
6.5.13. NEXT Plugin and init.lua configurations by others
In case you want to search by plugins, or configurations, what others have set up their neovim, head to https://dotfyle.com/ Also https://neovimcraft.com/?search=tag%3Anote-taking and https://github.com/rockerBOO/awesome-neovim?tab=readme-ov-file#note-taking have list of plugins to inspect.
6.6. DONE Try Neovide
Note: Run version 0.12.2 until https://github.com/neovide/neovide/issues/2689 is fixed. Otherwise UNC-paths are not working correctly. Evident e.g. by doing $ neovide.exe --wsl ~.bashrc and file is opened blank.
Install 0.12.2 neovide.msi from here: https://github.com/neovide/neovide/releases
Then run in wsl $ neovide.exe --wsl .bashrc to see it works.
In neovide doing :!export sees my bob in $PATH.
: Neovide is not yet production ready. At least the following issues below needs to be DONE:
6.6.1. ONGO setup clipboard support
Mouse right click does work.
: What works from version onwards:
[X]On windows host select text, ctrl-c then inside wsl nvide guest in insert mode: right click and paste works.[X]Inside nvide guest in WSL in insert mode select text with mouse and press y then right click and paste works. Also pastes to Windows host.- [] Inserting link after \oli does not yet work.
6.6.2. NEXT setup link support for mouse
Ctrl + mouse click does not follow links. Test link: https://pyyhttu.kapsi.fi/debian/neovim Concealed link. : Supported but requires configuration.
6.6.3. NEXT setup config.toml
For smaller font sizes etc. See what is supported with 0.12.2 config.
Tried with config.toml from https://github.com/linkarzu/dotfiles-latest/blob/main/neovide/config.toml placed at c:\Users\TPyyhtia\AppData\Roaming\neovide\ with wsl = true but this configuration file was never read by neovide. https://www.reddit.com/r/neovim/comments/1anku9o/neovide_app_from_brew_and_nvim_from_bob_in_macos
https://github.com/neovide/neovide/issues/2193#issuecomment-1866729923
6.6.4. NEXT Evaluate if neovide is usable
Because I need to revert in /etc/wsl.conf:
[interop] appendWindowsPath = false
Otherwise $ nvide in wsl won't work.