v2.0 IBM/docling-pipelines

Quick Start Guide

Get your first pipeline running in under 5 minutes.

⏱ ~5 min total ⚙️ Prerequisites 30s 📦 Setup 2 min 🚀 First run 2 min

This guide provides the fastest path from installation to a working document processing pipeline. For detailed setup and advanced features, see USER_GUIDE_PIPELINE_SETUP.md.

Prerequisites Check (30 seconds)

Before starting, verify you have Python 3.12 and ~5 GB of free disk space:

# Check Python 3.12
python3.12 --version
# Expected: Python 3.12.x

# Check available disk space (need ~5GB)
df -h .

Don't have Python 3.12?

  • macOS: brew install python@3.12
  • Ubuntu/Debian: sudo apt install python3.12 python3.12-venv
  • Fedora/RHEL: sudo dnf install python3.12

Automated Setup (2 minutes)

Run the automated setup script to install everything:

# Clone the repository
git clone https://github.com/IBM/docling-pipelines.git
cd docling-pipelines

# Make setup script executable
chmod +x scripts/setup_docling_pipelines_environment.sh

# Run automated setup (installs only required model for quick start)
./scripts/setup_docling_pipelines_environment.sh --models nomic-embed-text

What this installs:

  • ✅ uv package manager
  • ✅ Ollama server + nomic-embed-text model (~274 MB)
  • ✅ OpenSearch + Dashboards (for vector storage)
  • ✅ Python virtual environment + dependencies
Note

Setup takes 5–10 minutes depending on your internet connection.

Configure Environment

# Copy environment template
cp .env.example .env

# The default values work for local development
# Edit .env if you need to customize settings

Verify Services

# Check Ollama (should return list of models)
curl http://localhost:11434/api/tags

# Check OpenSearch (should return cluster info)
curl -u admin:MyStrongPass123! http://localhost:9200
Success

Both commands return JSON responses — you're ready to run your first pipeline.

Failed?

Jump to the Troubleshooting section below.

Your First Pipeline (2 minutes)

Step 1
Verify Sample Documents

The repository includes sample text files ready to process.

ls -la sample_documents/
# Output includes: hello.txt, 1kb_file.txt samples
Step 2
Activate Environment

Set PYTHONPATH and activate the virtual environment.

# Set PYTHONPATH (from project root)
export PYTHONPATH="$(pwd)/src:${PYTHONPATH}"

# Activate virtual environment
source .venv/bin/activate
Step 3
Run the Pipeline

Execute the complete document processing pipeline.

docling-pipelines --flow-file sample_flows/quickstart/complete_pipeline_ollama.json

Expected Output

================================================================================
 FLOW: complete-document-pipeline
 Operators: 5
 Started: 2024-01-15 10:30:00
================================================================================

[ingest] Starting ingest_source...
================================================================================
 ingest (COMPLETED)
================================================================================
 Duration: 0.50s | Documents: 1 processed, 0 failed, 0 skipped
 Data Columns: 8 total (8 added by this operator)
   Added (8): id, name, path, size, created_time, modified_time, content, extension
================================================================================

[extract] Starting extract_operator...
[chunk]   Starting chunker...
[embed]   Starting embeddings...
[store]   Starting vectordb...

================================================================================
 FLOW EXECUTION SUMMARY
================================================================================
 Status: COMPLETED  |  Total Duration: 15.30s
 Documents: 1 completed, 0 failed, 0 skipped

 Operator                       Status     Duration  Docs
 ──────────────────────────────────────────────────────────
 ingest_source_filesystem       Completed  < 1s      2/2
 extract_with_docling           Completed  < 1s      2/2
 simple_chunker                 Completed  1.00s     2/2
 ollama_embeddings              Completed  1.00s     2/2
 opensearch_vector_store        Completed  1.00s     2/2
================================================================================
Step 4
Verify Success

Check that your document was stored in OpenSearch.

