Model Registry
Intermediate 14 min read Model Registry

MLflow Registry

Tracking, registry and serving in one platform

MLflow's registry turns tracked runs into governed models: register versions from runs, transition stages, set aliases, add descriptions and control permissions — all through one API and UI.

MLflowmodel registryregistered modelmodel versiontransition
Prerequisites: The Model Registry MLflow Tracking
Before we start

What you will learn

  • Register a tracked run as a model version
  • Record descriptions, tags and stage transitions
  • Query registry state programmatically
Introduction

What is this?

MLflow's model registry provides registered models, which are containers for versions of a model produced from tracked runs. Each version carries artifacts, metrics, tags and lineage; versions advance through stages (Staging, Production, Archived) with transitions that can require approvals. The registry plugs into the same platform as tracking and serving.

Motivation

Why do you need it?

  • It reuses run lineage — every registered version inherits its training recipe automatically.
  • Stage transitions give the governed movement that deployment and audit need.
  • The CLI, SDK and UI give humans and pipelines the same registry.
  • Serving integration loads versions directly, keeping registry and deployment in lockstep.
Think about it

Mental model

Imagine

A car dealership's lot inventory

Think of

Registered MLflow models

Each car parked in a run; the dealer (registry) lists models/trim (registered models), assigns stock IDs (versions), marks status (staging/test-drive/sold), and logs the paperwork (approvals). One lot serves the whole operation.

Mechanics

How it works

  • mlflow.register_model() creates a registered model and its first version from an artifact URI.
  • Each version links back to its source run, so lineage and metrics travel with it.
  • transition_model_version_stage moves versions between Staging, Production and Archived.
  • Aliases (champion, candidate) point at versions for semantic addressing.
  • Permissions control who can register, transition and delete.

Registering a run and advancing versions.

Tracked run
register_model
Version metadata
Stage transitions
Serving uses it
Hands-on

Examples

Register and transition a version

Register and transition a version
from mlflow.tracking import MlflowClient
client = MlflowClient()
client.create_registered_model("churn_model")
client.create_model_version("churn_model",
                             "s3://artifacts/run-abc/model", "run-abc")
client.transition_model_version_stage("churn_model", 1, "Staging")
client.update_model_version(
    "churn_model", 1, description="candidate from weekly retrain")

Registering from a run keeps lineage; transitions and descriptions add the governance layer serving and audit depend on.

Real world

In production

  • A nightly pipeline registers each candidate, then CI transitions only the passing one to Staging.
  • A human reviews Staging versions and approves Production transitions through the UI.
  • Serving loads 'Production' via the registry so rollback is a registry pointer flip.
Guidelines

Best practices

  • Register from the run artifact URI, never a re-serialized copy.
  • Use descriptions and tags to record the promotion rationale.
  • Apply permissions to stage transitions (who may promote).
  • Archive aggressively once successors promote; keep versions queryable.
Watch out

Common mistakes

  • Duplicate registered models for the same logical model ('churn', 'churn_model', 'churn2').
  • Transitioning to Production without metrics recorded on the version.
  • Registering serialized copies so lineage to the run is broken.
  • Deleting versions to 'tidy' — destroying audit history.
When things break

Debugging tips

  • 'Version not found' — the model name must match exactly; list registered models to confirm.
  • Transition blocked — check the approval/permission policy on that stage.
  • Artifact unreachable at serving — re-register with the correct artifact URI for that run.
Interviews

Interview checkpoint

Practice

Hands-on lab

Register Models and Transition Stages
30 min · intermediate
In progress
Objectives
  • Register the artifact of a tracked run as a model version
  • Move versions through Staging → Production → Archived
  • Query the registry to verify state and linkage

Register Models and Transition Stages

30 min · intermediate

0/4 steps
0%
sandbox · Linux sandbox
$
Try these commands
Test yourself

Quick quiz

0/2
1

What links an MLflow model version back to its training?

2

Stage transitions in MLflow can encode approval requirements.

Go deeper

Official documentation

MLflow Model Registry docs
docs
MLflow registry API (MlflowClient)
docs