paperless-gpt

_{💡 Maintained by Icereed. Proudly supported by BubbleTax.de – automated, BMF-compliant tax reports for Interactive Brokers traders in Germany.}

paperless-gpt seamlessly pairs with [paperless-ngx][paperless-ngx] to generate AI-powered document titles and tags, saving you hours of manual sorting. While other tools may offer AI chat features, paperless-gpt stands out by supercharging OCR with LLMs-ensuring high accuracy, even with tricky scans. If you're craving next-level text extraction and effortless document organization, this is your solution.

https://github.com/user-attachments/assets/bd5d38b9-9309-40b9-93ca-918dfa4f3fd4

❤️ Support This Project
If paperless-gpt is helping you organize your documents and saving you time, please consider sponsoring its development. Your support helps ensure continued improvements and maintenance!

Key Highlights

1. LLM-Enhanced OCR
   Harness Large Language Models (OpenAI or Ollama) for better-than-traditional OCR—turn messy or low-quality scans into context-aware, high-fidelity text.

2. Use specialized AI OCR services

3. LLM OCR: Use OpenAI or Ollama to extract text from images.

4. Google Document AI: Leverage Google's powerful Document AI for OCR tasks.
5. Azure Document Intelligence: Use Microsoft's enterprise OCR solution.

6. Docling Server: Self-hosted OCR and document conversion service

7. Automatic Title, Tag & Created Date Generation
   No more guesswork. Let the AI do the naming and categorizing. You can easily review suggestions and refine them if needed.

8. Supports reasoning models in Ollama
   Greatly enhance accuracy by using a reasoning model like qwen3:8b. The perfect tradeoff between privacy and performance! Of course, if you got enough GPUs or NPUs, a bigger model will enhance the experience.

9. Automatic Correspondent Generation
   Automatically identify and generate correspondents from your documents, making it easier to track and organize your communications.

10. Automatic Custom Field Generation
    Extract and populate custom fields from your documents. Configure which fields to target and how they should be filled. This feature must be enabled in the settings, and you must select at least one custom field for it to function. Three write modes are available:

11. Append: This is the safest option: It only adds new fields that do not already exist on the document. It will never overwrite an existing field, even if it's empty.
12. Update: Adds new fields and overwrites existing fields with new suggestions. Fields on the document that don't have a new suggestion are left untouched.

13. Replace: Deletes all existing custom fields on the document and replaces them entirely with the suggested fields.

14. Searchable & Selectable PDFs
    Generate PDFs with transparent text layers positioned accurately over each word, making your documents both searchable and selectable while preserving the original appearance.

15. Extensive Customization

16. Customizable Prompts via Web UI: Tweak and manage all AI prompts for titles, tags, correspondents, and more directly within the web interface under the "Settings" menu. The application uses a safe default_prompts and prompts directory structure, ensuring your customizations are persistent.

17. Tagging: Decide how documents get tagged—manually, automatically, or via OCR-based flows.

18. PDF Processing: Configure how OCR-enhanced PDFs are handled, with options to save locally or upload to paperless-ngx.

19. Simple Docker Deployment
    A few environment variables, and you're off! Compose it alongside paperless-ngx with minimal fuss.

20. Unified Web UI

21. Manual Review: Approve or tweak AI's suggestions.

22. Auto Processing: Focus only on edge cases while the rest is sorted for you.

23. Ad-hoc Document Analysis Perform ad-hoc analysis on a selection of documents using a custom prompt. Gain quick insights, summaries, or extract specific information from multiple documents at once.

Table of Contents

• paperless-gpt
• Key Highlights
• Table of Contents
• Getting Started
  • Prerequisites
  • Installation
  • Docker Compose
  • Manual Setup
• OCR Providers
  • 1. LLM-based OCR (Default)
  • 2. Azure Document Intelligence
  • 3. Google Document AI
  • 4. Docling Server
• OCR Processing Modes
  • Image Mode (Default)
  • PDF Mode
  • Whole PDF Mode
  • Provider Compatibility
  • Existing OCR Detection
• Enhanced OCR Features
  • PDF Text Layer Generation
  • Local File Saving
  • PDF Upload to paperless-ngx
  • Metadata Copying Limitations
  • Safety Features
  • Usage Recommendations
