Basic Setup¶
Installation Methods¶
Method 1: From Source (Recommended)¶
This is the recommended method for most users.
Step 1: Install uv¶
First, install the uv package manager:
Linux/macOS:
Windows (PowerShell):
Alternative (using pip):
Step 2: Clone Repository¶
Step 3: Choose Installation Type¶
Minimal (VLM only):
Full (all features):
Local LLM only:
Remote API only:
Specific providers:
# OpenAI
uv sync
# Mistral
uv sync
# Gemini
uv sync
# WatsonX
uv sync
# Ollama (local)
uv sync
# vLLM (local, requires GPU)
uv sync
Step 4: Verify Installation¶
# Check version
uv run docling-graph --version
# Test CLI
uv run docling-graph --help
# Test Python import
uv run python -c "import docling_graph; print(docling_graph.__version__)"
Expected output:
Method 2: From PyPI (Coming Soon)¶
Coming Soon
PyPI installation will be available in a future release.
Installation Scenarios¶
Scenario 1: Quick Start (Remote LLM)¶
For users who want to get started quickly without GPU:
# Install
git clone https://github.com/IBM/docling-graph
cd docling-graph
uv sync
# Set API key
export OPENAI_API_KEY="your-key-here"
# Test
uv run docling-graph --version
Time: ~2-3 minutes
Requirements: Internet connection, API key
GPU: Not required
Scenario 2: Local VLM (GPU Required)¶
For users with GPU who want local inference:
# Install
git clone https://github.com/IBM/docling-graph
cd docling-graph
uv sync
# Verify GPU
nvidia-smi
# Test
uv run docling-graph --version
Time: ~5-10 minutes
Requirements: NVIDIA GPU with 4+ GB VRAM
GPU: Required
Scenario 3: Full Local Setup (GPU Required)¶
For users who want all local capabilities:
# Install
git clone https://github.com/IBM/docling-graph
cd docling-graph
uv sync
# Verify GPU
nvidia-smi
# Test
uv run docling-graph --version
Time: ~10-15 minutes
Requirements: NVIDIA GPU with 8+ GB VRAM
GPU: Required
Scenario 4: Hybrid (Local + Remote)¶
For maximum flexibility:
# Install
git clone https://github.com/IBM/docling-graph
cd docling-graph
uv sync
# Set API keys (optional)
export OPENAI_API_KEY="your-key-here"
export MISTRAL_API_KEY="your-key-here"
# Test
uv run docling-graph --version
Time: ~10-15 minutes
Requirements: GPU recommended, API keys optional
GPU: Optional
Post-Installation Configuration¶
Initialize Configuration¶
Run the interactive configuration wizard:
This creates a config.yaml file with your preferences.
New in v1.2.0: Init command is 75-85% faster with intelligent caching!
Verify Installation¶
Run a simple test:
# Check all commands work
uv run docling-graph --help
uv run docling-graph init --help
uv run docling-graph convert --help
uv run docling-graph inspect --help
Test with Example¶
# Run a simple example (requires API key or GPU)
uv run python docs/examples/scripts/02_quickstart_llm_pdf.py
Directory Structure¶
After installation, your directory should look like:
docling-graph/
├── .venv/ # Virtual environment (created by uv)
├── docs/ # Documentation
├── docling_graph/ # Source code
├── examples/ # Example scripts and templates
├── tests/ # Test suite
├── pyproject.toml # Project configuration
├── uv.lock # Dependency lock file
└── README.md # Project readme
Environment Variables¶
Optional Configuration¶
Set these environment variables for customization:
# Logging level
export LOG_LEVEL="INFO" # DEBUG, INFO, WARNING, ERROR
# Temporary directory
export TEMP_DIR="/tmp/docling"
API Keys (if using remote providers)¶
See API Keys Setup for detailed instructions.
Updating¶
Update to Latest Version¶
# Navigate to repository
cd docling-graph
# Pull latest changes
git pull origin main
# Update dependencies
uv sync
Update Specific Components¶
Troubleshooting¶
🐛 uv command not found¶
Cause: uv not in PATH
Solution:
# Add to PATH (Linux/macOS)
export PATH="$HOME/.cargo/bin:$PATH"
# Or reinstall
curl -LsSf https://astral.sh/uv/install.sh | sh
🐛 Permission denied¶
Cause: Insufficient permissions
Solution:
🐛 Import errors¶
Cause: Not using uv run
Solution:
🐛 Slow installation¶
Cause: Network or disk speed
Solution:
# Use verbose mode to see progress
uv sync --verbose
# Or install in stages
uv sync # Core first
uv sync # Then remote
uv sync # Then local
🐛 CUDA not found (for GPU users)¶
Cause: CUDA not installed or not in PATH
Solution: See GPU Setup Guide
🐛 Out of disk space¶
Cause: Insufficient disk space
Solution:
# Check disk space
df -h
# Clean up if needed
uv cache clean
# Or install minimal version
uv sync # No extras
Verification Checklist¶
After installation, verify:
-
uv run docling-graph --versionworks -
uv run docling-graph --helpshows commands -
uv run python -c "import docling_graph"succeeds - GPU detected (if using local inference):
nvidia-smi - API keys set (if using remote):
echo $OPENAI_API_KEY - Config initialized:
uv run docling-graph init
Performance Notes¶
Installation Speed¶
New in v1.2.0: - First install: ~2-5 minutes (depending on extras) - Subsequent updates: ~30-60 seconds - Dependency caching: 90-95% faster validation
Disk Usage¶
Memory Usage¶
Development Setup¶
For contributors:
# Clone repository
git clone https://github.com/IBM/docling-graph
cd docling-graph
# Install with dev dependencies
uv sync --all-extras --dev
# Install pre-commit hooks
uv run pre-commit install
# Run tests
uv run pytest
# Run linting
uv run ruff check .
# Run type checking
uv run mypy docling_graph
Uninstalling¶
To completely remove Docling Graph:
# Remove virtual environment
cd docling-graph
rm -rf .venv
# Remove repository (optional)
cd ..
rm -rf docling-graph
# Remove cache (optional)
rm -rf ~/.cache/docling-graph
Next Steps¶
Installation complete! Now:
- GPU Setup (if using local inference) - Configure CUDA
- API Keys (if using remote) - Set up API keys
- Schema Definition - Create your first template
- Quick Start - Run your first extraction