Bad / corrupted paths for images under Microsoft Windows for `--image-export-mode referenced`

[clach04]

Bug

Using command line tool docling to convert (say) PDF to; markdown, html, or html_split_page results in "bad" paths for Windows. Either '' or URL encoded to %5C.

Looks like this is actually in docling-core https://github.com/docling-project/docling-core/blob/2a78701b3fcee511a3b0d5a6acdf82851d70cfe2/docling_core/types/doc/document.py#L5924 or the rendering https://github.com/docling-project/docling-core/blob/2a78701b3fcee511a3b0d5a6acdf82851d70cfe2/docling_core/transforms/serializer/html.py#L1200 - I'm not clear which

Steps to reproduce

1. Needs a windows environment :-)

2. use sample doc and convert:

   docling --no-ocr --to html --image-export-mode referenced  tests\data\pdf\picture_classification.pdf
   

alternatively use Markdown or html.

Seeing

<img src="picture_classification_artifacts%5Cimage_000000_62208f20a02fafcd90d0c99fe51507939b766fd92a2e358cf1d642eee8093a7e.png">

should be

<img src="picture_classification_artifacts/image_000000_62208f20a02fafcd90d0c99fe51507939b766fd92a2e358cf1d642eee8093a7e.png">

%5C is \

trying markdown

docling --no-ocr --to md --image-export-mode referenced  tests\data\pdf\picture_classification.pdf

seems fine but not ideal

![Image](picture_classification_artifacts\image_000000_62208f20a02fafcd90d0c99fe51507939b766fd92a2e358cf1d642eee8093a7e.png)

so using windows path, I believe it is reasonable to use '/' in a Markdown file under Windows.

Docling version

Docling version: 2.102.1
Docling Core version: 2.82.0
Docling IBM Models version: 3.13.3
Docling Parse version: 6.2.0
Python: cpython-312 (3.12.5)
Platform: Windows-11-10.0.22631-SP0

Python version

Python 3.12.5

[dosubot]

Thanks for the detailed report. I can confirm this is a real bug in docling-core. The root cause is in the _with_pictures_refs() method in document.py where image paths are constructed using Python's pathlib.Path, which uses OS-native separators (backslash on Windows). The resulting path is stored directly in item.image.uri without normalization:

loc_path = image_dir / f"image_{img_count:06}_{hexhash}.png"
# ...
obj_path = relative_path(reference_path.resolve(), loc_path.resolve())
item.image.uri = Path(obj_path)

The relative_path() utility returns a Path object with OS-specific separators. Then in the HTML serializer, urllib.parse.quote() URL-encodes the backslash to %5C:

img_text = f'<img src="{quote(str(item.image.uri))}">'

The fix would be to call .as_posix() on the path before storing it in image.uri, ensuring forward slashes regardless of platform. Something like:

item.image.uri = Path(obj_path).as_posix()

This would fix both the HTML (%5C) and Markdown (\) cases you reported. The issue lives in docling-core rather than docling itself, so you're right that the fix belongs in https://github.com/docling-project/docling-core.

To reply, just mention @dosu.

---

Share context across your team and agents. Try Dosu.

[clach04]

Confirmed, hacking my site-packages copy fixes this:

C:\code\py\docling\.venv\Lib\site-packages\docling_core\types\doc\document.py

...
    def _with_pictures_refs(
...
                            elif item.image is not None:
                                #item.image.uri = Path(obj_path)
                                item.image.uri = Path(obj_path).as_posix()  # clach04 hack from https://github.com/docling-project/docling/issues/3617#issuecomment-4712114000
...

[clach04]

Posted PR docling-project/docling-core#641

[sriharan0804]

Hi @clach04 , I noticed this PR addresses #3617 but the checks are currently failing. I’d be happy to help debug the failing checks or submit a small follow-up if needed. Please let me know if you’re still working on this.

[clach04]

Thanks for the offer @sriharan0804 , I somehow missed the note about confirmation, which I just resolved. I think docling-project/docling-core#641 is now waiting for a reviewer based on the current messages/status. This change works fine on my machines for small scans.

This has fallen lower on my TODO list as docling parse doesn't seem suitable for production usage yet with more than 70 scanned pages on a modest machine with 64Gb of ram and 8Gb VRAM . I've been playing with Marker. The docs are much better with Docling but Marker actually works for the real scans I have (even on a 4Gb VRAM).