Users portal

This page is for darktable users – people running the application. If you want to convert or contribute models, head to the Developers portal.

Which models exist

Browse the Model catalog for the current set. In short:

• Object masking (darkroom → mask manager → AI object tool) – the SAM 2.1 family + SegNext. SAM 2.1 small is the recommended default; tiny is lighter, base plus is heavier.
• Neural restore (sidebar in lighttable and darkroom) – denoise, raw denoise, and upscale models.
• Image embeddings – OpenCLIP, used for similarity search and tagging.

Each model card lists what it's good at, what it needs, and any known limitations.

Installing from inside darktable

This is the recommended path. Open preferences → AI. The first time you visit the tab, darktable fetches a small manifest from this repo's releases and shows a table of available models.

You'll see three buttons:

• download / update default – grabs every model marked as default for each task. Quickest way to get a working setup.
• download / update selected – tick the rows you want first, then click. Use this to grab a single model or update a few.
• import from file… – pick a .dtmodel you've sideloaded (nightly build, custom build, anything). Multi-select works.

A freshly-installed or downloaded model is auto-activated for its task only when nothing else is active there. If you already had one model active for that task, the new one is installed but stays off – just toggle the enabled checkbox to switch.

Building your own

If you want models that haven't been released yet, build them yourself – see Getting started – and sideload via import from file…. Useful for testing model bumps before they ship.

Nightly builds

The repo publishes a rolling nightly-X.Y.Z pre-release for each darktable dev cycle. It's rebuilt whenever a model definition changes on master and clearly marked as pre-release on GitHub.

Two ways to use it:

1. Open the releases page, find the nightly matching your darktable version, and download .dtmodel files. Sideload via import from file….
2. Run a nightly darktable build – its AI preferences will fetch from the matching nightly automatically.

Things move fast on nightly. Models can change between rebuilds, behaviour can shift, things can break. Use with caution; report what breaks.

GPU execution providers

The ONNX models in this repo work on whichever execution provider your darktable build includes:

• CUDA (NVIDIA) – fastest on Linux/Windows
• ROCm / MIGraphX (AMD) – Linux
• DirectML (Windows) – any GPU on Windows
• CoreML (macOS) – Apple Silicon and Intel
• OpenVINO (Intel) – CPU and integrated GPU
• CPU – always works, just slower

Tile sizes are baked into each model's manifest, so JIT-compiling providers (CoreML, MIGraphX) only pay the compile cost once per session.

Troubleshooting

Slow inference, no GPU. Open preferences → AI → execution provider. If it shows CPU and you expected GPU, either your darktable build doesn't ship the EP for your hardware, or there's no compatible ONNX Runtime library on your system. Some EPs need a separate runtime install – see tools/ai/README.md in the darktable repo for platform-specific install scripts and notes.

Out of memory. Try a smaller variant – e.g. SAM 2.1 tiny instead of small. Reduce AI mask render resolution in preferences → AI if the model supports it.

"Update available" never clears. The version check reads versions.json from the latest release matching your darktable build. Make sure you've actually downloaded the matching .dtmodel, not a stale one.

Model downloads fail. Check your network can reach github.com/darktable-org/darktable-ai/releases. Behind a proxy? Set https_proxy before launching darktable.

I want to back out of a model. preferences → AI → tick the row → delete selected. The next default for that task auto-activates if one is available.