Provider

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 vim.provider"

Run the :checkhealth command, and review the sections below.

Python integration provider-python

Nvim supports Python remote-plugins and the Vim legacy python3 and pythonx interfaces (which are implemented as remote-plugins).

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.9+ 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.

See also python-virtualenv.

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

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-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

Ruby integration provider-ruby

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:loaded_ruby_provider
To disable Ruby support:

let g:loaded_ruby_provider = 0

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'

Perl integration provider-perl

Nvim supports Perl remote-plugins on Unix platforms. Support for polling STDIN on MS-Windows is currently lacking from all known event loop implementations. The Vim legacy perl-vim interface is also supported (which is itself implemented as a Nvim remote-plugin). https://github.com/jacquesg/p5-Neovim-Ext

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:loaded_perl_provider
To disable Perl support:

:let g:loaded_perl_provider = 0

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'

Node.js integration provider-nodejs

Nvim supports Node.js remote-plugins. https://github.com/neovim/node-client/

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.

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'

Clipboard integration provider-clipboard clipboard

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 supports these clipboard tools, in order of priority:

g:clipboard
To configure a custom clipboard tool, set g:clipboard to a string name (from the above clipboard-tool list), or dict (to explicitly specify the shell commands or lambda functions).

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.

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().

Example: set to "osc52" to force OSC52, skipping auto-detection of terminal support:

let g:clipboard = 'osc52'

Example: set to "wayclip" to force waycopy/waypaste:

let g:clipboard = 'wayclip'

Example: set to a dict which 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,
  \ }

Example: set to a dict which uses g:foo 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', [])},
  \   },
  \ }

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, an "Operating System Command" control-sequence that causes the terminal emulator to write to or read from the system clipboard.

When Nvim is running in the TUI, it automatically detects host terminal support for OSC 52. If successful, then Nvim will use OSC 52 for copying and pasting if no other clipboard-tool is found and when 'clipboard' is unset. NOTE: Using a terminal multiplexer (e.g. tmux) may inhibit automatic OSC 52 support detection.

g:termfeatures
To disable the automatic detection, set the "osc52" key of g:termfeatures to false early in your config. Example:

local termfeatures = vim.g.termfeatures or {}
termfeatures.osc52 = false
vim.g.termfeatures = termfeatures

To force Nvim to use the OSC 52 provider you can set g:clipboard:

vim.g.clipboard = 'osc52'

Which is equivalent to:

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: 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 provider-paste paste

"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.

bracketed-paste-mode
Pasting in the TUI depends on the "bracketed paste" terminal capability, which allows terminal applications to distinguish between user input and pasted text. https://cirw.in/blog/bracketed-paste This works automatically if your terminal supports it.

ui-paste
GUIs can paste by calling nvim_paste().

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 selection mechanism clipboard-x11 x11-selection

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).

primary-selection quotestar quoteplus quote+

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.