Guía

Instalar Docling

La ruta completa y verificada desde cero hasta tu primera conversión — configuración Python, pip frente a uv, entornos virtuales, cada extra opcional, builds PyTorch CPU / CUDA / MPS, paquetes de sistema Tesseract, descargas de modelos, verificación y soluciones por SO. Funciona en macOS, Linux y Windows (x86_64 y arm64).

WindowsWindowsuv, pip, herramientas de compilación C++ y ruta WSL2 + CUDA.macOSmacOSApple Silicon e Intel, aceleración MPS, OcrMac, Tesseract vía Homebrew.LinuxLinuxUbuntu/Debian/RHEL, wheels solo-CPU, CUDA 12.8/13.0, apt y dnf.ContainerDockerServir la API HTTP como contenedor: imágenes CPU frente a CUDA, puertos, UI, prueba curl.

Step 1

¿Qué ruta de instalación elegir?

Situación	Empieza aquí	Por qué
Convertir PDF en local	`pip install docling`	Paquete base; sin Docker ni servidor.
En Windows con errores de compilador	Guía Windows + `uv add docling`	uv resuelve wheels precompiladas y evita MSVC.
Necesitas una API HTTP para una app	Guía Docker / docling-serve	Contenedor oficial con `/v1/convert/source`, `/docs`, `/ui`.
Necesitas velocidad GPU en Linux	Guía Linux	torch con CUDA + `--device cuda`.
En un Mac	Guía macOS	Apple Silicon usa MPS; Intel requiere torch fijado.
PDF escaneados / OCR	Tabla de extras + Guía OCR	Elige RapidOCR, EasyOCR, Tesseract u OcrMac.

Step 2

Requisitos (todas las plataformas)

Si la salida es inferior a 3.10, instala primero un Python más nuevo — todo lo siguiente asume 3.10+:

python --version && pip --version

Python 3.10 o superior, 64 bits. Python 3.9 dejó de ser compatible en Docling 2.70.0. Con versiones muy nuevas, revisa el historial de PyPI por si aún no hay wheel.
pip 23+ o Astral uv. uv es más rápido y evita la mayoría de problemas de compilación en Windows.
Unos 2–4 GB libres para modelos en la primera ejecución (layout, tablas y OCR).
Internet funcional en la primera ejecución para descargar modelos (máquinas sin conexión: ver caché de modelos).
Opcional: binario de sistema Tesseract (solo motores Tesseract), drivers CUDA (solo GPU NVIDIA), Docker (solo docling-serve).

Step 3

Crear un entorno aislado (recomendado)

Opción A — venv + pip (en todas partes): En PowerShell de Windows usa .venv\Scripts\Activate.ps1 en lugar de la línea source.

python -m venv .venv

source .venv/bin/activate

python -m pip install -U pip

Docling arrastra PyTorch, ONNX y librerías OCR. Nunca lo instales en el Python del sistema: un solo torch o numpy en conflicto puede romper otras herramientas.

Opción B — uv (la más rápida, la mejor en Windows):

uv venv --python 3.12

uv add docling

Step 4

Instalación rápida: pip frente a uv

Estándar (pip): Ambas instalan el mismo paquete desde PyPI en macOS, Linux y Windows (x86_64 + arm64). Las instrucciones oficiales completas están en la documentación oficial de instalación.

pip install docling

uv add docling

Con uv (resuelve wheels precompiladas y evita las herramientas de compilación C++): ver el comando anterior.

Step 5

Todos los extras opcionales, explicados

El paquete base cubre la conversión estándar. Todo lo que requiere dependencias pesadas es un extra: pip install "docling[NOMBRE]" (combinables con comas: "docling[rapidocr,vlm]").

Extra	Qué añade	Instalación
rapidocr	Motor RapidOCR (backend ONNX Runtime): el OCR multiplataforma más sencillo	`pip install "docling[rapidocr]"`
easyocr	Motor EasyOCR: instalación solo Python, buena cobertura multilingüe	`pip install "docling[easyocr]"`
tesserocr	Enlace rápido a Tesseract (requiere antes el Tesseract del sistema, ver abajo)	`pip install "docling[tesserocr]"`
ocrmac	OCR Apple Vision: solo macOS	`pip install "docling[ocrmac]"`
vlm	Pipeline de modelos visión-lenguaje (p. ej. Granite Docling)	`pip install "docling[vlm]"`
asr	Pipeline de reconocimiento de voz (Whisper)	`pip install "docling[asr]"`
htmlrender	Renderizado de páginas HTML para el backend HTML	`pip install "docling[htmlrender]"`
feat-ocr-nemotron	NVIDIA Nemotron OCR: solo Linux x86_64 + Python 3.12 + CUDA 13.x	`pip install "docling[feat-ocr-nemotron]" --extra-index-url https://download.pytorch.org/whl/cu130 --index-strategy unsafe-best-match`
mac_intel	torch fijado para Macs Intel (PyTorch ≥2.6 sin wheels Intel)	`pip install "docling[mac_intel]"`

Sobre el OCR: RapidOCR y EasyOCR se instalan solo con pip; las variantes Tesseract requieren antes el binario del sistema. Compara motores en la guía OCR.

Step 6

Builds PyTorch: solo-CPU, CUDA, MPS, Macs Intel

Los modelos Docling corren sobre PyTorch. El wheel por defecto sirve a casi todos; tres casos necesitan un build especial:

pip install docling --extra-index-url https://download.pytorch.org/whl/cpu

uv add torch==2.2.2 torchvision==0.17.2 docling

pip install "docling[mac_intel]"

