Paperless-ngx AI Setup: Native AI from Version 3 with Local Ollama

Using Paperless-ngx with AI? WZ-IT sets up the native AI in Paperless-ngx, connects local models and operates the instance long term if required, see Paperless-ngx at WZ-IT and Paperless-AI and AI integration. Book a meeting

Until recently, using Paperless-ngx with AI meant adding a separate project such as Paperless-AI. Since version 3.0.0, released on 22 July 2026, Paperless-ngx ships AI itself: suggestions for title, tags, correspondent and document type, a chat about a single document or the whole archive, and a vector index for similar documents. Version 3.1.0 added a workflow action that applies these suggestions automatically.

At the same time, the Paperless-AI repository has carried the notice "This repo is currently not maintained" since March 2026 (clusterzx/paperless-ai). For new installations the native integration is the obvious route; for existing Paperless-AI setups the question is how to switch.

This post covers the setup with a local Ollama server via Docker Compose, every AI variable with its default, model choice for non-English archives, automatic tagging via workflows, data flows and the migration from Paperless-AI. All details refer to Paperless-ngx 3.2.1 (as of October 2026).

Table of Contents

1. Key facts at a glance
2. What the native AI in Paperless-ngx does
3. What has changed since version 3
4. Requirements and hardware
5. Step by step: Paperless-ngx with Ollama via Docker Compose
6. All AI variables at a glance
7. Choosing generation and embedding models
8. Automatic tagging with the workflow action
9. Privacy: which data leaves the system
10. Native AI vs. Paperless-AI compared
11. Moving off Paperless-AI
12. Limitations as of October 2026
13. Our approach at WZ-IT
14. Further guides

Key facts at a glance

Sources: Configuration, AI section, Advanced Usage, AI features, releases, source code vector_store.py.

What the native AI in Paperless-ngx does

The documentation describes three features. All are optional and none replaces the existing non-LLM matching (Advanced Usage):

Two details matter in operation:

• Suggestions on open. For documents with an inbox tag, suggestions are requested automatically as soon as the document is opened. Since 3.2.0 this can be switched off under Settings > Documents (Usage, Document Suggestions). With a local model, every open is a request to the GPU.
• Permissions. The chat only searches documents the signed-in user may see. The source code filters the vector search to the permitted document IDs (chat.py). Since 3.0.0, suggestions require change permission on the document (release 3.0.0).

What has changed since version 3

If you are coming from 2.x, read the breaking changes of 3.0.0 before upgrading. They include, among others, the removal of document encryption, of API version 1 and of Python 3.10 support (release 3.0.0). For Docker installations the usual rule applies: back up first, then update the image.

Requirements and hardware

• Paperless-ngx 3.1.0 or later, preferably the current 3.2.1 if you want the workflow action. The guide Paperless-ngx on Ubuntu with Caddy shows a Docker installation with Caddy.
• Ollama as a container on the same host or as a separate server on the internal network (Ollama, Docker). On a separate server, the Ollama port should only be reachable from the Paperless network. The post on Bleeding Llama explains why an openly reachable Ollama is a risk.
• A GPU for usable response times. Ollama also runs on CPU, but suggestions then take considerably longer. NVIDIA GPUs in containers require the NVIDIA Container Toolkit.

As a rough guide, the model plus its context has to fit into GPU memory. The download sizes from the Ollama library are the lower bound:

By default, Paperless-ngx sends a context of 8,192 tokens to Ollama (PAPERLESS_AI_LLM_CONTEXT_SIZE, sent as num_ctx for Ollama). Memory usage is therefore above the download size. The article Sizing GPU VRAM for LLMs explains how to calculate GPU memory for models and context.

Step by step: Paperless-ngx with Ollama via Docker Compose

The starting point is the official docker-compose.postgres.yml. It is extended with an Ollama service and the AI variables in the webserver service.

1. Extend the Compose file

