Install

Install Docling on Linux

Ubuntu / Debian, RHEL / Fedora and WSL2 with Python 3.10+. Pick the CPU or CUDA path first — it decides which PyTorch wheel you install. Verify each command against the official installation docs.

bash — quickstart

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

$python -c "import torch; print(torch.cuda.is_available())"

CPU vs CUDA first. CPU servers use the small wheel; NVIDIA machines use a CUDA torch.

Never sudo pip. Use a venv to avoid permission errors.

Pre-download models. First run fetches models — keep the connection alive.

Prerequisites

Requirements + distro packages

python3 --version

Need 3.10+. Then install venv + build basics:

Ubuntu / Debian

sudo apt-get update && sudo apt-get install -y python3 python3-venv python3-pip

RHEL / Fedora

sudo dnf install -y python3 python3-pip

python3 -m venv .venv && source .venv/bin/activate && pip install -U pip

Recommended for servers

CPU-only install (servers, containers)

The default torch wheel bundles CUDA libraries (~2 GB+). On CPU-only machines install the small CPU build instead:

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

This is the right choice for CI runners, small VPS instances, and CPU Docker images. Speed is fully usable for text PDFs; scanned/OCR-heavy work is just slower than on GPU.

Installing the default wheel on a CPU-only box pulls a huge (~2 GB+) CUDA bundle. Use the --extra-index-url …/cpu line to keep the install small.

NVIDIA GPU

CUDA / GPU install (NVIDIA)

Install the NVIDIA driver + CUDA toolkit matching your GPU (check nvidia-smi).
Install a CUDA-enabled torch from pytorch.org for your CUDA version (12.8 / 13.0), then Docling — or let pip resolve CUDA torch from the default index, then select the device:

pip install docling

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

docling convert report.pdf --device cuda

torch.cuda.is_available() must print True — if not, fix drivers/torch before tuning Docling flags. For GPU OCR add the ONNX Runtime CUDA path: pip install "docling[onnxruntime]" and confirm CUDAExecutionProvider appears in ort.get_available_providers(). Full tuning (batch sizes, VLM servers) is in the official GPU guide.

Reproducible envs

uv CPU-index configuration

uv users pin torch to the CPU index in pyproject.toml so every team member and CI run gets the small wheel:

[[tool.uv.index]]
name = "pytorch-cpu"
url = "https://download.pytorch.org/whl/cpu"
explicit = true

[tool.uv.sources]
torch = [{ index = "pytorch-cpu" }]

uv add docling

System dependency

Tesseract system packages

Only for Tesseract engines. Install the binary before the pip extra:

Debian / Ubuntu

sudo apt-get install -y tesseract-ocr tesseract-ocr-eng libtesseract-dev libleptonica-dev pkg-config

RHEL / Fedora

sudo dnf install -y tesseract tesseract-devel tesseract-langpack-eng tesseract-osd leptonica-devel

pip install "docling[tesserocr]"

Set TESSDATA_PREFIX to the folder containing .traineddata (must end with /). Find it with dpkg -L tesseract-ocr-eng | grep tessdata$ on Debian or use /usr/share/tesseract/tessdata/ on RHEL. If tesserocr fails to build: pip uninstall tesserocr then pip install --no-binary :all: tesserocr.

Set TESSDATA_PREFIX to the folder containing .traineddata and include the trailing /, or Tesseract engines will not find their language data.

Optional

OCR + pipeline extras on Linux

Need	Install	Constraint
RapidOCR (recommended default)	`pip install "docling[rapidocr]"`	None — pip-only.
EasyOCR	`pip install "docling[easyocr]"`	None — pip-only.
VLM pipeline	`pip install "docling[vlm]"`	GPU strongly recommended.
ASR (audio)	`pip install "docling[asr]"`	None.
Nemotron OCR	`pip install "docling[feat-ocr-nemotron]" --extra-index-url https://download.pytorch.org/whl/cu130 --index-strategy unsafe-best-match`	Linux x86_64 + Python 3.12 + CUDA 13.x only.

Confirm it works

Verify (CPU vs GPU)

First run downloads models — keep the connection alive or pre-fetch with docling-tools models download --all. Use --device cpu to force CPU for comparison, --device cuda for NVIDIA.

docling --help

docling convert sample.pdf --to md

docling convert sample.pdf --device auto --to md

Alternative

Prefer containers? Use docling-serve

For an HTTP API instead of the CLI, run the official container (CPU image shown) — full reference in the Docker page:

podman run -p 5001:5001 -e DOCLING_SERVE_ENABLE_UI=1 quay.io/docling-project/docling-serve-cpu

Fix fast

Common Linux problems

GPU ignored — see GPU not used: wrong torch build or missing drivers.
Out of memory — see out of memory: convert one file at a time, lower --num-threads, add --no-ocr for digital PDFs.
Huge install size — you pulled CUDA torch on a CPU box; reinstall with the --extra-index-url …/cpu line.
Tesseract missing languages — install the tesseract-ocr-lang packages and export TESSDATA_PREFIX.
Permission errors — use a venv; never sudo pip install.

Answers

Linux FAQ

CPU or CUDA torch?

CPU-only servers and CI: the /whl/cpu index (small, fast download). Any NVIDIA machine where you want speed: a CUDA-enabled torch plus --device cuda.

Which CUDA version?

Match your driver’s CUDA (check nvidia-smi). Docling-serve publishes -cu128 and -cu130 images; for pip installs pick the torch index pytorch.org recommends for that CUDA.

Can I use Nemotron OCR?

Only on Linux x86_64 with Python 3.12 and CUDA 13.x, installed with the feat-ocr-nemotron extra plus the cu130 index and unsafe-best-match strategy.

apt or pip for Tesseract?

Both: the binary and dev libraries come from apt/dnf, the Python binding (tesserocr) from pip. Set TESSDATA_PREFIX afterwards.

InstallInstall overviewCompare all platforms and pick the right path. ContainersDocker imagesRun docling-serve CPU / GPU via Podman or Docker. CLICommand finderFind convert, batch and export commands. FixTroubleshootingSolve GPU, memory and OCR errors.

Verified with Docling v2.129.0 · Last checked 2026-09-22 · Official source