pynvim

library0.6.0pypypi✓ verified 87d ago

Pynvim is the official Python client and plugin host for Neovim, enabling Python developers to interact with Neovim instances and write powerful remote plugins. Currently at version 0.6.0, it is actively maintained with regular releases addressing bug fixes, performance improvements, and new features.

http-networking web-framework

pip install pynvim

github ↗package ↗

INSTALL

IMPORT

SIG · PYNVIM

pynvim

http-networkingpythonv0.6.0

Install

2.1s avg

Import

247ms

Disk

22MB

Pass rate

10/ 10

Env Coverage10 / 10

glibc

3.9–3.13

musl

3.9–3.13

Install & Compatibility

Where this runs

tested against v0.6.0 · pip install

no network on importno background threads

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

py 3.10–3.920 runs

installs and imports cleanly · install 0.0s · import 0.259s · 25.3MB

glibc

py 3.10–3.920 runs

installs and imports cleanly · install 2.1s · import 0.235s · 23MB

22MB installed

● package 22MB

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

attach

✓ from pynvim import attach

neovim (old package name)

✓ from pynvim import attach

✗ import neovim

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.

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

Debug

Known issues

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

affects: <0.5.0

breakingThe `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.

affects: <0.6.0 (when using Python 3.14)

deprecatedThe 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`.

affects: >=0.3.1

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

affects: All versions

gotchaIn 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`.

affects: All versions

Errors

Common errors & fixes

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

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

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

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

Upgrade

Version history

0.6.0latest on PyPI · released Sep 7, 2025

Audit

Dependencies

No dependency data recorded yet.

Agent activity

16 hits · last 30 days

node

Resources

githubhttps://github.com/neovim/pynvim ↗

packagehttps://pypi.org/project/pynvim/ ↗