Model version pinning

Model version pinning is the production practice of locking your app to a specific model snapshot (e.g., `claude-sonnet-4-6-20250101`) instead of an alias (`claude-sonnet-4-6`) — protects against silent behavior changes when the provider rolls a new snapshot.

LLM providers ship model improvements continuously. If you call the alias (`gpt-4o`, `claude-sonnet-4-6`), the provider can swap the underlying weights at any time — usually fine, but sometimes breaks edge cases your prompts relied on. Pinning to a snapshot (`gpt-4o-2024-08-06`, `claude-sonnet-4-6-20250101`) gives you stable behavior at the cost of missing improvements. Production patterns: pin in prod, test on alias in staging, plan migrations on quarterly cadence. Anthropic, OpenAI, Google all offer both alias + snapshot in 2026. The right policy: pin prod, allow alias in dev, run eval suite before promoting new snapshots.

When to use model version pinning

• Production deployments.
• Eval-driven prompt iteration.

Common mistakes

• Using alias in prod — silent regressions when the provider rolls a new snapshot.
• Forgetting to migrate pinned versions — providers eventually deprecate old snapshots.

FAQ

Related terms

• Model deprecation — Model deprecation is the lifecycle event where a provider announces and eventually removes an LLM snapshot — production apps must migrate to a newer model or pinned version before the deprecation date or queries start failing.
• Evals-driven development — Evals-driven development is the discipline of writing the eval suite first, then iterating prompts and models against it — borrowing test-driven development for LLM work.

Last updated: 2026-06-01. Raw markdown: https://promtable.com/glossary/model-version-pinning.md.