• Configuration
  • Environment Variables
  • Custom Prompt Templates
  • Template Variables
• LLM-Based OCR: Compare for Yourself
  • Example 1
  • Example 2
  • How It Works
• Usage
• Troubleshooting
  • Working with Local LLMs
  • Token Management
  • PDF Processing Issues
  • Custom Field Generation Issues
• Contributing
• Support the Project
• License
• Star History
• Disclaimer

Getting Started

Prerequisites

• [Docker][docker-install] installed.
• A running instance of [paperless-ngx][paperless-ngx].
• Access to an LLM provider:
• OpenAI: An API key with models like gpt-4o or gpt-3.5-turbo.
• Ollama: A running Ollama server with models like qwen3:8b.

Installation

Docker Compose

Here's an example docker-compose.yml to spin up paperless-gpt alongside paperless-ngx:

services:
  paperless-ngx:
    image: ghcr.io/paperless-ngx/paperless-ngx:latest
    # ... (your existing paperless-ngx config)

  paperless-gpt:
    # Use one of these image sources:
    image: icereed/paperless-gpt:latest # Docker Hub
    # image: ghcr.io/icereed/paperless-gpt:latest  # GitHub Container Registry
    environment:
      PAPERLESS_BASE_URL: "http://paperless-ngx:8000"
      PAPERLESS_API_TOKEN: "your_paperless_api_token"
      PAPERLESS_PUBLIC_URL: "http://paperless.mydomain.com" # Optional
      MANUAL_TAG: "paperless-gpt" # Optional, default: paperless-gpt
      AUTO_TAG: "paperless-gpt-auto" # Optional, default: paperless-gpt-auto
      # LLM Configuration - Choose one:

      # Option 1: Standard OpenAI
      LLM_PROVIDER: "openai"
      LLM_MODEL: "gpt-4o"
      OPENAI_API_KEY: "your_openai_api_key"

      # Option 2: Mistral
      # LLM_PROVIDER: "mistral"
      # LLM_MODEL: "mistral-large-latest"
      # MISTRAL_API_KEY: "your_mistral_api_key"

      # Option 3: Azure OpenAI
      # LLM_PROVIDER: "openai"
      # LLM_MODEL: "your-deployment-name"
      # OPENAI_API_KEY: "your_azure_api_key"
      # OPENAI_API_TYPE: "azure"
      # OPENAI_BASE_URL: "https://your-resource.openai.azure.com"

      # Option 4: Ollama (Local)
      # LLM_PROVIDER: "ollama"
      # LLM_MODEL: "qwen3:8b"
      # OLLAMA_HOST: "http://host.docker.internal:11434"
      # OLLAMA_CONTEXT_LENGTH: "8192" # Sets Ollama NumCtx (context window)
      # TOKEN_LIMIT: 1000 # Recommended for smaller models

      # Option 5: Anthropic/Claude
      # LLM_PROVIDER: "anthropic"
      # LLM_MODEL: "claude-sonnet-4-5"
      # ANTHROPIC_API_KEY: "your_anthropic_api_key"

      # Optional LLM Settings
      # LLM_LANGUAGE: "English" # Optional, default: English

      # OCR Configuration - Choose one:
      # Option 1: LLM-based OCR
      OCR_PROVIDER: "llm" # Default OCR provider
      VISION_LLM_PROVIDER: "ollama" # openai, ollama, mistral, or anthropic
      VISION_LLM_MODEL: "minicpm-v" # minicpm-v (ollama) or gpt-4o (openai) or claude-sonnet-4-5 (anthropic/claude)
      OLLAMA_HOST: "http://host.docker.internal:11434" # If using Ollama

      # OCR Processing Mode
      OCR_PROCESS_MODE: "image" # Optional, default: image, other options: pdf, whole_pdf
      PDF_SKIP_EXISTING_OCR: "false" # Optional, skip OCR for PDFs with existing OCR

      # Option 2: Google Document AI
      # OCR_PROVIDER: 'google_docai'       # Use Google Document AI
      # GOOGLE_PROJECT_ID: 'your-project'  # Your GCP project ID
      # GOOGLE_LOCATION: 'us'              # Document AI region
      # GOOGLE_PROCESSOR_ID: 'processor-id' # Your processor ID
      # GOOGLE_APPLICATION_CREDENTIALS: '/app/credentials.json' # Path to service account key

      # Option 3: Azure Document Intelligence
      # OCR_PROVIDER: 'azure'              # Use Azure Document Intelligence
      # AZURE_DOCAI_ENDPOINT: 'your-endpoint' # Your Azure endpoint URL
      # AZURE_DOCAI_KEY: 'your-key'        # Your Azure API key
      # AZURE_DOCAI_MODEL_ID: 'prebuilt-read' # Optional, defaults to prebuilt-read
      # AZURE_DOCAI_TIMEOUT_SECONDS: '120'  # Optional, defaults to 120 seconds
      # AZURE_DOCAI_OUTPUT_CONTENT_FORMAT: 'text' # Optional, defaults to 'text', other valid option is 'markdown'
      # 'markdown' requires the 'prebuilt-layout' model

      # Enhanced OCR Features
      CREATE_LOCAL_HOCR: "false" # Optional, save hOCR files locally
      LOCAL_HOCR_PATH: "/app/hocr" # Optional, path for hOCR files
      CREATE_LOCAL_PDF: "false" # Optional, save enhanced PDFs locally
      LOCAL_PDF_PATH: "/app/pdf" # Optional, path for PDF files
      PDF_UPLOAD: "false" # Optional, upload enhanced PDFs to paperless-ngx
      PDF_REPLACE: "false" # Optional and DANGEROUS, delete original after upload
      PDF_COPY_METADATA: "true" # Optional, copy metadata from original document
      PDF_OCR_TAGGING: "true" # Optional, add tag to processed documents
      PDF_OCR_COMPLETE_TAG: "paperless-gpt-ocr-complete" # Optional, tag name

      # Option 4: Docling Server
      # OCR_PROVIDER: 'docling'              # Use a Docling server
      # DOCLING_URL: 'http://your-docling-server:port' # URL of your Docling instance
      # DOCLING_IMAGE_EXPORT_MODE: "placeholder" # Optional, defaults to "embedded"
      # DOCLING_OCR_PIPELINE: "standard" # Optional, defaults to "vlm"
      # DOCLING_OCR_ENGINE: "easyocr" # Optional, defaults to "easyocr" (only used when `DOCLING_OCR_PIPELINE is set to 'standard')


      AUTO_OCR_TAG: "paperless-gpt-ocr-auto" # Optional, default: paperless-gpt-ocr-auto
      OCR_LIMIT_PAGES: "5" # Optional, default: 5. Set to 0 for no limit.
      LOG_LEVEL: "info" # Optional: debug, warn, error
    volumes:
      - ./prompts:/app/prompts # Mount the prompts directory
      # For Google Document AI:
      - ${HOME}/.config/gcloud/application_default_credentials.json:/app/credentials.json
      # For local hOCR and PDF saving:
      - ./hocr:/app/hocr # Only if CREATE_LOCAL_HOCR is true
      - ./pdf:/app/pdf # Only if CREATE_LOCAL_PDF is true
    ports:
      - "8080:8080"
    depends_on:
      - paperless-ngx

Pro Tip: Replace placeholders with real values and read the logs if something looks off.

Manual Setup

1. Clone the Repository bash git clone https://github.com/icereed/paperless-gpt.git cd paperless-gpt
2. Create a prompts Directory bash mkdir prompts
3. Build the Docker Image bash docker build -t paperless-gpt .
4. Run the Container bash docker run -d \ -e PAPERLESS_BASE_URL='http://your_paperless_ngx_url' \ -e PAPERLESS_API_TOKEN='your_paperless_api_token' \ -e LLM_PROVIDER='openai' \ -e LLM_MODEL='gpt-4o' \ -e OPENAI_API_KEY='your_openai_api_key' \ -e LLM_LANGUAGE='English' \ -e VISION_LLM_PROVIDER='ollama' \ -e VISION_LLM_MODEL='minicpm-v' \ -e LOG_LEVEL='info' \ -v $(pwd)/prompts:/app/prompts \ -p 8080:8080 \ paperless-gpt

OCR Providers

For detailed provider-specific