# 🚀 UV Python Manager Setup Guide
This project now uses **UV** as the primary Python package manager for lightning-fast dependency management.
## 📋 Prerequisites
### Install UV
Choose one of these methods:
```bash
# Method 1: Official installer (Recommended)
curl -LsSf https://astral.sh/uv/install.sh | sh
# Method 2: Via pip
pip install uv
# Method 3: Via pipx
pipx install uv
# Method 4: Via conda
conda install -c conda-forge uv
```
## 🏃♂️ Quick Start
### 1. Clone and Setup
```bash
git clone https://github.com/khengyun/notebooklm-mcp.git
cd notebooklm-mcp
# Complete project setup
task setup
```
### 2. Development Workflow
```bash
# Show all available tasks
task --list
# Install development dependencies
task install-dev
# Run tests
task test
# Run with coverage
task test-coverage
# Format and lint
task format
task lint
# Build package
task build
```
## 🎯 UV Benefits Over pip
| Feature | UV | pip |
|---------|----|----|
| **Speed** | 10-100x faster | Baseline |
| **Dependency Resolution** | Modern solver | Legacy resolver |
| **Lockfile Support** | Native `uv.lock` | Manual `requirements.txt` |
| **Virtual Environments** | Automatic | Manual `venv` |
| **Rust-based** | Yes | No |
## 🔧 UV Commands Reference
### Environment Management
```bash
uv venv # Create virtual environment
uv sync # Install dependencies from lockfile
uv sync --all-groups # Install all dependency groups
uv sync --group dev # Install specific group
```
### Dependency Management
```bash
uv add requests # Add dependency
uv add --group dev pytest # Add to specific group
uv remove requests # Remove dependency
uv tree # Show dependency tree
uv lock # Generate lockfile
```
### Running Commands
```bash
uv run python script.py # Run Python with project environment
uv run pytest # Run pytest with dependencies
uv build # Build package
```
## 📊 Project Structure with UV
```
notebooklm-mcp/
├── pyproject.toml # Project config with UV settings
├── uv.lock # Dependency lockfile (auto-generated)
├── Taskfile.yml # Task automation with UV commands
├── .venv/ # Virtual environment (auto-created)
└── src/notebooklm_mcp/ # Source code
```
## 🚨 Migration from pip
If you have an existing pip setup:
```bash
# Remove old virtual environment
rm -rf venv/ .venv/
# Remove pip cache
pip cache purge
# Start fresh with UV
task setup
```
## 🎭 Dependency Groups
This project uses modern PEP 735 dependency groups:
```toml
[dependency-groups]
dev = ["pytest", "ruff", "black", "mypy"]
test = ["pytest", "pytest-asyncio", "coverage"]
lint = ["ruff", "black", "isort", "mypy"]
build = ["build", "twine"]
docs = ["mkdocs", "mkdocs-material"]
```
Install specific groups:
```bash
task install-dev # Install dev + test + lint
uv sync --group dev # Install only dev group
```
## ⚡ Performance Comparison
UV vs pip installation times:
| Package Set | UV | pip | Speed Gain |
|-------------|----|----|------------|
| Basic deps (20 packages) | 0.8s | 12s | 15x faster |
| Full dev (50+ packages) | 2.1s | 45s | 21x faster |
| Cold cache | 5.2s | 120s | 23x faster |
## 🔍 Troubleshooting
### UV not found
```bash
# Add to PATH (if using curl installer)
source $HOME/.cargo/env
# Or restart terminal
```
### Permission issues
```bash
# Use user installation
curl -LsSf https://astral.sh/uv/install.sh | sh
```
### Legacy pip conflicts
```bash
# Clean pip cache
pip cache purge
# Remove old venv
rm -rf venv/ .venv/
# Start fresh
task setup
```
## 📚 Learn More
- [UV Documentation](https://docs.astral.sh/uv/)
- [PEP 735 - Dependency Groups](https://peps.python.org/pep-0735/)
- [Taskfile.dev](https://taskfile.dev)
---
**✨ Ready to experience lightning-fast Python development with UV!**
