Pynvim

Common errors

• E319: No "python3" provider found. Run ":checkhealth vim.provider" for details.

  cause Neovim cannot find a Python 3 interpreter with `pynvim` installed, or `g:python3_host_prog` is incorrectly configured or not set.
  fix 1. Ensure `pynvim` is installed for the Python interpreter Neovim uses (check `:py3 print(sys.executable)` and `:py3 import pynvim`). 2. If using a virtual environment, tell Neovim its path by setting `vim.g.python3_host_prog` in your Neovim config (e.g., `init.lua` or `init.vim`): `let g:python3_host_prog = '/path/to/your/venv/bin/python'` (Vimscript) `vim.g.python3_host_prog = '/path/to/your/venv/bin/python'` (Lua) 3. Run `:checkhealth` in Neovim to diagnose further.

• EOFError: Read beyond end of file

  cause The connection to the Neovim instance was unexpectedly closed or interrupted, often because the Neovim process itself crashed, was killed, or backgrounded in a way that severed the communication pipe/socket.
  fix This often indicates an issue within Neovim or a plugin. 0.6.0 improves handling, but the root cause might be external. Check Neovim's logs (if enabled, e.g., `NVIM_PYTHON_LOG_FILE=logfile nvim`), review your Neovim configuration and plugins for instability, and ensure the Neovim process remains active during `pynvim` interaction. If connecting via `socket`, verify the socket file `/tmp/nvim.sock` exists and Neovim is listening.

• RuntimeError: asyncio.run() cannot be called from a running event loop

  cause Attempting to call `asyncio.run()` from within an already active asyncio event loop. This commonly occurs when `pynvim` is hosting a plugin, which already operates within an asyncio event loop.
  fix Instead of `asyncio.run()`, use `await` directly for awaitable objects if you are within an `async` function managed by the event loop. If you need to run a task concurrently without blocking, schedule it using `asyncio.create_task()` or `nvim.async_call()`.

Warnings

• breaking Pynvim 0.5.0 raised the minimum supported Python version to 3.7. While 0.6.0 still supports 3.7, it is recommended to use Python 3.9+ for optimal compatibility, especially when using modern installation tools like `uv` or `pipx`.
  Fix: Upgrade your Python environment to 3.7 or newer. For best results with `pynvim >=0.6.0`, use Python 3.9+.
• breaking The `asyncio.get_child_watcher()` function was removed in Python 3.14. Older versions of pynvim (prior to 0.6.0) that relied on this function will cause `AttributeError` or similar failures when run with Python 3.14.
  Fix: Upgrade pynvim to version 0.6.0 or higher: `pip install --upgrade pynvim`. If still encountering issues, ensure your Python installation is compatible.
• deprecated The Python package was renamed from `neovim` to `pynvim` in version 0.3.1. While `import neovim` remains an alias for backward compatibility, new projects and updated codebases should use `import pynvim` to avoid confusion and ensure future compatibility.
  Fix: Update all import statements from `import neovim` to `import pynvim`. When upgrading, it's safest to `pip uninstall neovim` then `pip install pynvim`.
• gotcha When accessing Vimscript dictionaries (e.g., `nvim.vars['my_dict']`) from Python, pynvim returns a *copy* of the dictionary, not a live reference. Modifying fields directly on the Python object will not persist changes back to Neovim.
  Fix: To update a Vimscript dictionary, you must re-assign the entire dictionary back to Neovim. For example: ```python my_dict = nvim.vars['my_dict'] my_dict['field1'] = 'new_value' nvim.vars['my_dict'] = my_dict # Re-assign the modified dictionary ```
• gotcha In remote plugins, synchronous API calls (`sync=True` in decorators) made from within asynchronous handlers can cause Neovim to hang or deadlock, as Neovim waits for the handler to complete while the handler is waiting for Neovim.
  Fix: Avoid making synchronous Neovim API calls from within `async` (default `sync=False`) plugin handlers. If a return value is required, the handler must be explicitly marked `sync=True`. For non-blocking operations within async handlers, use `async_=True` for Neovim requests or schedule new callbacks with `nvim.async_call`.

Install

• pip install pynvim Install with pip
• uv tool install --upgrade pynvim Recommended with uv
• pipx install pynvim Recommended with pipx

Imports

• attach

  from pynvim import attach

• neovim (old package name)
  wrong:

  import neovim

  correct:

  from pynvim import attach

  The package was renamed from `neovim` to `pynvim` in version 0.3.1. While `import neovim` is still aliased for compatibility, `import pynvim` is the modern and recommended approach.

Quickstart

This quickstart demonstrates how to connect to a running Neovim instance using a Unix domain socket and interact with it. It executes a command, reads from the current buffer, and sets a global Neovim variable. Ensure Neovim is started with `nvim --listen /tmp/nvim.sock` (or similar for Windows/TCP) for the client to connect.

# Start Neovim in a terminal with: nvim --listen /tmp/nvim.sock

import os
from pynvim import attach

# Connect to a running Neovim instance via socket
# Ensure Neovim is running with `--listen /tmp/nvim.sock`
# For local testing, you might use os.environ.get('NVIM_LISTEN_ADDRESS')
try:
    nvim = attach('socket', path=os.environ.get('NVIM_LISTEN_ADDRESS', '/tmp/nvim.sock'))
    
    # Execute a Neovim command
    nvim.command('echo "Hello from pynvim!"')
    
    # Get and print the current buffer content
    current_buffer = nvim.current.buffer
    print(f"First line of current buffer: {current_buffer[0]}")
    
    # Set a Neovim variable
    nvim.vars['pynvim_test_var'] = 'Python was here'
    print(f"Neovim variable 'pynvim_test_var': {nvim.eval('g:pynvim_test_var')}")

except Exception as e:
    print(f"Could not connect to Neovim or encountered an error: {e}")
    print("Make sure Neovim is running with '--listen /tmp/nvim.sock' or NVIM_LISTEN_ADDRESS is set.")