Skip to content
python client and plugin host for Nvim
Branch: master
Clone or download
bfredl Pynvim 0.3.2
Cleanup after the `pynvim` rename, as well as a few bugfixes and

Changes since 0.3.1:
    - bfb5c26 support `del vim.current.line`
    - 408025b Handle `nvim_error_event` (errors from async requests)
    - 14ab154 Don't crash when subprocesses write to stdout
    - c37b4ed 22e5919 Continue `pynvim` rename
    - 2aa29f9 test with Python 3.7 in Travis.
Latest commit 8db551c Jan 20, 2019
Type Name Latest commit message Commit time
Failed to load latest commit information.
docs hamster wheel: avoid deprecated "encoding" msgpack param Nov 18, 2018
dummy Pynvim 0.3.1 Nov 17, 2018
neovim rename package to pynvim, add transition package Nov 17, 2018
pynvim Pynvim 0.3.2 Jan 20, 2019
scripts scripts/ use print() (#363) Nov 18, 2018
test test: del vim.current.line Dec 13, 2018
.readthedocs.yml Project documentation using Sphinx (#302) Mar 4, 2018
.scrutinizer.yml Travis: test with Python 3.7 Nov 18, 2018
.travis.yml travis: keep qa at the bottom Dec 4, 2018
setup.cfg lint: Enforce "line break before operator" (#365) Nov 18, 2018

Pynvim: Python client to Neovim

Build Status Documentation Status Scrutinizer Code Quality Code Coverage

Pynvim implements support for python plugins in Nvim. It also works as a library for connecting to and scripting Nvim processes through its msgpack-rpc API.


Supports python 2.7, and 3.4 or later.

pip2 install pynvim
pip3 install pynvim

If you only use one of python2 or python3, it is enough to install that version. You can install the package without being root by adding the --user flag.

Anytime you upgrade Neovim, make sure to upgrade pynvim as well:

pip2 install --upgrade pynvim
pip3 install --upgrade pynvim

Alternatively, the master version could be installed by executing the following in the root of this repository:

pip2 install .
pip3 install .

Python Plugin API

Pynvim supports python remote plugins (via the language-agnostic Nvim rplugin interface), as well as Vim plugins (via the :python[3] interface). Thus when pynvim is installed Neovim will report support for the +python[3] Vim feature.

The rplugin interface allows plugins to handle vimL function calls as well as defining commands and autocommands, and such plugins can operate asynchronously without blocking nvim. For details on the new rplugin interface, see the Remote Plugin documentation.

Pynvim defines some extensions over the vim python API:

  • Builtin and plugin vimL functions are available as nvim.funcs
  • API functions are available as vim.api and for objects such as buffer.api
  • Lua functions can be defined using vim.exec_lua and called with vim.lua
  • Support for thread-safety and async requests.

See the Python Plugin API documentation for usage of this new functionality.


Use (and activate) a local virtualenv.

python3 -m venv env36
source env36/bin/activate

If you change the code, you must reinstall for the changes to take effect:

pip install .

Use pytest to run the tests. Invoking with python -m prepends the current directory to sys.path (otherwise pytest might find other versions!):

python -m pytest

For details about testing and troubleshooting, see the development documentation.

Usage through the python REPL

A number of different transports are supported, but the simplest way to get started is with the python REPL. First, start Nvim with a known address (or use the $NVIM_LISTEN_ADDRESS of a running instance):

$ NVIM_LISTEN_ADDRESS=/tmp/nvim nvim

In another terminal, connect a python REPL to Nvim (note that the API is similar to the one exposed by the python-vim bridge):

>>> from pynvim import attach
# Create a python API session attached to unix domain socket created above:
>>> nvim = attach('socket', path='/tmp/nvim')
# Now do some work. 
>>> buffer = nvim.current.buffer # Get the current buffer
>>> buffer[0] = 'replace first line'
>>> buffer[:] = ['replace whole buffer']
>>> nvim.command('vsplit')
>>>[1].width = 10
>>> nvim.vars['global_var'] = [1, 2, 3]
>>> nvim.eval('g:global_var')
[1, 2, 3]

You can embed neovim into your python application instead of binding to a running neovim instance.

>>> from pynvim import attach
>>> nvim = attach('child', argv=["/bin/env", "nvim", "--embed"])

The tests can be consulted for more examples.

You can’t perform that action at this time.