AI features on darktable user manual

overview

Mon, 01 Jan 0001 00:00:00 +0000

darktable uses machine learning models for a handful of image-processing tasks: interactive object masking, denoising, upscaling, etc. This section explains how those features work end-to-end – what runs where, which models exist, how inference is accelerated, and what the user’s choices in the AI preferences actually control.

AI features are opt-in. They are off by default in a fresh install and can be toggled with a single preference at any time.

how AI features work

Mon, 01 Jan 0001 00:00:00 +0000

This page covers what goes on under the hood: the inference library darktable loads, the execution providers available to it, and how models are stored and activated.

🔗the inference runtime

darktable loads models through ONNX Runtime – a production-grade inference library originally developed at Microsoft and now governed by the Linux Foundation – that accepts models in the ONNX open format. ONNX is the de-facto standard for interchanging machine-learning models across frameworks (PyTorch, TensorFlow, etc.) so we can take a model trained in any of them, export it to ONNX, and run it from darktable without carrying its training framework along.

GPU acceleration

Mon, 01 Jan 0001 00:00:00 +0000

Enabling GPU acceleration for darktable’s AI features is a two-step process:

Install a GPU-capable ONNX Runtime for your hardware (this page).
Point darktable at the new library via AI preferences – click detect to auto-scan standard install locations, or browse to the file by hand.

On Linux, the bundled runtime is CPU-only; on Windows, it uses DirectML; and on macOS, it uses CoreML. So, step 1 only applies if you want NVIDIA, AMD, or Intel GPU acceleration on Linux or Windows. Step 1 has three paths, covered below.

performance & troubleshooting

Mon, 01 Jan 0001 00:00:00 +0000

🔗performance notes

CPU inference is acceptable for object masks (small one-shot evaluations) but much slower for denoise and upscale. A CUDA / MIGraphX / OpenVINO / DirectML / CoreML runtime is strongly recommended if you use those regularly.
Upscale at 4x on a large image is memory-hungry regardless of provider. Tiling is enabled automatically to keep memory in check, at a cost of some extra processing time.
Loading ONNX Runtime lazily on first use means the very first AI operation after startup takes an extra moment. This is normal.
When switching between execution providers (e.g. auto → CUDA), the new provider’s first inference incurs a graph-compilation delay. After that, runtime is steady for the rest of the session.
AMD (MIGraphX) has a multi-minute first-run cost per model. ROCm/MIGraphX compiles the model graph for your specific GPU the first time it sees it, which can take 1–3 minutes for large models (denoise, upscale); mask models are smaller and compile faster. The compiled graph is cached on disk under ~/.cache/darktable/ai_v*_migraphx_* and reused across darktable restarts, so subsequent runs of the same model are fast.
Model discovery is cached at startup. If you drop a new .dtmodel file into the models directory manually while darktable is running, open AI preferences and toggle any control to force a rescan.

🔗troubleshooting

Most AI problems fall into one of three buckets.