The command uv add docling does two distinct things simultaneously: it executes an installation via uv, and it targets a specific, popular open-source AI package called docling.
Running this command executes the following actions:
#### 1. What uv does behind the scenes
Because you are using uv's modern project management tool, this single command handles the entire dependency lifecycle:
- Resolves Dependencies: It looks up docling on PyPI, checks all the sub-packages it requires, and resolves any version conflicts in milliseconds.
- Updates your pyproject.toml: It automatically writes docling into your project's configuration file under the dependencies list.
- Updates your uv.lock file: It locks down the exact cryptographic versions of docling and its sub-dependencies to ensure reproducibility across different machines.
- Installs into .venv: It downloads the wheels and installs them directly into your project's local virtual environment (creating the environment first if it doesn't already exist).
Initially, installing Docling failed due to deep dependency conflicts rooted in the Python environment version. The system was running Python 3.14 (an experimental/pre-release version).
```bash
Plaintext
Configuring project 137_Docing-Test...
× No solution found when resolving dependencies:
╰─▶ Because docling v2.14.0 depends on numpy >=1.26.4 and <2.0.0...
and no versions of numpy match >=1.26.4,<2.0.0becausepython_version>= "3.14"
```
### The Root Cause
Core scientific computing libraries utilized by Docling—specifically numpy (restricted to <2.0.0byunderlyingmodels)andscipy—didnotyethavepre-compiledbinarywheelsavailableforPython3.14.BuildingthemfromsourcefailedduetostrictC-extensionrequirementsthatwereincompatiblewiththeunreleasedPythonruntime.
The Fix
We utilized the uv package manager to explicitly pin and enforce a stable, production-grade Python runtime environment without altering your global system configuration:
```Bash
uv init --python 3.12
```
This cleanly isolated the project to Python 3.12, instantly unlocking access to fully compiled, highly optimized binary wheels for numpy, scipy, torch, and onnxruntime.
## 2. The Metal Performance Shaders (MPS) float64 Crash
The Error
Once the environment was stable, running the document converter triggered a hard runtime crash during the Stage layout phase when processing the first page:
```zsh
TypeError: Cannot convert a MPS Tensor to float64 dtype as the MPS framework doesn't support float64. Please use float32 instead.
Stage layout failed for run 1: Cannot convert a MPS Tensor to float64 dtype as the MPS framework doesn't support float64.
```
### The Root Cause
Docling uses IBM's rt_detr_v2 (Real-Time DEtection TRansformer) vision model for document layout and element segmentation.
- By default, PyTorch detected the Apple Silicon M3 GPU hardware and automatically routed tensors to the MPS (Metal Performance Shaders) backend.
- Deep inside the Hugging Face transformers layout code, the model initialized a positional embedding layer using high-precision 64-bit floating-point numbers:
ω= torch.arange(pos_dim,dtype=torch.float64)
----------------------------------------
pos_dim
- Because Apple's Metal shading language natively operates on 16-bit (half) and 32-bit (float) precisions to maximize unified memory bandwidth, the MPS framework physically lacks hardware support for float64 operations, causing the runtime execution to immediately fault.
## The Fix
Standard environment variables (like device="cpu" passing configurations or CUDA_VISIBLE_DEVICES="") failed because the model's internal source code bypassed them to poll the hardware directly.
We resolved this by implementing a pre-emptive monkeypatch at the absolute top of main.py before any heavy machine learning frameworks could execute their initialization loops:
```Python
import torch
# Intercept and mock PyTorch's hardware discovery backend completely
torch.backends.mps.is_available = lambda: False
torch.backends.mps.is_built = lambda: False
# Force standard CPU allocation fallback
torch.set_default_device("cpu")
```
## The Result
By blinding PyTorch to the presence of the local Metal architecture, the layout engine cleanly and safely fell back to the standard CPU processing path. This bypassed the precision limitations completely and achieved a flawless, structurally complete 9-page Markdown compilation in 36.44 seconds.
