Docling Serve Configuration: Every DOCLING_SERVE_* Environment Variable

Docling Serve is configured almost entirely through environment variables prefixed DOCLING_SERVE_. There are close to 180 of them in the current release, and the published configuration doc lists roughly half. This page lists all of them.

Every name, type and default below is read from docling_serve/settings.py at the v1.32.0 tag, released September 1, 2026, with the engine settings cross-checked against docling-jobkit 3.5.0, which is the version that release pins. Where the doc and the source disagree, the source wins and the difference is called out.

This is the reference companion to two guides: Docling Serve: self-hosting the Docling REST API covers the endpoints, async jobs and timeouts, and Docling Docker: CPU/GPU images, Compose and model cache covers the container side. If you only want the Compose file, skip to it.

How Docling Serve reads configuration

The settings object is a pydantic-settings model with env_prefix="DOCLING_SERVE_". A field named max_sync_wait is therefore set by DOCLING_SERVE_MAX_SYNC_WAIT. Five things about the loader are worth knowing before the tables:

1. Precedence is env var, then .env file, then config file, then defaults. The settings_customise_sources override in the source orders them init > env > dotenv > yaml_config > file_secret. A .env in the working directory is read automatically. DOCLING_SERVE_CONFIG_FILE points at a YAML or JSON file whose keys are the field names without the prefix (max_sync_wait: 300), and env vars override anything in it.
2. Typos are silent. The model is declared with extra="allow", so DOCLING_SERVE_MAX_SYNC_WAIT_SECONDS does not raise; it is stored and ignored. Check /version or your logs rather than assuming a setting took.
3. Empty string means unset. env_parse_none_str="" maps "" to None for optional fields. That is why -e DOCLING_SERVE_ARTIFACTS_PATH="" clears the artifacts path that the container image sets, which re-enables model auto-download.
4. Lists are JSON unless a validator says otherwise. DOCLING_SERVE_CORS_ORIGINS must be a JSON array: '["https://app.example.com"]'. The ALLOWED_* allow-lists and ALLOWED_IMAGE_EXPORT_MODES have a validator that also accepts a comma-separated string. The CUSTOM_*_PRESETS settings must be JSON objects; a value that fails to parse becomes {} rather than an error.
5. Booleans take the usual pydantic spellings. true, false, 1, 0, yes, no, on, off, case-insensitive.

The CLI exposes only --artifacts-path and --enable-ui at the app level. As of v1.32.0 the run command re-exports both as environment variables before starting Uvicorn, so they survive --reload and multi-worker spawns; every other app setting has no CLI flag at all. Configure through the environment and you never hit the gap.

Types below use Python notation from the source: str, int, float, bool, Path, list[str], dict. Optional[X] means unset by default.

Web server (UVICORN_*)

These are not DOCLING_SERVE_ variables but they live in the same settings module and you will need at least one of them.

Because the default bind is 0.0.0.0 and authentication is off, publish the container port to loopback (-p 127.0.0.1:5001:5001) unless a proxy with TLS sits in front.

Paths, models and startup

OPTIONS_CACHE_SIZE is the one people miss. Two clients that differ only in table_mode are two cache entries, and each holds a full model set in memory. Size it to the number of option combinations you actually serve, and watch memory when you raise it.

Request limits and policy

These are enforced server-side and return 422 when violated.

MAX_FILE_SIZE and MAX_NUM_PAGES are unbounded by default. Set both before you accept untrusted uploads.

Sync endpoints and results

Raising MAX_SYNC_WAIT is the last resort, not the first. The sync handler enqueues the task and polls it; on timeout it raises 504 and leaves the conversion running, with a TODO: abort task! at that point in the source. The Serve guide’s timeout section walks through the order of fixes.

Security and exposure

There is no per-tenant credential, rate limit or quota. If you need any of that, it goes in a proxy in front of Docling Serve.

Logging

The header propagation is the cheapest request tracing available here, and it works under the local engine without any extra setup.

Pipeline batching

These flow straight into docling-jobkit’s DoclingConverterManagerConfig. They are all unset by default, which means the library’s own defaults apply.

Two Docling library variables belong next to them, because they decide how many CPU threads and which device the conversion uses:

Async engine

DOCLING_SERVE_ENG_KIND picks which engine runs the async endpoints and, under local, the sync ones too.

Local engine (ENG_LOC_*)

SHARE_MODELS=true is the easiest memory saving available. The default allocates a full model graph per worker, so two workers cost roughly twice the memory of one. Pending tasks under local live in the process and are lost on restart.

