DOCLING_SERVE_ALLOW_EXTERNAL_PLUGINS env var doesn't work

[jorge-garcia-le]

Good day. I'm trying to get my plugin loaded into a docling-serve image. I set the environment variable DOCLING_SERVE_ALLOW_EXTERNAL_PLUGINS to true as indicated in the documentation, but the app does not load it as a valid option for processing.

This is my docker_compose.yaml (with some added commands for sanity checks):

services:
  docling-serve:
    image: ghcr.io/docling-project/docling-serve-cu128:main
    container_name: docling-serve 
    entrypoint: bash
    user: "0:0"
    command: >
      -c "mkdir /app && 
          cp -r /mnt/docling-vllm-plugin /app/docling-vllm-plugin &&
          pip install /app/docling-vllm-plugin &&
          docling --show-external-plugins &&
          env | grep DOCLING &&
          docling-serve run"
    ports:
      - "5001:5001"
    environment:
      - DOCLING_SERVE_ENABLE_UI=true
      - DOCLING_SERVE_ALLOW_EXTERNAL_PLUGINS=true
      - NVIDIA_VISIBLE_DEVICES=0
    volumes:
      - ../docling-vllm-plugin:/mnt/docling-vllm-plugin:ro
    runtime: nvidia
    restart: unless-stopped

After the installation of my plugin package, here's the output:

docling-serve  |            Available OCR engines            
docling-serve  | ┏━━━━━━━━━━━━━┳━━━━━━━━━━━━━┳━━━━━━━━━━━━━━┓
docling-serve  | ┃        Name ┃ Plugin      ┃ Package      ┃
docling-serve  | ┡━━━━━━━━━━━━━╇━━━━━━━━━━━━━╇━━━━━━━━━━━━━━┩
docling-serve  | │ lazarus-ocr │ lazarus-ocr │ docling_vllm │
docling-serve  | └─────────────┴─────────────┴──────────────┘
docling-serve  | DOCLING_SERVE_ALLOW_EXTERNAL_PLUGINS=true
docling-serve  | DOCLING_SERVE_ARTIFACTS_PATH=/opt/app-root/src/.cache/docling/models
docling-serve  | DOCLING_SERVE_ENABLE_UI=true
docling-serve  | Starting production server 🚀
docling-serve  | 
docling-serve  | Server started at http://0.0.0.0:5001
docling-serve  | Documentation at http://0.0.0.0:5001/docs
docling-serve  | Scalar docs at http://0.0.0.0:5001/scalar
docling-serve  | UI at http://0.0.0.0:5001/ui
docling-serve  | 
docling-serve  | Logs:
docling-serve  | INFO:     Started server process [1]
docling-serve  | INFO:     Waiting for application startup.
docling-serve  | WARNING:docling.models.factories.base_factory:The plugin lazarus-ocr will not be loaded because Docling is being executed with allow_external_plugins=false.
docling-serve  | WARNING:docling.models.factories.base_factory:The plugin lazarus-ocr will not be loaded because Docling is being executed with allow_external_plugins=false.
docling-serve  | INFO:     Application startup complete.
docling-serve  | INFO:     Uvicorn running on http://0.0.0.0:5001 (Press CTRL+C to quit)

[dosubot]

Hi @jorge-garcia-le! I'm Dosu and I’m helping the docling-serve team.

The DOCLING_SERVE_ALLOW_EXTERNAL_PLUGINS variable is correctly mapped in the code and controls whether external plugins are loaded, but for your plugin to be discovered and used, a few requirements must be met: the environment variable must be set to true, your plugin must be installed in the container and registered as a setuptools entrypoint under the correct namespace, and it must expose the required callable attribute (like ocr_engines for OCR plugins) source.

If any of these steps are missing, the plugin won't load even if the variable is enabled. Check your container logs for warnings about skipped plugins or missing attributes—they often indicate exactly what went wrong. If you share your docker_compose.yaml and details about how your plugin is installed and registered, I can help pinpoint the issue.

To reply, just mention @dosu.

---

Share context across your team and agents. Try Dosu.

[dolfim-ibm]

@jorge-garcia-le it looks like an argument was not propagated in all places. The fix is in docling-project/docling-jobkit#50 and it should make it into a docling-serve release today.