services:
  broker:
    image: docker.io/valkey/valkey:9-alpine
    restart: unless-stopped
    volumes:
      - redisdata:/data

  db:
    image: docker.io/library/postgres:18
    restart: unless-stopped
    volumes:
      - pgdata:/var/lib/postgresql
    environment:
      POSTGRES_DB: paperless
      POSTGRES_USER: paperless
      POSTGRES_PASSWORD: paperless   # change in production

  ollama:
    image: docker.io/ollama/ollama:latest
    restart: unless-stopped
    volumes:
      - ollama:/root/.ollama
    # no "ports:" needed, Paperless reaches Ollama via the Compose network
    deploy:
      resources:
        reservations:
          devices:
            - driver: nvidia
              count: all
              capabilities: [gpu]

  webserver:
    image: ghcr.io/paperless-ngx/paperless-ngx:latest   # pin a version in production
    restart: unless-stopped
    depends_on:
      - db
      - broker
      - ollama
    ports:
      - "8000:8000"
    volumes:
      - data:/usr/src/paperless/data
      - media:/usr/src/paperless/media
      - ./export:/usr/src/paperless/export
      - ./consume:/usr/src/paperless/consume
    env_file: docker-compose.env
    environment:
      PAPERLESS_REDIS: redis://broker:6379
      PAPERLESS_DBHOST: db
      PAPERLESS_DBENGINE: postgresql
      # AI
      PAPERLESS_AI_ENABLED: "true"
      PAPERLESS_AI_LLM_BACKEND: ollama
      PAPERLESS_AI_LLM_ENDPOINT: http://ollama:11434
      PAPERLESS_AI_LLM_MODEL: gemma3:12b
      PAPERLESS_AI_LLM_EMBEDDING_BACKEND: ollama
      PAPERLESS_AI_LLM_EMBEDDING_MODEL: bge-m3
      PAPERLESS_AI_LLM_REQUEST_TIMEOUT: "300"

volumes:
  data:
  media:
  pgdata:
  redisdata:
  ollama:

The deploy.resources.reservations.devices block reserves the NVIDIA GPU for the Ollama container (Docker, GPU support in Compose). Remove it if there is no GPU. If Ollama runs on another server, drop the ollama service and point PAPERLESS_AI_LLM_ENDPOINT to its internal address.

2. Start and pull the models

docker compose pull
docker compose up -d
docker compose exec ollama ollama pull gemma3:12b
docker compose exec ollama ollama pull bge-m3

3. Build the LLM index

Rebuild the index from scratch when enabling it for the first time and after every change of the embedding model (Administration, LLM index):

docker compose exec webserver document_llmindex rebuild

After that, a scheduled task keeps the index up to date, by default daily at 02:10 (PAPERLESS_LLM_INDEX_TASK_CRON, default 10 2 * * *). For large archives the first build takes correspondingly long; embeddings run on the same GPU as the suggestions.

4. Check in the UI

• Open a document and expand the menu next to the suggest button. AI suggestions appear there in addition to the classic suggestions.
• Open the chat in the top toolbar. On the detail page it refers to the open document, in lists to all visible documents.

The AI settings can also be set under Settings > Application Configuration. Database values take precedence over environment variables (Advanced Usage). If you manage the configuration in Compose, leave the fields in the UI empty, otherwise a change in the Compose file has no effect.

5. On updates

Since version 3, migrating the LLM index is part of the update procedure. In the Docker image, document_llmindex migrate runs automatically when the container starts (init script init-llmindex-migrate). On bare-metal installations, the command is a separate step after the database migration (Administration, Updating).

The index lives in the data volume under llm_index and is therefore part of the existing backup.

All AI variables at a glance

Source: Paperless-ngx configuration, AI section, version 3.2.1.

On PAPERLESS_AI_LLM_ALLOW_INTERNAL_ENDPOINTS: for a local Ollama the value has to stay true, otherwise Paperless-ngx blocks addresses such as http://ollama:11434. Set it to false only if you exclusively use an external provider and want to rule out requests into the internal network.