RQ engine (ENG_RQ_*)

Set ENG_KIND=rq on the API containers and the workers alike, run workers with docling-serve rq-worker, and the API stops converting entirely. The Redis URL is validated at startup; the process refuses to boot without it.

The gate settings exist so that a burst of status polls cannot exhaust the Redis pool and starve the background listener; the four GATE_* values and the two ZOMBIE_REAPER_* values are undocumented upstream and were read from the jobkit RQOrchestratorConfig. Leave them alone unless you see gate-timeout errors in the logs.

Ray engine (ENG_RAY_*)

The Ray engine requires both a Redis URL and a Ray address, and refuses to start without either. It is also the largest settings surface in the module and is not covered by the upstream configuration doc at all. Defaults below are Docling Serve’s own, which in a few places differ from jobkit’s.

Connection and storage:

Fairness and per-tenant limits. Tenants are identified by a request header:

Autoscaling and resources:

Page-slice fan-out and coordinators. With fan-out enabled, a large PDF is split into page ranges converted in parallel and reassembled by a coordinator replica:

Retries, timeouts and health:

If you do not already operate Ray, run RQ. The Ray engine is designed for multi-tenant clusters and its defaults assume one.

Artifact storage

Enables the PresignedUrlTarget, where the server writes converted output to object storage and returns a presigned URL instead of the document body. Off by default.

With the Azure backend, the connection string, container and account name are all checked at startup and a missing one raises with the variable names in the message.

Model presets and allow-lists

These decide which models a client may ask for and what "default" means. They pass through to the converter manager unchanged. The pattern repeats for each model family: a DEFAULT_* preset, an optional ALLOWED_* list that restricts clients to a subset, a CUSTOM_* JSON object that registers new presets, and an ALLOW_CUSTOM_*_CONFIG flag that lets clients send a fully custom configuration instead of a preset name.

ALLOWED_* lists accept a JSON array or a comma-separated string. CUSTOM_* presets must be JSON objects mapping a preset id to that family’s options.

VLM pipeline:

Picture description:

Code and formula enrichment:

Picture classification:

Table structure. Table and layout have both a kind (which implementation) and a preset (which configuration of it):

Layout:

OCR. Not in the upstream configuration doc:

