Model versioning tracks exactly which trained model artifact is which — the code, data, and hyperparameters that produced it — so any deployed model can be traced back, reproduced, or rolled back to precisely.
Why "Just Overwrite model.pkl" Fails
Without versioning, retraining and saving over the same file destroys the ability to answer basic operational questions: which model is currently live? What produced last week's predictions that are now being audited? Can we roll back to the version from before a metric regression appeared? Model versioning exists specifically to keep these questions answerable.
What a Model Version Should Capture
| Element | Why It Matters |
|---|---|
| A unique version identifier | Unambiguous reference — "v1.3.0," not "the new model" |
| The exact training data version | Reproducibility — see Data Versioning |
| The exact code/commit used | Lets you rebuild the identical training run later |
| Hyperparameters and metrics | Understanding why this version differs from others — see Experiment Tracking |
| Library/environment versions | Avoiding subtle behavior differences from a mismatched runtime, as covered in Docker for ML Models |
A Simple Manual Versioning Pattern
import joblib
import json
from datetime import datetime
def save_versioned_model(model, metrics, params, version):
joblib.dump(model, f"models/model_v{version}.pkl")
metadata = {
"version": version,
"created_at": datetime.utcnow().isoformat(),
"metrics": metrics,
"hyperparameters": params,
}
with open(f"models/model_v{version}_metadata.json", "w") as f:
json.dump(metadata, f, indent=2)
save_versioned_model(
model,
metrics={"accuracy": 0.87, "f1": 0.81},
params={"n_estimators": 200, "max_depth": 10},
version="1.3.0",
)Using MLflow for Automated Versioning
import mlflow
import mlflow.sklearn
with mlflow.start_run():
mlflow.log_params({"n_estimators": 200, "max_depth": 10})
mlflow.log_metrics({"accuracy": 0.87, "f1": 0.81})
mlflow.sklearn.log_model(model, "model")
# MLflow automatically assigns a unique run ID -- a complete version recordPurpose-built tools like MLflow (or DVC, or a cloud provider's model registry) automate what the manual pattern above does by hand — logging metadata, versioning artifacts, and making past versions easy to browse and retrieve.
Semantic Versioning for Models
| Version Change | Meaning |
|---|---|
| Major (1.x.x → 2.0.0) | Fundamentally different model (new architecture, new feature set) |
| Minor (1.2.x → 1.3.0) | Retrained on new data, or meaningfully different hyperparameters |
| Patch (1.2.3 → 1.2.4) | Small fix, e.g. a bug in preprocessing, minimal behavior change |
Practical Use Cases
- Rolling back to a known-good model when a new deployment regresses in production
- Auditing exactly which model produced a specific historical prediction
Common Mistakes
- Versioning only the model file, without the data version, code commit, or environment it depended on — an incomplete version record.
- Manually overwriting the "current" model file in place instead of keeping distinct, retrievable versions.
Interview Relevance
Q: "Why isn't versioning the model file alone sufficient?" A model's behavior depends on the exact data, code, and hyperparameters used to train it — versioning the file alone loses the ability to reproduce or fully understand that specific version later; a complete version record needs the data version, code commit, and training configuration alongside the artifact itself.
Practice Question
A production model starts performing worse after a redeployment. What specifically would proper model versioning let you do to investigate and recover?