Choosing generation and embedding models

Paperless-ngx uses two separate models. The project wiki gives guidance, explicitly without benchmarks (AI Model Recommendations):

• Generation model (PAPERLESS_AI_LLM_MODEL): an instruction or chat model that reliably produces structured output. Start with a small model and only move up if quality is insufficient.
• Embedding model (PAPERLESS_AI_LLM_EMBEDDING_MODEL): the Hugging Face default all-MiniLM-L6-v2 is meant for primarily English archives. For multilingual archives the wiki lists intfloat/multilingual-e5-small, intfloat/multilingual-e5-base and BAAI/bge-m3.

For a German or mixed-language archive this means:

Test with a sample of typical documents: invoices, contracts, letters from authorities, poor-quality scans. The article Which LLM to self-host? helps to classify models for self-hosting. If text recognition itself is the problem, see the comparison of local VLM OCR models.

Automatic tagging with the workflow action

Suggestions alone do not change a document. For automatic assignment, the "Apply AI Suggestions" workflow action has existed since 3.1.0 (Usage, Workflows). It requests the same suggestions as the document detail page and applies them.

A proven setup to start with:

1. Trigger "Document Added", filtered on the inbox tag or an intake folder.
2. Action "Apply AI Suggestions" with correspondent, document type and tags, "create missing items" off.
3. Second action (assignment): a tag such as ai-suggested, so that AI-processed documents can be reviewed specifically.
4. After a few weeks, review samples and only then add title and date with overwriting.

The documentation points out that every matching document triggers a request to the model. A workflow across the whole archive can occupy the task queue for a long time and delay processing of new documents. For existing documents, work in small batches.

Privacy: which data leaves the system

For suggestions, chat and embeddings, Paperless-ngx sends document content and metadata to the configured backend (Usage, AI Features). Where the data goes depends solely on the configuration:

Remote OCR is a separate feature from version 3.0.0 and off by default (Usage, Remote OCR). When enabled in always mode, every supported document is sent to Azure. Since 3.1.0, PAPERLESS_REMOTE_OCR_MODE=workflow_only limits it to individual documents via workflows. If you choose local AI for privacy reasons, do not enable Remote OCR in passing.

The documentation treats document content as untrusted data towards the model. A document may contain text phrased like an instruction to the model. For automatic workflows this is an argument for using "create missing items" and "overwrite" sparingly. Background in the article Prompt injection protection.

Native AI vs. Paperless-AI compared

Sources: Paperless-ngx Advanced Usage, Paperless-AI README, Paperless-AI sample configuration, Paperless-AI releases.

Paperless-AI only keeps an advantage where a custom system prompt or filling custom fields is needed. That has to be weighed against a project without security updates that holds an API token with broad access to the archive.

Moving off Paperless-AI

The switch takes six steps and loses no data. Paperless-AI writes its results directly into Paperless-ngx, so tags, correspondents and titles remain in place.

1. Back up and upgrade. Back up Paperless-ngx, review the breaking changes of 3.0.0 and upgrade to 3.2.1.
2. Record the configuration. From the Paperless-AI configuration, note the model and endpoint (OLLAMA_API_URL, OLLAMA_MODEL or CUSTOM_BASE_URL), the filter tag (TAGS), the processed tag (AI_PROCESSED_TAG_NAME) and any changes to SYSTEM_PROMPT.
3. Stop Paperless-AI. Stop the container but do not delete it yet, so that two systems do not process the same documents in parallel.
4. Enable native AI. Enter the existing Ollama endpoint as PAPERLESS_AI_LLM_ENDPOINT, set the embedding backend and run document_llmindex rebuild.
5. Rebuild the workflow. Use the former filter tag as the workflow filter, create "Apply AI Suggestions" with the fields used so far and set the processed tag with an assignment action.
6. Verify and retire. Compare a sample of new documents. Then remove the Paperless-AI container and its data and revoke its API token in Paperless-ngx.

