Instalación

Instalar Docling en macOS

Apple Silicon (M1/M2/M3/M4) y Macs Intel con Python 3.10+. Verifica cada comando contra la documentación oficial de instalación.

Step 1

¿Qué Mac tienes?

uname -m

arm64 → Apple Silicon. Sigue las secciones 2–6. Aceleración MPS disponible.
x86_64 → Intel. Sigue las secciones 2–3 y luego la sección 7 antes de instalar extras: los wheels torch nuevos no existen para Intel.

Step 2

Configuración Python (ambos chips)

python3 --version

python3 -m venv .venv && source .venv/bin/activate

python -m pip install -U pip

Instala Python 3.10–3.12 desde python.org o con brew install python@3.12.
Macs Intel: quédate en Python ≤3.12: PyTorch 2.2.2 (último build compatible Intel) lo exige.
Usa siempre un venv:

Step 3

Instalación base

Alternativa uv: uv add docling (o uv pip install docling dentro del venv).

pip install docling

Step 4

Apple Silicon + aceleración MPS

Apple Silicon ejecuta Docling sobre el backend MPS (Metal) de PyTorch en vez de CUDA. CPU es el defecto y funciona bien; selecciona MPS cuando quieras velocidad GPU. Si imprime False, actualiza macOS + torch; algunos motores OCR son solo CPU de todos modos.

docling convert report.pdf --device mps

docling convert report.pdf --device auto

python -c "import torch; print(torch.backends.mps.is_available())"

Step 5

OcrMac: OCR nativo Apple Vision

Extra solo-macOS con el framework Apple Vision integrado: sin binario Tesseract, OCR privado en el dispositivo. Para escaneos en inglés/europeos en macOS moderno. Para CJK o escrituras complejas, compara con RapidOCR/EasyOCR en la guía OCR.

pip install "docling[ocrmac]"

docling convert scan.pdf --ocr-engine ocrmac --ocr-mode full_page

Step 6

Tesseract vía Homebrew

Solo para motores Tesseract (tesserocr, CLI). Instala el binario primero. TESSDATA_PREFIX debe terminar en barra y apuntar a la carpeta con ficheros .traineddata. En Homebrew Intel suele ser /usr/local/share/tessdata/. Persiste con export TESSDATA_PREFIX=… en tu perfil de shell.

brew install tesseract leptonica pkg-config

pip install "docling[tesserocr]"

TESSDATA_PREFIX=/opt/homebrew/share/tessdata/ docling convert scan.pdf --ocr-engine tesseract

Step 7

Macs Intel: el fijado de torch

Por qué: PyTorch 2.6.0+ no publica wheels para macOS Intel, así que un simple pip install docling puede fallar resolviendo torch. Dos soluciones soportadas (requieren Python ≤3.12). Si ya instalaste un torch roto, quítalo (pip uninstall torch torchvision) y reinstala con una línea anterior.

uv add torch==2.2.2 torchvision==0.17.2 docling

pip install "docling[mac_intel]"

Step 8

Verificación

Luego confirma acelerador y OCR por separado: --device mps en Apple Silicon, --ocr-engine ocrmac o rapidocr en una página escaneada.

docling --help

docling convert sample.pdf --to md

Step 9

Problemas comunes en macOS

torch falla en Intel — aplica el fijado de la sección 7; nada de Python 3.13+ en Intel.
TesseractNotFound / idiomas ausentes — reinstala vía Homebrew, define TESSDATA_PREFIX (barra final), ver error de instalación del paquete OCR.
Error de importación OcrMac — el extra solo funciona en macOS reciente; reinstala "docling[ocrmac]" dentro del venv.
MPS no se usa — confirma torch.backends.mps.is_available(); algunas etapas vuelven a CPU por diseño.
Errores SSL / certificados en la primera descarga — actualiza certificados Python (Install Certificates.command del instalador python.org) y reejecuta.

Step 10

FAQ de macOS

¿M-series o Intel — importa?

Sí en dos cosas: Apple Silicon puede usar --device mps y el extra OcrMac; los Intel deben fijar torch 2.2.2 y quedarse en Python ≤3.12. Lo demás es idéntico.

¿OcrMac o Tesseract?

OcrMac es cero configuración y privado (Vision en el dispositivo). Tesseract da más control de idiomas/escrituras pero requiere Homebrew + TESSDATA_PREFIX. RapidOCR es un buen punto medio solo-pip.

¿Necesito Xcode?

No. Solo las command line tools se necesitan alguna vez si pip compila algo: xcode-select --install.

¿python o python3?

Dentro del venv ambos apuntan al mismo intérprete. Fuera, macOS reserva python: usa siempre python3 -m venv y activa antes de instalar.

Verificado con Docling v2.129.0 · Última comprobación 2026-09-22 · Fuente oficial