Docling v2.129.0
🇺🇸 English EN 🇩🇪 Deutsch DE 🇯🇵 日本語 JA 🇨🇳 简体中文 ZH 🇫🇷 Français FR 🇪🇸 Español ES
GitHub Get Started
Install

Run Docling with Docker (docling-serve)

Run the official docling-serve HTTP API as a container — no Python env needed. Pick the right image (CPU vs CUDA), publish port 5001, enable the UI, and test with curl. Advanced deployment lives in the official docling-serve project.

bash — docker quickstart
$podman run -p 5001:5001 -e DOCLING_SERVE_ENABLE_UI=1 quay.io/docling-project/docling-serve
$curl -X POST http://localhost:5001/v1/convert/source
No Python env needed. The container ships everything — serve Docling over HTTP with Docker or Podman.
Images are 4–11 GB. Base/CPU ~4.4 GB, CUDA 12.8 ~11.4 GB. Pull once, reuse everywhere.
Pin CUDA tags. CUDA images have no :latest — pin explicit versions like -cu130:v1.18.0.
Decide

When Docker is (and isn’t) the answer

  • Use Docker when an app, pipeline or team needs Docling over HTTP (/v1/convert/source), reproducible deploys, or isolation from host Python.
  • Skip Docker for one-off local conversion — pip install docling plus docling convert file.pdf --to md is faster (see the install overview).
  • Images are large (4–11 GB): base/CPU ~4.4 GB, CUDA 12.8 ~11.4 GB. Pull once, reuse everywhere.
Images

Which image to pull: CPU vs CUDA

All images are published on both quay.io/docling-project/… and ghcr.io/docling-project/… for linux/amd64 (and arm64 for base/CPU). Replace docker with podman if that is your runtime.

ImageUse whenArch / size
docling-serve / docling-serve-cpuCPU-only servers, laptops, CIamd64 + arm64, ~4.4 GB
docling-serve-cu128NVIDIA GPUs on CUDA 12.8amd64, ~11.4 GB
docling-serve-cu130NVIDIA GPUs on CUDA 13.0amd64 (+arm64), size TBD
Tagging rule: base/CPU images use latest and main; CUDA images intentionally have no latest (CUDA versions deprecate with PyTorch). Always pin CUDA images explicitly, e.g. quay.io/docling-project/docling-serve-cu130:v1.18.0. A ROCm image exists but is not published (build locally); slim images without pre-downloaded weights are planned.
docker pull quay.io/docling-project/docling-serve-cpu
docker pull quay.io/docling-project/docling-serve-cu130:v1.18.0
Run

Start the server (Docker / Podman)

CPU (most common)

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

CUDA GPU (needs nvidia-container-toolkit / --gpus)

docker run --gpus all -p 5001:5001 -e DOCLING_SERVE_ENABLE_UI=1 quay.io/docling-project/docling-serve-cu130:v1.18.0

First start downloads model weights inside the image’s cache — give it time and disk. For compose-based deploys see docs/deployment.md.

Pip alternative

Alternative: pip-install docling-serve

Same server without containers — useful on a VM or for debugging:

pip install "docling-serve[ui]"
docling-serve run --enable-ui
Endpoints

Ports, docs, UI and health check

  • API base: http://127.0.0.1:5001
  • Interactive API docs (Swagger): http://127.0.0.1:5001/docs
  • Playground UI: http://127.0.0.1:5001/ui (only when DOCLING_SERVE_ENABLE_UI=1 / --enable-ui)
  • Stable conversion endpoint: POST /v1/convert/source (v1 API — see the v1 migration notes if you have old code).
/ui 404 — you forgot DOCLING_SERVE_ENABLE_UI=1 / --enable-ui.

If /docs renders, the server is healthy. If the port is busy, remap with -p 5002:5001 and use :5002 in the URLs.

API

Convert your first document via API

curl -X POST http://localhost:5001/v1/convert/source -H 'Content-Type: application/json' -d '{"sources": [{"kind": "http", "url": "https://arxiv.org/pdf/2501.17887"}]}'
curl -X 'POST' \
  'http://localhost:5001/v1/convert/source' \
  -H 'accept: application/json' \
  -H 'Content-Type: application/json' \
  -d '{
    "sources": [{"kind": "http", "url": "https://arxiv.org/pdf/2501.17887"}]
  }'

The response contains Markdown / JSON / HTML depending on your request options. Explore every runtime option in docs/usage.md and the REST reference in docling-serve docs.

Deploy

Configuration + deployment notes

  • Configure via env vars (see .env.example and docs/configuration.md), e.g. DOCLING_SERVE_ENABLE_UI=1.
  • Mount a cache volume so model weights survive restarts; set memory limits for large PDFs (see out-of-memory).
  • Put auth / TLS / rate-limits in a reverse proxy for production; the compose examples in docs/deployment.md are the starting point.
  • Pin image tags in production (:v1.18.0, not :latest) — especially CUDA tags.
Fix

Common container problems

  • Server does not start — see docling-serve does not start: port conflict, missing [ui] extra, or wrong entrypoint.
  • /ui 404 — you forgot DOCLING_SERVE_ENABLE_UI=1 / --enable-ui.
  • GPU image runs on CPU — host needs NVIDIA drivers + container toolkit and --gpus all; confirm inside with nvidia-smi.
  • Pulls :latest of a CUDA image fail — expected: CUDA images only carry explicit version tags.
  • First request slow — weights downloading; subsequent requests reuse the cache.
FAQ

Docker FAQ

Docker or pip install?
Pip (pip install docling) for local CLI conversion. Docker (docling-serve) when you need a language-agnostic HTTP API for an app or team.
Which registry — quay.io or ghcr.io?
Both mirror the same images. Use whichever is faster or allowed in your environment.
Why is there no :latest CUDA tag?
CUDA versions deprecate as PyTorch moves on, so pulling :latest could silently change your CUDA. Pin explicit versions like -cu130:v1.18.0.
Where are the API docs?
Live on your server at /docs, plus the usage, configuration and deployment guides upstream.

Advanced deployment is documented in the official docling-serve project.

Install Install overview Compare pip, Docker and platform install options. Install Linux guide Native pip install on Ubuntu, Debian and RHEL. Reference Commands Find the right CLI flags for convert and options. Help Troubleshooting Fix serve startup, out-of-memory and GPU issues.

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