What does not carry over: a customised system prompt and filling custom fields. If you depend on these, clarify this with the business teams before switching. The existing guides for Paperless-AI and the Paperless-AI installer remain available for existing installations.

Limitations as of October 2026

Some limitations from the 3.0 days still apply in 3.2.1. They can be traced in the source code:

In practice: suggestions and the workflow action are fit for production use with a review step. The chat works as a search aid for questions like "When does the lease end?", but does not replace research across many documents with a complete list of sources. If you need that, build a dedicated RAG application as described in Processing documents with AI.

Our approach at WZ-IT

WZ-IT operates Paperless-ngx for businesses and sets up the AI integration. When introducing the native AI we work in five steps:

1. Take stock. Record version, document volume, languages, existing rules and any running Paperless-AI installation.
2. Decide where the model runs. Depending on confidentiality: Ollama on existing hardware, a GPU server or an AI Cube on premises; cloud APIs only after an explicit decision.
3. Set up and test. Upgrade to 3.2.1, set the AI variables, build the index and assess suggestions on a sample together with the business teams.
4. Build workflows. Automatic assignment with a review tag, existing documents in batches, controlled retirement of Paperless-AI.
5. Operate. Updates including index migration, backups of documents and index, monitoring of the task queue.

Managed open source such as Paperless-ngx costs from EUR 129.90 excl. VAT per workload and month at WZ-IT (Managed Open Source). For local models with sensitive documents, the AI Cube is available at EUR 6,490 excl. VAT one-off plus AI Cube Care from EUR 349.90 excl. VAT per month. Support, consulting and implementation by WZ-IT.

Further guides

• Install Paperless-ngx on Ubuntu with Caddy, the base installation with Docker and automatic certificates.
• Install Paperless-AI, the previous extension for existing installations.
• Paperless-AI one-liner installer, installation by script.
• Local VLM OCR models, when text recognition itself needs to improve.
• Self-hosted AI document processing, capturing invoices and delivery notes in structured form.
• Processing documents with AI, from OCR to intelligent document processing.
• Which LLM to self-host?, classifying models for self-hosting.
• vLLM vs. Ollama, which inference server fits which job.
• AI solutions by WZ-IT, the hub for all local AI offerings.

Introducing Paperless-ngx with local AI? We set up the native AI, translate an existing Paperless-AI configuration into workflows and operate the instance long term if required. Book a meeting

Sources

• Paperless-ngx release 3.0.0
• Paperless-ngx release 3.0.5
• Paperless-ngx release 3.1.0
• Paperless-ngx release 3.1.3
• Paperless-ngx release 3.2.0
• Paperless-ngx release 3.2.1
• Paperless-ngx releases
• Paperless-ngx docs, Configuration: AI
• Paperless-ngx docs, Advanced Usage: AI features
• Paperless-ngx docs, Usage: AI Features
• Paperless-ngx docs, Usage: Apply AI Suggestions
• Paperless-ngx docs, Usage: Remote OCR
• Paperless-ngx docs, Administration: LLM index
• Paperless-ngx, init script init-llmindex-migrate (v3.2.1)
• Paperless-ngx wiki, AI Model Recommendations
• Paperless-ngx, docker-compose.postgres.yml (v3.2.1)
• Paperless-ngx source, chat.py (v3.2.1)
• Paperless-ngx source, chat.service.ts (v3.2.1)
• Paperless-ngx source, chat.component.html (v3.2.1)
• Paperless-ngx source, vector_store.py (v3.2.1)
• Paperless-AI repository with maintenance notice
• Paperless-AI releases
• Paperless-AI sample configuration .env.example
• Ollama docs, Docker
• Docker docs, GPU support in Compose
• Ollama library: gemma3
• Ollama library: qwen3
• Ollama library: llama3.1
• Ollama library: bge-m3
• Ollama library: embeddinggemma