Chunking, for the /v1/chunk/* endpoints. Also undocumented upstream:

The four ALLOW_CUSTOM_*_CONFIG flags for table structure, layout, picture classification and OCR are wired through orchestrator_factory.py but absent from the configuration doc, which lists only the VLM, picture description and code/formula ones.

Telemetry

OTEL_EXPORTER_OTLP_ENDPOINT is a standard OpenTelemetry variable, not a DOCLING_SERVE_ one, but traces and OTLP metrics go nowhere without it.

Docker Compose example

A single-container Compose file that sets the variables which matter before real traffic arrives. Models ship inside the official image, so there is no volume and no download step. The Docker guide defends each choice; this version adds an API key and a CORS restriction.

services:
  docling:
    image: quay.io/docling-project/docling-serve-cpu:v1.32.0
    ports:
      - '127.0.0.1:5001:5001'
    environment:
      # Server
      UVICORN_WORKERS: '1'
      DOCLING_NUM_THREADS: '4'
      OMP_NUM_THREADS: '4'
      # Local engine
      DOCLING_SERVE_ENG_LOC_NUM_WORKERS: '2'
      DOCLING_SERVE_ENG_LOC_SHARE_MODELS: 'true'
      # Limits
      DOCLING_SERVE_MAX_DOCUMENT_TIMEOUT: '1800'
      DOCLING_SERVE_MAX_SYNC_WAIT: '120'
      DOCLING_SERVE_MAX_FILE_SIZE: '52428800'
      DOCLING_SERVE_MAX_NUM_PAGES: '200'
      DOCLING_SERVE_MAX_SOURCES_PER_REQUEST: '3'
      # Exposure
      DOCLING_SERVE_API_KEY: 'replace-me'
      DOCLING_SERVE_CORS_ORIGINS: '["https://app.example.com"]'
      DOCLING_SERVE_SHOW_VERSION_INFO: 'false'
      # Logging
      DOCLING_SERVE_LOG_LEVEL: 'INFO'
      DOCLING_SERVE_LOG_FORMAT: 'json'
    healthcheck:
      test:
        - CMD
        - python
        - -c
        - "import urllib.request; urllib.request.urlopen('http://127.0.0.1:5001/ready', timeout=5).read()"
      interval: 30s
      timeout: 10s
      retries: 5
      start_period: 180s
    stop_grace_period: 2m
    restart: unless-stopped
    deploy:
      resources:
        limits:
          cpus: '4'
          memory: 12G

GPU images: cu128 and cu130

Four official images exist, mirrored on quay.io/docling-project/ and ghcr.io/docling-project/:

The CUDA images are deliberately not tagged latest, only with explicit versions and main, so that a deprecated CUDA build cannot arrive through a floating tag. Pin the version and match the tag to your host driver: a cu128 image needs a driver that supports the CUDA 12.8 runtime, cu130 needs 13.0.

As a Compose override on the file above:

services:
  docling:
    image: quay.io/docling-project/docling-serve-cu128:v1.32.0
    environment:
      DOCLING_DEVICE: 'cuda'
      NVIDIA_VISIBLE_DEVICES: 'all'
      NVIDIA_DRIVER_CAPABILITIES: 'compute,utility'
    runtime: nvidia

Swap in docling-serve-cu130:v1.32.0 for a CUDA 13.0 host. DOCLING_DEVICE is a Docling library variable, not a Docling Serve one, and it is the thing that actually moves the layout and table models onto the GPU. OCR through RapidOCR’s ONNX backend can still fall back to CPU silently; the Serve guide covers the check.

Scaling out with RQ

Three services: Redis, the API, and workers built from the same image with a different command. ENG_RQ_JOB_TIMEOUT sits on the API service because it is baked into each job at enqueue time.

services:
  redis:
    image: redis:7-alpine
    command: ['redis-server', '--appendonly', 'yes']
    volumes:
      - redis-data:/data

  docling-api:
    image: quay.io/docling-project/docling-serve-cpu:v1.32.0
    ports:
      - '127.0.0.1:5001:5001'
    environment:
      DOCLING_SERVE_ENG_KIND: 'rq'
      DOCLING_SERVE_ENG_RQ_REDIS_URL: 'redis://redis:6379/'
      DOCLING_SERVE_ENG_RQ_JOB_TIMEOUT: '3600'
      DOCLING_SERVE_MAX_DOCUMENT_TIMEOUT: '1800'
      DOCLING_SERVE_API_KEY: 'replace-me'
      DOCLING_SERVE_LOG_FORMAT: 'json'
    depends_on:
      - redis

  docling-worker:
    image: quay.io/docling-project/docling-serve-cpu:v1.32.0
    command: ['docling-serve', 'rq-worker']
    environment:
      DOCLING_SERVE_ENG_KIND: 'rq'
      DOCLING_SERVE_ENG_RQ_REDIS_URL: 'redis://redis:6379/'
      DOCLING_NUM_THREADS: '4'
      OMP_NUM_THREADS: '4'
      DOCLING_SERVE_LOG_FORMAT: 'json'
    depends_on:
      - redis
    deploy:
      replicas: 2
      resources:
        limits:
          memory: 12G

volumes:
  redis-data:

Under RQ the API’s /ready gates on its queue processor and Redis connection, not on whether a worker has loaded its models. Probe the workers separately. The project’s Kubernetes manifest is the same shape.

Self-hosting versus a hosted Docling API

Everything on this page is the cost of owning Docling Serve: a model cache, thread caps, an engine choice, Redis, timeouts at three layers, and a readiness probe that means what it says. That is a fair trade when you need formats beyond PDF, control over OCR, a pinned Docling version, or processing that never leaves your network. It is a poor trade when you wanted Markdown out of a PDF and nothing else.

If the second one is you, Parsebridge runs Docling as a managed API. It is our own product, so here is the honest scope: PDF in, Markdown out, through our request shape rather than Docling Serve’s. No DOCLING_SERVE_ variables, no Compose file, no /ready probe:

curl -X POST https://api.parsebridge.com/v1/parse/url \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"url": "https://example.com/document.pdf"}'

If you already run Docling Serve and it is behaving, stay there. Same parser either way.

Names, types and defaults above were read from docling_serve/settings.py, orchestrator_factory.py and policy.py at the v1.32.0 tag, with engine semantics from the docling-jobkit 3.5.0 RQ and Ray orchestrator configs. Descriptions that the upstream configuration doc does not provide were inferred from how the value is used in code, and are marked as such. The Compose files are source-reviewed against that release, not runtime-tested here.