curl -u admin:MyStrongPass123! \
  "http://localhost:9200/sample-documents-index/_search?pretty" \
  -H 'Content-Type: application/json' \
  -d '{"query": {"match_all": {}}, "size": 1}'
🎉 Congratulations!

You've successfully installed Docling Pipelines, processed a document through the complete pipeline, and stored vector embeddings in OpenSearch.

Understanding What Just Happened

Your document went through this pipeline:

📄 Text File input
→
📥 Ingest ingest_source
→
📝 Extract extract_operator
→
✂️ Chunk chunker
→
🧮 Embed embeddings
→
💾 Store vectordb
OperatorWhat it did
ingest_sourceRead hello.txt from disk via the filesystem provider
extract_operatorExtracted structured content using docling_library mode
chunkerSplit into simple chunks (~512 chars each)
embeddingsGenerated vector embeddings using Ollama + nomic-embed-text
vectordbStored in OpenSearch for similarity search

What's Next?

Explore More Flows

ls -la sample_flows/

Invoice Processing Example

This flow uses entity extraction (NuExtract) and an LLM-based document classifier. Install the required dependency and pull the model first:

# Required for entity extraction with NuExtract
uv pip install qwen-vl-utils

# Required for the document classifier node
ollama pull llama3.2

docling-pipelines --flow-file sample_flows/use_cases/invoice_processing.json

View Data in OpenSearch Dashboards

Open http://localhost:5601 — Username: admin · Password: MyStrongPass123!

Create Your Own Pipeline

# Copy sample flow as starting point
cp sample_flows/quickstart/complete_pipeline_ollama.json my_flow.json

# Edit paths, chunk_size, models …
open my_flow.json

# Run your custom flow
docling-pipelines --flow-file my_flow.json

Deep Dive Documentation

Run the Web UI

The frontend requires Node.js 22 and the FastAPI backend already running.

Step 1
Install Node.js 22.15.1

Use nvm (recommended) or download from nodejs.org.

nvm install 22.15.1
nvm use 22.15.1
node --version   # v22.15.1
Step 2
Start the FastAPI Backend

In one terminal, from the project root:

source .venv/bin/activate
uvicorn docpipe.api.main:app --host 0.0.0.0 --port 8080
Warning

Do not use python src/docpipe/api/main.py when running the UI in dev mode — it starts a BFF sidecar on port 3001 that conflicts with npm run dev.

Step 3
Start the UI

In a second terminal, from the project root:

cd frontend
npm install          # once
cp .env.example .env # once
npm run dev

Open http://localhost:3000/ui/

Troubleshooting Quick Fixes

Setup script failed — Python 3.12 not found

Install Python 3.12 first, then re-run the setup script.

./scripts/setup_docling_pipelines_environment.sh
Ollama not responding
ollama serve &
sleep 5
curl http://localhost:11434/api/tags
OpenSearch not responding
podman-compose -f docker/docker-compose.opensearch.yml up -d
sleep 30
curl -u admin:MyStrongPass123! http://localhost:9200
ModuleNotFoundError / import errors
export PYTHONPATH="$(pwd)/src:${PYTHONPATH}"
pwd  # Should end with /docling-pipelines
Still having issues? Start fresh
podman-compose -f docker/docker-compose.opensearch.yml down
pkill -f "ollama serve"
rm .docpipe_setup_config docpipe_setup.log
./scripts/setup_docling_pipelines_environment.sh

Quick Reference Commands

# Activate environment (from project root)
export PYTHONPATH="$(pwd)/src:${PYTHONPATH}"
source .venv/bin/activate

# Run a flow
docling-pipelines --flow-file path/to/flow.json

# List operators (summary)
docling-pipelines --list-operators

# List operators (verbose)
docling-pipelines --list-operators --verbose

# Check Ollama
curl http://localhost:11434/api/tags

# Check OpenSearch
curl -u admin:MyStrongPass123! http://localhost:9200

# Stop services
podman-compose -f docker/docker-compose.opensearch.yml down
pkill -f "ollama serve"