Python Dependencies¶
Reference documentation for Python packages used in the configuration.
Overview¶
The configuration requires a Python virtual environment (~/.virtualenvs/nvim) with specific packages installed.
The install.py script handles this automatically, but you can also install manually.
List of Dependencies¶
Package Details¶
pynvim¶
What it does: Provides Python bindings for Neovim’s msgpack API.
Why needed: Neovim plugins written in Python need this to communicate with the editor.
Installation:
~/.virtualenvs/nvim/bin/pip install pynvim>=0.4.3
Features:
Execute Neovim commands from Python
Access Neovim buffers and windows
Write Neovim plugins in Python
RPC communication with Neovim
Version requirement: 0.4.3+ supports Neovim 0.5+
Documentation: pynvim GitHub
Zuban¶
What it does: Python Language Server providing intelligent code analysis.
Why needed: Enables LSP features:
Code completion
Go to definition
Find references
Hover information
Diagnostics (errors/warnings)
Rename refactoring
Installation:
~/.virtualenvs/nvim/bin/pip install zuban>=0.2.0
Zuban features:
Written in Rust (very fast)
Type checking
Comprehensive Python support
Supports Python 3.8+
Active development
Configuration: Configured in lua/lsp/lsp.lua
Example settings:
settings = {
python = {
analysis = {
typeCheckingMode = "basic",
}
}
}
Documentation: Zuban GitHub
Alternative servers (if you want different ones):
Pylance (Microsoft, VS Code focused)
Pyright (similar to Pylance)
Jedi (simple, good for basic tasks)
To use a different server, edit lua/lsp/lsp.lua and change the server configuration.
Ruff¶
What it does: Fast, modern Python linter checking code quality.
Why needed: Catches common errors and style issues:
Undefined variables
Unused imports
Style violations (PEP 8)
Complexity issues
And hundreds more rules
Installation:
~/.virtualenvs/nvim/bin/pip install ruff>=0.1.0
Features:
Extremely fast (written in Rust)
Minimal configuration
Compatible with Black formatter
Thousands of rules
Extensible
Configuration in pyproject.toml:
[tool.ruff]
line-length = 100
select = ["E", "W", "F", "I"] # What rules to enable
ignore = ["E501"] # What to ignore
Rules:
E: PEP 8 errors
W: PEP 8 warnings
F: PyFlakes (logic errors)
I: isort (import sorting)
Documentation: Ruff GitHub
Darker¶
What it does: Code formatter that applies Black formatting to only changed lines.
Why needed: Keeps code style consistent while minimizing git diffs:
Formats Python code
Uses Black formatting
Integrates isort for imports
Only touches changed lines
Respects line length
Installation:
~/.virtualenvs/nvim/bin/pip install "darker[isort]>=1.7.0"
Note the [isort] extra - this includes isort integration.
Features:
Diff-aware (only changes what changed)
Black-compatible
isort integration for imports
Respects git history
Preserves unchanged code
Configuration in pyproject.toml:
[tool.darker]
line_length = 140
[tool.isort]
profile = "black"
multi_line_mode = 3
Line length: Set to 140 by default (configurable)
Keybinding: <leader>f to format current file
Why darker vs black?
Black reformats entire file (more disruptive)
Darker only reformats changed lines (cleaner diffs)
Perfect for gradual formatting adoption
Better for team settings where code style is evolving
Documentation: Darker GitHub
Installing Dependencies¶
Automatic (recommended):
python3 install.py
The script handles everything.
Manual installation:
# Create virtual environment
python3 -m venv ~/.virtualenvs/nvim
# Activate it
source ~/.virtualenvs/nvim/bin/activate
# Install packages
pip install pynvim zuban ruff "darker[isort]"
# Deactivate
deactivate
Using uv (faster):
# Install uv first
pip install uv
# Create venv
uv venv ~/.virtualenvs/nvim
# Install packages
uv pip install pynvim zuban ruff "darker[isort]"
Updating Dependencies¶
Update all:
~/.virtualenvs/nvim/bin/pip install --upgrade pynvim zuban ruff darker
Update specific package:
~/.virtualenvs/nvim/bin/pip install --upgrade zuban
Check for updates:
~/.virtualenvs/nvim/bin/pip list --outdated
Update via pyproject.toml:
Edit versions in pyproject.toml:
[project]
dependencies = [
"pynvim>=0.5.0", # New version
"zuban>=0.3.0", # New version
]
Then reinstall:
~/.virtualenvs/nvim/bin/pip install --upgrade -e .
Verifying Installation¶
Check what’s installed:
~/.virtualenvs/nvim/bin/pip list
Should show:
Package Version
---------- -------
pynvim 0.4.3
zuban 0.2.5
ruff 0.1.8
darker 1.7.2
isort 5.12.0
Verify Neovim can use them:
:checkhealth python
Should show green checkmarks for:
Python provider
Python3 executable path
Packages found
Test LSP:
# Create test file
echo 'undefined_variable' > test.py
# Open in Neovim
nvim test.py
# Should show LSP error (red squiggly)
Test formatting:
<leader>f
Should format the file with darker.
Adding Custom Dependencies¶
If you need additional Python packages for your setup:
Edit pyproject.toml:
[project]
dependencies = [
"pynvim>=0.4.3",
"zuban>=0.2.0",
"ruff>=0.1.0",
"darker[isort]>=1.7.0",
"my_custom_package>=1.0.0", # Add here
]
Install:
~/.virtualenvs/nvim/bin/pip install my_custom_package
Use in configuration:
-- In lua/utils/my_utils.lua
local function use_custom_package()
-- Python code via pynvim
end
Troubleshooting Dependencies¶
Error: ModuleNotFoundError: No module named ‘zuban’
Solution: Install it:
~/.virtualenvs/nvim/bin/pip install zuban
Error: Wrong Python being used
Verify which Python Neovim is using:
:checkhealth python
Should point to ~/.virtualenvs/nvim/bin/python.
If not, edit lua/lsp/lsp.lua:
settings = {
python = {
pythonPath = os.getenv('HOME') .. '/.virtualenvs/nvim/bin/python',
}
}
Error: Version conflict
Some packages may require specific versions:
~/.virtualenvs/nvim/bin/pip install --upgrade zuban pynvim
Virtual environment not found
Create it:
python3 -m venv ~/.virtualenvs/nvim
~/.virtualenvs/nvim/bin/pip install pynvim zuban ruff "darker[isort]"
Performance Tips¶
Installation is slow:
Use uv for faster installation:
pip install uv
uv pip install pynvim zuban ruff "darker[isort]"
Much faster than standard pip.
Large virtual environment:
You can delete and recreate if needed:
rm -rf ~/.virtualenvs/nvim
python3 -m venv ~/.virtualenvs/nvim
~/.virtualenvs/nvim/bin/pip install pynvim zuban ruff "darker[isort]"
Alternative: Use system Python:
If you don’t want to use a virtual environment:
Edit lua/lsp/lsp.lua:
settings = {
python = {
pythonPath = "/usr/bin/python3", # System Python
}
}
Not recommended - virtual environment is better for isolation.
Security Considerations¶
Virtual environment isolation:
Packages installed in ~/.virtualenvs/nvim/ don’t affect system Python:
Safer
No conflicts
Can be deleted and recreated
Reproducible
Keeping packages updated:
Regularly check for security updates:
~/.virtualenvs/nvim/bin/pip install --upgrade pip
~/.virtualenvs/nvim/bin/pip install --upgrade pynvim zuban ruff darker
Pinning versions:
For reproducibility, specify exact versions:
~/.virtualenvs/nvim/bin/pip install pynvim==0.4.3 zuban==0.2.0
See the pyproject.toml for current versions.
Alternative Setups¶
Use Poetry:
If your project uses Poetry:
poetry add pynvim zuban ruff darker
poetry run nvim
Use uv:
uv venv ~/.virtualenvs/nvim
uv pip install pynvim zuban ruff "darker[isort]"
Use conda:
conda create -n nvim-env python=3.11
conda activate nvim-env
pip install pynvim zuban ruff "darker[isort]"
Dependencies Summary¶
pynvim - Neovim Python API
zuban - Python LSP (code intelligence)
ruff - Linter (code quality)
darker - Formatter (code style)
All installed in a dedicated virtual environment at ~/.virtualenvs/nvim.
For more information on each tool, see their documentation:
pynvim: https://github.com/neovim/pynvim
For configuration details, see LSP Configuration and Customization.