Servidores Linux solo-CPU: instala el build CPU pequeño en vez del wheel CUDA grande (ver comando abajo).
GPU NVIDIA en Linux/Windows: instala un torch con CUDA para tu versión de CUDA y selecciónalo con --device cuda. En Windows, WSL2 es la vía CUDA más simple — detalles en la guía Windows.
macOS Intel (x86_64): PyTorch 2.6.0+ no publica wheels Intel. Fija el último build válido y quédate en Python ≤3.12.
Apple Silicon: funciona tal cual; selecciona el backend MPS con --device mps cuando lo necesites (ver guía macOS).

Step 7

Paquetes de sistema Tesseract + TESSDATA_PREFIX

Solo necesario si eliges un motor Tesseract. Instala el binario con el gestor de paquetes del SO antes del extra pip, y apunta TESSDATA_PREFIX a los datos de idioma (con barra final):

SO	Instalación	Ejemplo TESSDATA_PREFIX
macOS (Homebrew)	`brew install tesseract leptonica pkg-config`	`/opt/homebrew/share/tessdata/`
Ubuntu / Debian	`sudo apt-get install tesseract-ocr tesseract-ocr-eng libtesseract-dev libleptonica-dev pkg-config`	desde `dpkg -L tesseract-ocr-eng \| grep tessdata$`
RHEL / Fedora	`sudo dnf install tesseract tesseract-devel tesseract-langpack-eng tesseract-osd leptonica-devel`	`/usr/share/tesseract/tessdata/`
Windows	Instala la build UB Mannheim, añádela al PATH	apunta `TESSDATA_PREFIX` a su carpeta `tessdata\\`

Si tesserocr no compila: pip uninstall tesserocr y luego pip install --no-binary :all: tesserocr.

Step 8

Verifica tu instalación

Ejecuta estas tres comprobaciones en orden — cada una aísla una capa distinta de fallo. Usa primero un PDF digital (texto) pequeño para dejar fuera OCR y GPU. Luego prueba --to json, --to html y --ocr-engine rapidocr. Si algo falla, consulta sección 11 o la resolución de problemas.

docling --help

python -c "import docling; print(docling.__version__)"

docling convert sample.pdf --to md

Step 9

La primera ejecución descarga modelos — prevéelo

docling-tools models download --all

La primera conversión descarga modelos de layout, tablas y OCR: lenta una vez, rápida después.
Mantén una conexión estable en esa primera ejecución; una descarga parcial deja una caché rota — basta reejecutar.
Predescarga todo:
Apunta la caché a un disco escribible con DOCLING_CACHE_DIR si la ubicación por defecto es de solo lectura o pequeña.
Máquinas aisladas: descarga en un equipo conectado y copia el directorio de caché.

Step 10

Actualizar, fijar y desinstalar

Fija una versión exacta en producción (requirements.txt, lockfile o tag de contenedor) para que ningún cambio de modelo o CLI te sorprenda. Este sitio está verificado contra la versión de la insignia inferior.

pip install -U docling

pip install "docling==2.129.0"

pip uninstall docling

Step 11

Corrige los 5 fallos de instalación más comunes

Microsoft Visual C++ 14.0 is required (Windows): cambia a uv add docling por wheels precompiladas, o instala Build Tools con winget install Microsoft.VisualStudio.2022.BuildTools y la carga C++. Detalles en la guía Windows y resolución de problemas.
Errores de versión Python: crea un entorno nuevo con 3.10–3.12 (uv venv --python 3.12). Python 3.9 no compatible desde 2.70.0.
Falla el extra OCR: usa rapidocr o easyocr (solo pip); para Tesseract instala antes el binario del sistema + TESSDATA_PREFIX.
GPU ignorada (corre en CPU): confirma que torch.cuda.is_available() devuelva True, instala un torch CUDA y pasa --device cuda (MPS en Apple Silicon).
Sin memoria / muy lento: convierte de uno en uno, baja --num-threads y añade --no-ocr para PDF digitales.

Step 12

Preguntas frecuentes de instalación

¿Qué versión Python necesita Docling?

Python 3.10 o superior, 64 bits. El soporte de 3.9 terminó en 2.70.0. Si estás en 3.9 o 32 bits, crea un entorno nuevo con 3.10–3.12 y reinstala.

¿pip o uv — cuál uso?

Ambos instalan lo mismo. uv resuelve wheels precompiladas con más agresividad, evita el error del compilador MSVC en Windows y es más rápido. Con uv: uv add docling; si no, pip install docling basta.

¿Necesito Docker?

No para conversión local — basta el paquete Python. Docker (o Podman) solo hace falta para docling-serve, el servidor API HTTP como contenedor. Ver la guía Docker.

¿Necesito GPU?

No. Todo corre en CPU. Una GPU CUDA (Linux/Windows) o MPS (Apple Silicon) acelera notablemente layout, tablas y OCR en documentos largos.

¿Por qué la primera conversión es tan lenta?

Docling descarga sus modelos en el primer uso. Mantén la conexión en esa ejecución o predescarga con docling-tools models download --all. Después reutiliza la caché.

¿Qué motor OCR se instala más fácil?

RapidOCR (docling[rapidocr]) o EasyOCR (docling[easyocr]): ambos solo pip. Tesseract es excelente pero requiere binario del sistema más datos; OcrMac solo funciona en macOS.

¿Puedo instalar Docling sin conexión?

Sí, con preparación: instala wheels más la caché de modelos en una máquina conectada y transfiere ambas. Apunta DOCLING_CACHE_DIR a la caché copiada en el equipo aislado.

¿Cómo uso Docling con frameworks RAG?

Instala Docling, añade el adaptador (LangChain, LlamaIndex, Haystack). Convierte a Markdown o JSON, trocea e indexa. Ver la guía RAG y los ejemplos.

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