Nvim Class

An instance of this class is used by remote plugins.

class pynvim.api.Nvim(session, channel_id, metadata, types, decode=False, err_cb=None)[source]

Class that represents a remote Nvim instance.

This class is main entry point to Nvim remote API, it is a wrapper around Session instances.

The constructor of this class must not be called directly. Instead, the from_session class method should be used to create the first instance from a raw Session instance.

Subsequent instances for the same session can be created by calling the with_decode instance method to change the decoding behavior or SubClass.from_nvim(nvim) where SubClass is a subclass of Nvim, which is useful for having multiple Nvim objects that behave differently without one affecting the other.

When this library is used on python3.4+, asyncio event loop is guaranteed to be used. It is available as the “loop” attribute of this class. Note that asyncio callbacks cannot make blocking requests, which includes accessing state-dependent attributes. They should instead schedule another callback using nvim.async_call, which will not have this restriction.

async_call(fn, *args, **kwargs)[source]

Schedule fn to be called by the event loop soon.

This function is thread-safe, and is the only way code not on the main thread could interact with nvim api objects.

This function can also be called in a synchronous event handler, just before it returns, to defer execution that shouldn’t block neovim.

call(name, *args, **kwargs)[source]

Call a vimscript function.


Run os.chdir, then all appropriate vim stuff.


Close the nvim session and release its resources.

command(string, **kwargs)[source]

Execute a single ex command.


Execute a single ex command and return the output.

err_write(msg, **kwargs)[source]

Print msg as an error message.

The message is buffered (won’t display) until linefeed (“n”).

eval(string, **kwargs)[source]

Evaluate a vimscript expression.

exec_lua(code, *args, **kwargs)[source]

Execute lua code.

Additional parameters are available as inside the lua chunk. Only statements are executed. To evaluate an expression, prefix it with return: return my_function(…)

There is a shorthand syntax to call lua functions with arguments:

nvim.lua.func(1,2) nvim.lua.mymod.myfunction(data, async_=True)

is equivalent to

nvim.exec_lua(“return func(…)”, 1, 2) nvim.exec_lua(“mymod.myfunction(…)”, data, async_=True)

Note that with async_=True there is no return value.

feedkeys(keys, options='', escape_csi=True)[source]

Push keys to Nvim user input buffer.

Options can be a string with the following character flags: - ‘m’: Remap keys. This is default. - ‘n’: Do not remap keys. - ‘t’: Handle keys as if typed; otherwise they are handled as if coming

from a mapping. This matters for undo, opening folds, etc.

Invoke cb for each path in ‘runtimepath’.

Call the given callable for each path in ‘runtimepath’ until either callable returns something but None, the exception is raised or there are no longer paths. If stopped in case callable returned non-None, vim.foreach_rtp function returns the value returned by callable.

classmethod from_nvim(nvim)[source]

Create a new Nvim instance from an existing instance.

classmethod from_session(session)[source]

Create a new Nvim instance for a Session instance.

This method must be called to create the first Nvim instance, since it queries Nvim metadata for type information and sets a SessionHook for creating specialized objects from Nvim remote handles.


Push bytes to Nvim low level input buffer.

Unlike feedkeys(), this uses the lowest level input buffer and the call is not deferred. It returns the number of bytes actually written(which can be less than what was requested if the buffer is full).


Return a list of paths contained in the ‘runtimepath’ option.


Return new src_id for use with Buffer.add_highlight.


Block until a message(request or notification) is available.

If any messages were previously enqueued, return the first in queue. If not, run the event loop until one is received.

out_write(msg, **kwargs)[source]

Print msg as a normal message.

The message is buffered (won’t display) until linefeed (“n”).


Send a quit command to Nvim.

By default, the quit command is ‘qa!’ which will make Nvim quit without saving anything.

replace_termcodes(string, from_part=False, do_lt=True, special=True)[source]

Replace any terminal code strings by byte sequences.

The returned sequences are Nvim’s internal representation of keys, for example:

<esc> -> ‘x1b’ <cr> -> ‘r’ <c-l> -> ‘x0c’ <up> -> ‘x80ku’

The returned sequences can be used as input to feedkeys.

request(name, *args, **kwargs)[source]

Send an API request or notification to nvim.

It is rarely needed to call this function directly, as most API functions have python wrapper functions. The api object can be also be used to call API functions as methods:

vim.api.err_write(‘ERRORn’, async_=True) vim.current.buffer.api.get_mark(‘.’)

is equivalent to

vim.request(‘nvim_err_write’, ‘ERRORn’, async_=True) vim.request(‘nvim_buf_get_mark’, vim.current.buffer, ‘.’)

Normally a blocking request will be sent. If the async_ flag is present and True, a asynchronous notification is sent instead. This will never block, and the return value or error is ignored.

run_loop(request_cb, notification_cb, setup_cb=None, err_cb=None)[source]

Run the event loop to receive requests and notifications from Nvim.

This should not be called from a plugin running in the host, which already runs the loop and dispatches events to plugins.


Stop the event loop being started with run_loop.


Return the number of display cells string occupies.

Tab is counted as one cell.


Subscribe to a Nvim event.

ui_attach(width, height, rgb=None, **kwargs)[source]

Register as a remote UI.

After this method is called, the client will receive redraw notifications.


Unregister as a remote UI.

ui_try_resize(width, height)[source]

Notify nvim that the client window has resized.

If possible, nvim will send a redraw request to resize.


Unsubscribe to a Nvim event.


Initialize a new Nvim instance.