Using models from local HF hub cache

[QLutz]

I'd like Docling to use models locally stored in my HF hub cache. These models may include:

• ds4sd/docling-layout-heron for layout recognition
• ds4sd/docling-models for table parsing
• ds4sd/Document figure classifier for figure classification
• HuggingFaceTB/SmolVLM-256M-Instruct for image captioning
• ds4sd/CodeFormulaV2 for code parsing

Is there an envvar I should set to use these models without explicitly setting each of their paths in my code ?

[dosubot[bot]]

You can set the environment variable DOCLING_SERVE_ARTIFACTS_PATH to the directory where your models are stored locally (such as your Hugging Face hub cache or a mounted folder with pre-downloaded models). Docling Serve will then load models from that directory without requiring you to specify each model path in your code. Just make sure all required models are present in that directory—if any are missing, Docling Serve will raise a runtime error instead of downloading them automatically. More details are in the official documentation here.

To reply, just mention @dosu.

---

^{How did I do? Good | Irrelevant | Incorrect | Verbose | Hallucination | Report 🐛 | Other}    

[QLutz]

This does not seem to work as an error is raised when looking for the layout model: Docling is looking for the safetensors at the root of the cache folder.

[dosubot[bot]]

Docling Serve expects models to be organized in a specific directory structure, not directly in the root of the Hugging Face cache. When you set DOCLING_SERVE_ARTIFACTS_PATH to the cache root, Docling looks for model files (like safetensors) at the root, which causes the error you’re seeing.

The recommended approach is to use the docling-tools CLI to download models into a dedicated folder (for example, run docling-tools models download --all -o models), then set DOCLING_SERVE_ARTIFACTS_PATH to that folder. Each model should be in its own subdirectory (e.g., models/ds4sd--docling-layout-heron/), and each must include a config.json with a model_type key. Docling does not currently support traversing the Hugging Face cache structure automatically—models must be in the expected layout for Docling to find them without specifying each path individually [source] [source].

If you want to automate copying from your HF cache, you’ll need to script moving or symlinking the relevant subdirectories into a new folder that matches Docling’s expectations.

To reply, just mention @dosu.

---

^{How did I do? Good | Irrelevant | Incorrect | Verbose | Hallucination | Report 🐛 | Other}    

[QLutz]

Could you détail the specific structure that Docling expects ?

[dosubot[bot]]

Docling expects your models directory (the one you set with DOCLING_SERVE_ARTIFACTS_PATH) to look like this:

models/
  ds4sd--docling-layout-heron/
    config.json
    model.safetensors
    ...other model files...
  ds4sd--docling-models/
    config.json
    ...model files...
  ds4sd--DocumentFigureClassifier/
    config.json
    ...model files...
  HuggingFaceTB--SmolVLM-256M-Instruct/
    config.json
    ...model files...
  ds4sd--CodeFormulaV2/
    config.json
    ...model files...

Each model must be in its own subdirectory (named after the model, with -- instead of /), and each must include a config.json file with at least a "model_type" key. All model weights (like .safetensors, .bin, etc.) and any other required files should be inside the same subdirectory. Docling does not support the Hugging Face cache structure directly—it expects this flat, per-model folder layout under the path you specify. If you use docling-tools models download --all -o models, it will create this structure for you automatically. If a required model or its config is missing, Docling will raise a runtime error and tell you which one it needs.
Reference

To reply, just mention @dosu.

---

^{How did I do? Good | Irrelevant | Incorrect | Verbose | Hallucination | Report 🐛 | Other}