[dolfim-ibm]

pip install docling-client installs the docling CLI, but the CLI crashed at startup, also for docling convert-remote --help. The CLI module builds the OCR, layout, and table engine factories at import time. This loads the built-in plugins, which import the engine modules. On docling-slim[service-client] installs these imports fail (packaging, then torch). The existing guard only covered the factory import, not the factory construction.

Changes:

• docling/cli/main.py: build the factories inside the same try/except ImportError as the factory import. Keep the error.
• docling convert and --show-external-plugins now exit with code 1 and an install hint (pip install docling, or docling convert-remote) when the local model stack is missing. Before, they showed a traceback.
• Full installs are unchanged: docling convert --help still lists the available engines.

Checklist:

• Documentation has been updated, if necessary. (Not necessary: the docs already state that service-client is enough for convert-remote.)
• Examples have been added, if necessary. (Not necessary.)
• Tests have been added, if necessary.

Review evidence:

Before: in a fresh venv with only docling-client installed, docling convert-remote --help fails with ModuleNotFoundError: No module named 'packaging' from docling/models/inference_engines/vlm/_utils.py, through get_ocr_factory() in docling/cli/main.py.

After, same venv (uv pip install ./packages/docling-client ., no torch, no packaging):

• docling convert-remote --help: exit 0, help shown.
• docling convert-remote file.pdf against an unreachable URL: reaches the service client and reports Cannot reach service.
• docling convert file.pdf: exit 1 with the install hint.
• docling --version: works.

Tests:

• Replaced test_cli_main_importable_without_local_model_stack with two tests that run the CLI in a subprocess with pypdfium2, scipy, torch, and packaging blocked: convert-remote --help must succeed, and convert must exit 1 with the install hint. The subprocess keeps the blocked and re-imported modules out of the other tests (an in-process version polluted tests/test_cli_remote.py). Both tests fail without the fix.
• uv run pytest tests/test_cli.py tests/test_cli_remote.py tests/test_cli_tools.py: 139 passed.
• make validate: passed.

[github-actions]

✅ DCO Check Passed

Thanks @dolfim-ibm, all your commits are properly signed off. 🎉

[mergify]

Merge Protections

🟢 Merge protection satisfied — ready to merge.

Show 1 satisfied protection

🟢 Enforce conventional commit

Make sure that we follow https://www.conventionalcommits.org/en/v1.0.0/

• title ~= ^(fix|feat|docs|style|refactor|perf|test|build|ci|chore|revert)(?:\(.+\))?(!)?:

[github-actions]

AI triage (advisory)

Checked commit c9483fe239. The analysis read the diff only. It did not run code from this pull request.

This pull request prevents import errors when users run docling convert-remote without local model dependencies. It also shows a clear error message when local conversion commands run without required packages.

Topic labels added: bug, CLI.

CI safety: no concern found. A maintainer must still approve CI.

1 related pull request(s) in the same code

PR	State	Signal	Assessment
#4676	open	changes the same code	related: PR 4676 modifies external plugin discovery in the CLI, while this pull request prevents startup import errors when optional model dependencies are absent.

_{The ai:* labels are advisory. They do not approve CI and they do not add tests:full. A new push runs this check again.}

[github-actions]

AI first review (advisory): no blocker found

This review covers the full diff at c9483fe239. It read the code and did not run it.

I found no defect that decides the merge. In docling/cli/main.py the import guard now also covers building the OCR, layout, and table factories, which is where the packaging and torch imports fail. convert and --show-external-plugins exit with code 1 and an install hint when the stack is missing. Two things are not covered: the old module-level names ocr_factory_internal, layout_factory_internal, and table_structure_factory_internal are gone, and nothing else in the repo uses them. The --show-external-plugins exit path has no test. This second gap is minor.

_{A maintainer makes the merge decision. This review never approves the pull request.}

[codecov]

Codecov Report

❌ Patch coverage is 43.75000% with 9 lines in your changes missing coverage. Please review.

Files with missing lines	Patch %	Lines
docling/cli/main.py	43.75%	8 Missing and 1 partial ⚠️

📢 Thoughts on this report? Let us know!

[PeterStaar-IBM]

lgtm!