Provider
Nvim :help
pages, generated
from source
using the tree-sitter-vimdoc parser.
Providers
Nvim delegates some features to dynamic "providers". This document describes
the providers and how to install them.
E319
Use of a feature requiring a missing provider is an error:
E319: No "foo" provider found. Run ":checkhealth provider"
Run the
:checkhealth command, and review the sections below.
Note: Only the Vim 7.3 legacy interface is supported, not later features such
as
python-bindeval (Vim 7.4); use the Nvim API instead. Python 2 is not
supported.
To use Python plugins, you need the "pynvim" module. Run
:checkhealth to see
if you already have it (some package managers install the module with Nvim
itself).
For Python 3 plugins:
1. Make sure Python 3.4+ is available in your $PATH.
2. Install the module (try "python" if "python3" is missing):
python3 -m pip install --user --upgrade pynvim
The pip
--upgrade
flag ensures that you get the latest version even if
a previous version was already installed.
Note: The old "neovim" module was renamed to "pynvim".
https://github.com/neovim/neovim/wiki/Following-HEAD#20181118
If you run into problems, uninstall _both_ then install "pynvim" again:
python -m pip uninstall neovim pynvim
python -m pip install --user --upgrade pynvim
PYTHON PROVIDER CONFIGURATION
g:python3_host_prog
Command to start Python 3 (executable, not directory). Setting this makes
startup faster. Useful for working with virtualenvs. Must be set before any
check for has("python3").
let g:python3_host_prog = '/path/to/python3'
g:loaded_python3_provider
To disable Python 3 support:
let g:loaded_python3_provider = 0
PYTHON VIRTUALENVS
python-virtualenv
If you plan to use per-project virtualenvs often, you should assign one
virtualenv for Nvim and hard-code the interpreter path via
g:python3_host_prog so that the "pynvim" package is not required
for each virtualenv.
Example using pyenv:
pyenv install 3.4.4
pyenv virtualenv 3.4.4 py3nvim
pyenv activate py3nvim
python3 -m pip install pynvim
pyenv which python # Note the path
The last command reports the interpreter path, add it to your init.vim:
let g:python3_host_prog = '/path/to/py3nvim/bin/python'
See also:
https://github.com/zchee/deoplete-jedi/wiki/Setting-up-Python-for-Neovim
Nvim supports Ruby
remote-plugins and the Vim legacy
ruby-vim interface
(which is itself implemented as a Nvim remote-plugin).
To use Ruby plugins with Nvim, install the latest "neovim" RubyGem:
gem install neovim
Run
:checkhealth to see if your system is up-to-date.
g:ruby_host_prog
Command to start the Ruby host. By default this is "neovim-ruby-host". With
project-local Ruby versions (via tools like RVM or rbenv) setting this can
avoid the need to install the "neovim" gem in every project.
To use an absolute path (e.g. to an rbenv installation):
let g:ruby_host_prog = '~/.rbenv/versions/2.4.1/bin/neovim-ruby-host'
To use the RVM "system" Ruby installation:
let g:ruby_host_prog = 'rvm system do neovim-ruby-host'
Note: Only perl versions from 5.22 onward are supported.
To use perl remote-plugins with Nvim, install the "Neovim::Ext" cpan package:
cpanm -n Neovim::Ext
Run
:checkhealth to see if your system is up-to-date.
g:perl_host_prog
Command to start the Perl executable. Must be set before any
check for has("perl").
let g:perl_host_prog = '/path/to/perl'
To use javascript remote-plugins with Nvim, install the "neovim" npm package:
npm install -g neovim
Run
:checkhealth to see if your system is up-to-date.
NODEJS PROVIDER CONFIGURATION
g:loaded_node_provider
To disable Node.js support:
:let g:loaded_node_provider = 0
g:node_host_prog
Command to start the Node.js host. Setting this makes startup faster.
By default, Nvim searches for "neovim-node-host" using "npm root -g", which
can be slow. To avoid this, set g:node_host_prog to the host path:
let g:node_host_prog = '/usr/local/bin/neovim-node-host'
Nvim has no direct connection to the system clipboard. Instead it depends on
a
provider which transparently uses shell commands to communicate with the
system clipboard or any other clipboard "backend".
To ALWAYS use the clipboard for ALL operations (instead of interacting with
the "+" and/or "*" registers explicitly):
set clipboard+=unnamedplus
See
'clipboard' for details and options.
clipboard-tool
The presence of a working clipboard tool implicitly enables the '+' and "*"
registers. Nvim looks for these clipboard tools, in order of priority:
pbcopy, pbpaste (macOS)
wl-copy, wl-paste (if $WAYLAND_DISPLAY is set)
waycopy, waypaste (if $WAYLAND_DISPLAY is set)
xsel (if $DISPLAY is set)
xclip (if $DISPLAY is set)
termux (via termux-clipboard-set, termux-clipboard-set)
tmux (if $TMUX is set)
g:clipboard
To configure a custom clipboard tool, set g:clipboard to a dictionary.
For example this configuration integrates the tmux clipboard:
let g:clipboard = {
\ 'name': 'myClipboard',
\ 'copy': {
\ '+': ['tmux', 'load-buffer', '-'],
\ '*': ['tmux', 'load-buffer', '-'],
\ },
\ 'paste': {
\ '+': ['tmux', 'save-buffer', '-'],
\ '*': ['tmux', 'save-buffer', '-'],
\ },
\ 'cache_enabled': 1,
\ }
If "cache_enabled" is
TRUE then when a selection is copied Nvim will cache
the selection until the copy command process dies. When pasting, if the copy
process has not died the cached selection is applied.
g:clipboard can also use functions (see
lambda) instead of strings.
For example this configuration uses the g:foo variable as a fake clipboard:
let g:clipboard = {
\ 'name': 'myClipboard',
\ 'copy': {
\ '+': {lines, regtype -> extend(g:, {'foo': [lines, regtype]}) },
\ '*': {lines, regtype -> extend(g:, {'foo': [lines, regtype]}) },
\ },
\ 'paste': {
\ '+': {-> get(g:, 'foo', [])},
\ '*': {-> get(g:, 'foo', [])},
\ },
\ }
The "copy" function stores a list of lines and the register type. The "paste"
function returns the clipboard as a
[lines, regtype]
list, where
lines
is
a list of lines and
regtype
is a register type conforming to
setreg().
clipboard-wsl
For Windows WSL, try this g:clipboard definition:
let g:clipboard = {
\ 'name': 'WslClipboard',
\ 'copy': {
\ '+': 'clip.exe',
\ '*': 'clip.exe',
\ },
\ 'paste': {
\ '+': 'powershell.exe -NoLogo -NoProfile -c [Console]::Out.Write($(Get-Clipboard -Raw).tostring().replace("`r", ""))',
\ '*': 'powershell.exe -NoLogo -NoProfile -c [Console]::Out.Write($(Get-Clipboard -Raw).tostring().replace("`r", ""))',
\ },
\ 'cache_enabled': 0,
\ }
clipboard-osc52
Nvim bundles a clipboard provider that allows copying to the system clipboard
using OSC 52. OSC 52 is an Operating System Command control sequence that
writes the copied text to the terminal emulator. If the terminal emulator
supports OSC 52 then it will write the copied text into the system clipboard.
Nvim will attempt to automatically determine if the host terminal emulator
supports the OSC 52 sequence and enable the OSC 52 clipboard provider if it
does as long as all of the following are true:
Nvim is running in the
TUI
$SSH_TTY is set
If any of the above conditions are not met then the OSC 52 clipboard provider
will not be used by default and Nvim will fall back to discovering a
clipboard-tool through the usual process.
To force Nvim to use the OSC 52 provider you can use the following
g:clipboard definition:
vim.g.clipboard = {
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('*'),
},
}
Note that not all terminal emulators support reading from the system clipboard
(and even for those that do, users should be aware of the security
implications), so using OSC 52 for pasting may not be possible (and not
necessary, because you can
paste instead using your system paste function).
Users may need to configure their terminal emulator to allow reading from the
clipboard.
"Paste" is a separate concept from
clipboard: paste means "dump a bunch of
text to the editor", whereas clipboard provides features like
quote+ to get
and set the OS clipboard directly. For example, middle-click or
CTRL-SHIFT-v
(macOS: CMD-v) in your terminal is "paste", not "clipboard": the terminal
application (Nvim) just gets a stream of text, it does not interact with the
clipboard directly.
Paste inserts text after the cursor. Lines break at <NL>
, <CR>
, and <CR>
<NL>
.
When pasting a huge amount of text, screen-updates are throttled and the
message area shows a "..." pulse.
In cmdline-mode only the first line is pasted, to avoid accidentally executing
many commands. Use the
cmdline-window if you really want to paste multiple
lines to the cmdline.
You can implement a custom paste handler by redefining
vim.paste().
Example:
vim.paste = (function(lines, phase)
vim.api.nvim_put(lines, 'c', true, true)
end)
X11 clipboard providers store text in "selections". Selections are owned by an
application, so when the application gets closed, the selection text is lost.
The contents of selections are held by the originating application (e.g., upon
a copy), and only passed to another application when that other application
requests them (e.g., upon a paste).
There are three documented X11 selections: PRIMARY, SECONDARY, and CLIPBOARD.
CLIPBOARD is typically used in X11 applications for copy/paste operations
(CTRL-c/CTRL-v), while PRIMARY is used for the last selected text, which is
generally inserted with the middle mouse button.
Nvim's X11 clipboard providers only use the PRIMARY and CLIPBOARD selections,
for the "*" and "+" registers, respectively.