How do you organize model versions, aliases, and stages in a model registry?

Organize models under a stable registered-model name, give each candidate its own numbered version, and use aliases to identify the version selected for a particular purpose. Use version tags to express review or validation status.

Modern MLflow recommends model aliases and tags instead of legacy model stages. Stages such as Staging, Production, and Archived are deprecated and will be removed in a future major release.

Beginner-friendly example: delivery-time model

A food-delivery company has a registered model called delivery_time_predictor. Three candidates have been registered:

• Version 1: Validation MAE 5.2 minutes — original baseline.
• Version 2: Validation MAE 4.8 minutes — current approved model.
• Version 3: Validation MAE 4.5 minutes — newer candidate awaiting final checks.

The model registry can hold all three versions at once. An alias such as champion currently points to version 2. A second alias, candidate, may point to version 3.

Registered model: delivery_time_predictor
  ├── Version 1  [validation_status=passed]
  ├── Version 2  [validation_status=passed] ◄── @champion
  └── Version 3  [validation_status=pending] ◄── @candidate

If version 3 later passes evaluation and operational checks, the team can reassign champion to version 3. Its lower validation MAE represents a potential (4.8 − 4.5) / 4.8 × 100 = 6.25% improvement, *provided both scores came from the same evaluation protocol*. A better score alone does not authorize production deployment.

Understand the three main concepts

1. Registered model: A stable logical model name, such as delivery_time_predictor, containing related candidate versions.

2. Model version: A numbered, registered candidate. models:/delivery_time_predictor/2 identifies version 2. A model version carries information about its source and associated metadata. It is important to preserve underlying model artifacts and access permissions.

3. Model alias: A mutable named pointer to one version, such as models:/delivery_time_predictor@champion. The alias can move; its target version should not silently change beneath the same version identity.

Tags: Key-value annotations such as validation_status=passed, reviewer=ml-platform, or deployment_approval=granted. Tags communicate status or evidence; they are not a substitute for access-controlled approvals.

How do you promote using modern MLflow?

Use the MLflow client API to assign aliases:

PYTHON
from mlflow import MlflowClient

client = MlflowClient()
model_name = "delivery_time_predictor"

# Example: version 2 has already been reviewed and approved.
client.set_registered_model_alias(
    name=model_name,
    alias="champion",
    version="2",
)

# Inspect the current alias target.
approved = client.get_model_version_by_alias(
    name=model_name,
    alias="champion",
)
print("Approved version:", approved.version)

To promote a different version *after an independent approval check*:

PYTHON
# Execute only after validation, sign-off, and release controls.
client.set_registered_model_alias(
    name=model_name,
    alias="champion",
    version="3",
)

This shows registry operations, not a complete automated release-gate implementation. In practice, a controlled CI/CD process should confirm validation, permissions, required model metadata, and the currently approved version before changing an alias.

A serving application can resolve an alias:

PYTHON
import mlflow.pyfunc

model = mlflow.pyfunc.load_model(
    "models:/delivery_time_predictor@champion"
)

Important: Updating an alias does not automatically reload or redeploy an already-running model server. A serving process may resolve the alias at startup and keep an older model in memory. Integrate alias changes with an explicit deployment or refresh process and verify the actual served version.

What about legacy Staging and Production stages?

Older MLflow registry workflows supported four fixed stage values: None, Staging, Production, and Archived.

A former URI like:

models:/delivery_time_predictor/Production

is a legacy stage reference. Modern workflows instead use, for example:

models:/delivery_time_predictor@champion

A practical migration path:

1. Identify each current stage's intended model version.
2. Create appropriate aliases such as champion, candidate, or shadow.
3. Store validation and review states as model-version tags.
4. Update training, evaluation, and serving consumers to resolve aliases or fixed version numbers, rather than stage URIs.
5. Separate environments through appropriate registry naming, access controls, and promotion workflows instead of assuming a stage label is a security boundary.
6. Test production loading and rollback before retiring stage-based code.

Stages are deprecated, not simply interchangeable with aliases in every workflow. Environment names, permissions, and approval policy must be designed explicitly.

Why can aliases be useful?

• Stable application reference: The serving application refers to @champion, while the approved version changes through controlled promotion.
• Canary or shadow testing: Define aliases such as @candidate or @shadow for separate testing workflows.
• Rollback: If the newly deployed version performs poorly, reassign an alias to a previously approved version and coordinate serving rollback.
• Independent purposes: A version can have more than one alias, such as @champion and @shadow, when appropriate.

Aliases point to a version; they do not automatically route traffic percentages, schedule deployment, validate metrics, or guarantee that all serving instances switched.

Keep versions and environments understandable

For a larger company, a common pattern is to use separate registered model names for environments, such as:

dev.delivery_time_predictor
staging.delivery_time_predictor
prod.delivery_time_predictor

The exact naming conventions depend on the registry backend and organization's setup. Enforce development and production permissions independently. Promoting a candidate between such environments can require copying/registering the model in the target registry location while retaining its provenance.

For a small project, one registered model with well-managed aliases may suffice; do not create elaborate environments without a genuine need.

Common mistakes

• Treating @champion as a permanently fixed version.
• Equating the lowest validation error with production approval.
• Assuming an alias update instantly replaces a live model in every server.
• Rewriting or deleting model artifacts that older versions need for rollback.
• Using legacy stages as though they are MLflow's recommended future API.
• Putting confidential information in model tags.
• Changing the production alias without recording who approved the change, the previous version, and deployment verification.

In short: Use registered models for logical grouping, version numbers for specific candidates, aliases for movable references, and tags for review status. Prefer MLflow's modern aliases over deprecated stages, and keep actual deployment and approval safeguards explicit.