Basic Setup¶
Installation Methods¶
Method 1: From PyPI (Recommended)¶
Install the latest release from PyPI:
This installs the core package with VLM support and LiteLLM (for LLM providers). No extra steps are required for remote or local LLM backends.
Verify installation:
docling-graph --version
docling-graph --help
python -c "import docling_graph; print(docling_graph.__version__)"
Expected output:
Method 2: From Source (Development)¶
Use this method to contribute or run the latest development version.
Step 1: Install uv¶
Install the uv package manager:
Linux/macOS:
Windows (PowerShell):
Alternative (using pip):
Step 2: Clone Repository¶
Step 3: Install Dependencies¶
This installs the same core package as PyPI (VLM + LiteLLM). Use uv sync --extra dev for development tools.
Step 4: Verify Installation¶
When installed from source, run the CLI with uv run:
uv run docling-graph --version
uv run docling-graph --help
uv run python -c "import docling_graph; print(docling_graph.__version__)"
Installation Scenarios¶
Scenario 1: Quick Start (Remote LLM)¶
For users who want to get started quickly without GPU:
# Install from PyPI
pip install docling-graph
# Set API key
export OPENAI_API_KEY="your-key-here"
# Test
docling-graph --version
Time: ~1-2 minutes
Requirements: Internet connection, API key
GPU: Not required
Scenario 2: Local VLM (GPU Required)¶
For users with GPU who want local inference:
# Install from PyPI
pip install docling-graph
# Verify GPU
nvidia-smi
# Test
docling-graph --version
Time: ~2-5 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 from PyPI
pip install docling-graph
# Verify GPU
nvidia-smi
# Test
docling-graph --version
Time: ~5-10 minutes
Requirements: NVIDIA GPU with 8+ GB VRAM
GPU: Required
Scenario 4: Hybrid (Local + Remote)¶
For maximum flexibility:
# Install from PyPI
pip install docling-graph
# Set API keys (optional)
export OPENAI_API_KEY="your-key-here"
export MISTRAL_API_KEY="your-key-here"
# Test
docling-graph --version
Time: ~2-5 minutes
Requirements: GPU recommended, API keys optional
GPU: Optional
Post-Installation Configuration¶
Initialize Configuration¶
Run the interactive configuration wizard:
(Use uv run docling-graph init if you installed from source.)
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 (use uv run ... if from source)
docling-graph --help
docling-graph init --help
docling-graph convert --help
docling-graph inspect --help
Test with Example¶
# Run a simple example (requires API key or GPU; from repo only)
python docs/examples/scripts/02_quickstart_llm_pdf.py
# Or from source: uv run python docs/examples/scripts/02_quickstart_llm_pdf.py
Directory Structure (Source Install Only)¶
When you install from source, 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 (source install)¶
Cause: When installed from source, scripts must be run with uv run so they use the project environment.
Solution:
If you installed with pip, usepython and docling-graph directly.
🐛 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:
-
docling-graph --versionworks (oruv run docling-graph --versionif from source) -
docling-graph --helpshows commands -
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:
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/docling-project/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¶
If you installed from PyPI:
If you installed from source:
cd docling-graph
rm -rf .venv
cd ..
rm -rf docling-graph
# Optional: remove cache
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