Skip to main content
Join the official 2020 Python Developers SurveyStart the survey!

Control Neovim instances using "nvr" commandline tool

Project description



nvr is a tool that helps controlling nvim processes.

It basically does two things:

  1. adds back the --remote family of options (see man vim)
  2. helps controlling the current nvim from within :terminal

To target a certain nvim process, you either use the --servername option or set the environment variable $NVIM_LISTEN_ADDRESS.

Since $NVIM_LISTEN_ADDRESS is implicitely set by each nvim process, you can call nvr from within Neovim (:terminal) without specifying --servername.


$ pip3 install neovim-remote

On most systems this will be good enough.

If you get a “permission denied” error, don’t use sudo to force it! Use this instead:

$ pip3 install --user neovim-remote

..and make sure that ~/.local/bin is in $PATH.


Start a nvim process (which acts as a server) in one shell:

$ NVIM_LISTEN_ADDRESS=/tmp/nvimsocket nvim

And do this in another shell:

$ # Spares us from using --servername all the time:
$ export NVIM_LISTEN_ADDRESS=/tmp/nvimsocket
$ # This is optional, since nvr assumes /tmp/nvimsocket by default.

$ # Open two files:
$ nvr --remote file1 file2

$ # Send keys to the current buffer:
$ nvr --remote-send 'iabc<esc>'
$ # Enter insert mode, insert 'abc', and go back to normal mode again.

$ # Evaluate any VimL expression, e.g. get all listed buffers:
$ nvr --remote-expr "join(sort(map(filter(range(bufnr('$')), 'buflisted(v:val)'), 'bufname(v:val)')), "\""\n"\"")"

See nvr -h for all options.


How to open directories?

:e /tmp opens a directory view via netrw. Netrw works by hooking into certain events, BufEnter in this case (see :au FileExplorer for all of them).

Unfortunately Neovim’s API doesn’t trigger any autocmds on its own, so simply nvr /tmp won’t work. Meanwhile you can work around it like this:

$ nvr /tmp -c 'doautocmd BufEnter'

Reading from stdin?

Yes! E.g. echo "foo\nbar" | nvr -o - and cat file | nvr --remote - work just as you would expect them to work.

Exit code?

If you use a recent enough Neovim, nvr will use the same exit code as the linked nvim.

E.g. nvr --remote-wait <file> and then :cquit in the linked nvim will make nvr return with 1.

Talking to nvr from Neovim?

Imagine nvr --remote-wait file. The buffer that represents “file” in Neovim now has a local variable b:nvr. It’s a list of channels for each connected nvr process.

If we wanted to create a command that disconnects all nvr processes with exit code 1:

command! Cquit
    \  if exists('b:nvr')
    \|   for chanid in b:nvr
    \|     silent! call rpcnotify(chanid, 'Exit', 1)
    \|   endfor
    \| endif


(Click on the GIFs to watch them full-size.)

Using nvr from another shell: Demo 1

Using nvr from within :terminal: Demo 2

Project details

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Files for neovim-remote, version 1.5.0
Filename, size File type Python version Upload date Hashes
Filename, size neovim_remote-1.5.0-py3-none-any.whl (9.7 kB) File type Wheel Python version py3 Upload date Hashes View
Filename, size neovim-remote-1.5.0.tar.gz (7.7 kB) File type Source Python version None Upload date Hashes View

Supported by

Pingdom Pingdom Monitoring Google Google Object Storage and Download Analytics Sentry Sentry Error logging AWS AWS Cloud computing DataDog DataDog Monitoring Fastly Fastly CDN DigiCert DigiCert EV certificate StatusPage StatusPage Status page