WinError 10054: An existing connection was forcibly closed by the remote host

[Sohamactive]

Hi, I am trying to run Docling locally on Windows using a virtual environment and uv.

My basic setup appears to be working correctly:

• Python virtual environment is active
• Docling is installed successfully
• RapidOCR models download and load correctly
• The Docling layout model appears to load successfully

However, when Docling tries to download additional models from Hugging Face, the connection repeatedly fails.

The main errors are:

[WinError 10054] An existing connection was forcibly closed by the remote host

and sometimes:

httpx.RemoteProtocolError: Server disconnected without sending a response

The failures occur while downloading files from repositories such as:

docling-project/docling-models

For example, the failing files include TableFormer model artifacts.

Docling retries the requests, but eventually exits with a Hugging Face Hub download error.

I am currently running:

uv run main.py

My question is: is there a recommended way to pre-download the required Docling models or configure Docling for unreliable Hugging Face connections on Windows?

Also, are there any known issues with Hugging Face/Xet downloads causing WinError 10054 on Windows?

I would appreciate any recommended troubleshooting steps.

[kiril-buga]

Hi @Sohamactive,

Yes, Docling supports pre-downloading its model artifacts and using them locally during conversion.

From your project environment, run:

uv run docling-tools models download --output-dir .\docling-models

Then point the PDF pipeline to that directory:

from pathlib import Path

from docling.datamodel.base_models import InputFormat
from docling.datamodel.pipeline_options import PdfPipelineOptions
from docling.document_converter import DocumentConverter, PdfFormatOption

models_dir = Path(r"C:\path\to\docling-models")

options = PdfPipelineOptions(artifacts_path=models_dir)
converter = DocumentConverter(
    format_options={
        InputFormat.PDF: PdfFormatOption(pipeline_options=options)
    }
)

result = converter.convert("document.pdf")

Alternatively, leave artifacts_path unset and configure it through an environment variable:

$env:DOCLING_ARTIFACTS_PATH = "C:\path\to\docling-models"
uv run python main.py

I tested both approaches on Windows with Python 3.13 and Docling 2.126.0. A PDF containing a table converted successfully with HF_HUB_OFFLINE=1 and Python socket connections blocked, so the layout and TableFormer artifacts were loaded locally.

The initial model download still requires a working connection. If Xet is involved in the connection resets, you can try disabling it before downloading:

$env:[HF_HUB_DISABLE_XET](https://huggingface.co/docs/huggingface_hub/package_reference/environment_variables#hfhubdisablexet) = "1"
uv run docling-tools models download --output-dir .\docling-models

HF_HUB_DISABLE_XET is a documented Hugging Face option. However, the reported error alone does not prove that Xet is the cause, so it may not resolve this particular connection reset.

If the download still fails, another option is to download the artifacts from a different machine or network using the same Docling version, then copy the complete docling-models directory while preserving its structure. Additional OCR languages or optional models may need to be downloaded separately.

Docling documents the available options here: [Model prefetching and offline usage](https://docling-project.github.io/docling/usage/advanced_options/#model-prefetching-and-offline-usage).

[kiril-buga]

@Sohamactive, if this resolves your issue, please mark this reply as the answer 🙏

[ARAVIND281]

The pre-download route above answers half of this. The other half — "configure Docling for unreliable Hugging Face connections on Windows" — has a specific cause worth knowing, because the usual advice for it is now wrong.

Why it dies mid-transfer rather than at connect

WinError 10054 plus httpx.RemoteProtocolError: Server disconnected during a file body, on large artifacts like the TableFormer weights, is a transport failure, not a Docling one. Since huggingface_hub 1.32 the default download path is Xet, which is a separate Rust client (hf_xet) with its own connections and chunking rather than the plain httpx HTTPS path. That gives it a different failure surface, and on Windows it is a common drop point behind corporate DPI/TLS inspection, some AV "web shields", VPNs, and low-MTU links. A browser or a video stream is unaffected, which is why your connection otherwise looks fine.

Turn Xet off first

$env:HF_HUB_DISABLE_XET = "1"
uv run main.py

That falls back to ordinary HTTPS through httpx. It is the single highest-yield switch for this error, and it is a real, current flag — huggingface_hub/constants.py:343:

HF_HUB_DISABLE_XET: bool = _is_true(os.environ.get("HF_HUB_DISABLE_XET"))

If it gets further but still times out, the two relevant timeouts both default to 10 seconds, which is tight on a slow link:

$env:HF_HUB_DOWNLOAD_TIMEOUT = "60"
$env:HF_HUB_ETAG_TIMEOUT     = "30"

Do not reach for HF_HUB_ENABLE_HF_TRANSFER

A lot of older answers to this symptom recommend it. On huggingface_hub 2.x it does nothing — the variable is read only to warn you it is dead, constants.py:299-303:

if _is_true(os.environ.get("HF_HUB_ENABLE_HF_TRANSFER")) and not HF_XET_HIGH_PERFORMANCE:
    ...
    "The `HF_HUB_ENABLE_HF_TRANSFER` environment variable is deprecated as 'hf_transfer' is not used anymore. "

So if you have already tried it and seen no change, that is expected rather than a sign the diagnosis is wrong. Check which major version you are on first — uv run python -c "import huggingface_hub; print(huggingface_hub.__version__)" — since the advice differs either side of 2.0.

Then make the success permanent

Once docling-tools models download has succeeded, pin it shut so a later run cannot silently go back to the network on a bad day:

$env:HF_HUB_OFFLINE = "1"

Any cache miss then fails immediately with a clear offline error instead of retrying into the same disconnect.

If you want to know before you start

Transfers that die on the large files tend to be the ones worth checking in advance — total size, whether the repo is gated, and whether loading it executes code from the repo. Disclosure: I wrote hf-preflight — ignore that if you would rather not add a tool; the first three switches above are the actual fix.