Skip to content

pin-model-version

Docker Compose models without a tag pull different weights over time. How to pin Docker Model Runner models to a specific version.

On this page

The top-level models: element (Docker Model Runner, Compose ≥ 2.35) declares AI models as OCI artifacts, and OCI rules apply: model: ai/gemma3 with no tag resolves to whatever the registry currently serves. For a model, drift means different weights: often a different parameter count or quantization, with different memory needs and different behavior on the same prompts. This rule flags top-level models whose model: reference has no tag or uses latest.

What the rule catches

compose.yaml — whichever weights the registry serves today
services:
  agent:
    image: my-agent:1.2.0
    models: [gemma3]
models:
  gemma3:
    model: ai/gemma3

Scanning this file reports:

⚠ WARN [docker-doctor/pin-model-version]
  Model 'gemma3' artifact 'ai/gemma3' does not specify a tag. Every pull may fetch different weights.

Why it matters

An unpinned model is an unversioned dependency at the most behavior-sensitive layer of the stack. When outputs change, nothing in git explains why: the compose file is identical, the app is identical, only the silently updated weights differ. Debugging that means re-benchmarking prompts instead of reading a diff. A pinned tag turns 'the model changed' from a hypothesis into a visible line in version control, exactly like pin-service-image does for service images.

How to fix it

Pin the model to a specific tag (e.g. ai/gemma3:4B-Q4_0) so every environment runs the same weights. Model behavior differences are far harder to debug than software version drift.

compose.yaml — exact quantization, reproducible behavior
services:
  agent:
    image: my-agent:1.2.0
    models: [gemma3]
models:
  gemma3:
    model: ai/gemma3:4B-Q4_0
    context_size: 10000

Model tags encode size and quantization (ai/gemma3:4B-Q4_0), so the pin also documents the VRAM footprint you tested against. That pairs well with context_size, which trades context length against memory on the same weights. Pinning matters double for agents: tool-calling reliability varies sharply between model versions, so an unpinned model can turn a working agent into a flaky one without any code change.

Rule details

  • Rule key — docker-doctor/pin-model-version
  • Category — Compose
  • Default severity — warning
  • Applies to — Docker Compose files

Explain this rule from the CLI:

npx @docker-doctor/cli@latest rules explain docker-doctor/pin-model-version

Change its severity — or turn it off — in your config file:

// docker-doctor.config.ts
export default {
  rules: {
    "docker-doctor/pin-model-version": "off",
  },
};

Severity affects the health score: error findings cost more points than warning, and info costs the least.