Python + UV + Neovim Setup Guide

What You Get

Your Neovim setup now includes:

🐍 Python Development Features

• LSP Support: Pyright for type checking + Ruff for linting/formatting
• Auto-formatting: Automatic code formatting with Ruff on save
• Debugging: Full debugging support with nvim-dap
• Testing: Integrated test runner with neotest
• Virtual Environment: Automatic detection and selection

📦 UV Integration

• Project Detection: Auto-detects UV projects (pyproject.toml/uv.lock)
• Environment Activation: Automatically uses correct Python interpreter
• Dependency Management: Works seamlessly with uv commands

Installation Steps

1. Install UV (if not already installed)

# Install uv
curl -LsSf https://astral.sh/uv/install.sh | sh

# Or with pip
pip install uv

2. Update Your Neovim Config

The updated configuration is already in your init.lua. Restart Neovim to install the new plugins:

nvim

Wait for all plugins to install, then restart Neovim again.

3. Install the UV Helper Script (Optional)

# Make the script executable and add to PATH
chmod +x ~/.local/bin/uvnvim

# Or add the functions to your shell profile
cat >> ~/.bashrc << 'EOF'
# UV + Neovim integration (paste the content from the UV script here)
EOF

Key Bindings

🔍 LSP & Navigation

• gd - Go to definition
• K - Show hover info
• <Space>vrn - Rename symbol
• <Space>vca - Code actions
• [d / ]d - Navigate diagnostics

🐛 Debugging

• <Space>db - Toggle breakpoint
• <Space>dc - Continue/Start debugging
• <Space>dr - Open REPL
• <Space>dt - Terminate debugging

🧪 Testing

• <Space>tt - Run test under cursor
• <Space>tf - Run all tests in file
• <Space>td - Debug test under cursor
• <Space>ts - Toggle test summary
• <Space>to - Open test output

🌍 Virtual Environment

• <Space>vs - Select virtual environment
• <Space>vc - Use cached environment selection

📝 Formatting

• <Space>f - Format current buffer

Usage Examples

Starting a New UV Project

# Create a new project with proper structure
create_uv_project my-awesome-project
cd my-awesome-project

# Start Neovim with UV context
uvnvim

Working with Existing UV Project

cd existing-uv-project

# Start Neovim (auto-detects UV project)
uvnvim

# Or just use regular nvim (auto-detection still works)
nvim

Creating a Virtual Environment

# In your project directory
uv venv

# Install dependencies
uv add requests pytest black ruff

# Install development dependencies
uv add --dev mypy pre-commit

Project Structure Best Practices

my-project/
├── pyproject.toml          # Project configuration
├── uv.lock                 # Dependency lock file
├── .venv/                  # Virtual environment (auto-created)
├── src/
│   └── my_project/
│       ├── __init__.py
│       └── main.py
├── tests/
│   └── test_main.py
├── README.md
└── .gitignore

Troubleshooting

Python Interpreter Not Found

1. Select virtual environment: <Space>vs
2. Or manually set: :lua vim.g.python3_host_prog = '/path/to/python'

LSP Not Working

1. Check Mason installations: :Mason
2. Restart LSP: :LspRestart
3. Check LSP status: :LspInfo

Debugging Not Working

1. Ensure debugpy is installed: uv add --dev debugpy
2. Check DAP status: :lua print(vim.inspect(require('dap').configurations.python))

Tests Not Running

1. Install pytest: uv add --dev pytest
2. Check test adapter: :lua print(vim.inspect(require('neotest').status()))

Pro Tips

1. Auto-format on Save

The configuration automatically formats Python files on save using Ruff.

2. Virtual Environment in Status Line

The status line shows your current virtual environment.

3. Integrated Terminal

Use Ctrl+\ to open a floating terminal that inherits the UV environment.

4. Quick Project Setup

Use the create_uv_project function to scaffold new projects with all the right tools.

5. Multi-file Debugging

Set breakpoints in multiple files and debug complex workflows easily.

UV Commands Reference

# Project management
uv init                     # Initialize new project
uv add <package>           # Add dependency
uv add --dev <package>     # Add dev dependency
uv remove <package>        # Remove dependency
uv sync                    # Install all dependencies

# Running code
uv run python script.py    # Run with project environment
uv run pytest             # Run tests
uv run black .             # Format code
uv run ruff check .        # Lint code

# Environment management
uv venv                    # Create virtual environment
uv pip install <package>  # Install with pip compatibility

Disclaimer: this is claude generated.