Skip to content
Tutorials Center
My learning

Topics

Lesson 34 of 40 ยท Deployment and Pitfalls

Saving, Loading and Versioning Models

Save boosted models in portable formats (JSON, UBJ, text), compare them with pickle and joblib, verify round trips, and version a model together with its feature list and metadata.

A trained model is useless if you cannot reload it tomorrow, on another machine, in another process. Boosted trees are small, simple objects, so saving them is easy, but the choices you make now decide whether the model still loads after a library upgrade, whether it is safe to load, and whether you can tell which model produced a prediction. This lesson covers the formats, a verification habit, and a minimal versioning scheme.

Native formats

Both libraries have their own model formats. Prefer them to pickle for anything you keep.

Library Call Formats
XGBoost model.get_booster().save_model("m.json") and xgb.Booster().load_model("m.json") .json (readable), .ubj (binary JSON, smaller and faster), legacy .model/.bin
LightGBM model.booster_.save_model("m.txt") and lgb.Booster(model_file="m.txt") text file; model_to_string() returns the same text

The XGBoost JSON file includes the trees and the learned parameters needed for prediction (objective, base score, number of features), and in recent versions the feature names and types. The LightGBM text file includes the trees, feature names and the objective.

Python Round trip: save, reload and compare predictions

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with input()), it gets the next line from this box.

The round trip should give bit-for-bit (or within floating-point tolerance) identical predictions. Make this test a habit: after saving a model, load it into a fresh process and compare predictions on a few hundred rows. It catches truncated files, wrong feature order and version drift.

Notice that both native loaders return a Booster, whose predict gives probabilities for binary objectives but has none of the scikit-learn methods (predict_proba, classes_). That is the price of the native route; it is also why many teams serve the booster directly. Keeping the whole scikit-learn estimator is what joblib is for (see below). The scikit-learn wrapper has its own save_model and load_model too; how well they work with predict_proba depends on the library versions (some combinations of XGBoost and scikit-learn raise errors about the estimator type), so saving the booster is the dependable route.

Pickle and joblib

joblib.dump(model, "model.joblib") (or pickle) saves the entire scikit-learn-style estimator, including its Python wrapper attributes such as classes_ and feature_importances_, and it also saves preprocessing pipelines when the model sits inside a scikit-learn Pipeline. This is convenient, but with important limits:

  • A pickle only loads reliably with the same library versions (Python, scikit-learn, XGBoost, LightGBM) that created it.
  • Never unpickle a file you do not trust. Unpickling can run arbitrary code.
  • The native formats are safer and keep working across many versions.

A practical rule: save the booster in a native format for the long term, and use joblib for the whole pipeline when the serving environment is pinned and under your control.

Python A pipeline survives pickle, the booster survives JSON

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with input()), it gets the next line from this box.

The second half shows the price of the native format: it stores only the model, so you must carry the preprocessing (scaling, encoders, feature order) separately. For boosted trees preprocessing is often minimal (no scaling needed), which is one more reason they are pleasant to deploy.

What to store with a model

A bare model file is hard to trust six months later. Save a small metadata file next to it:

JSON
{
  "model_file": "churn-2026-11-12.json",
  "created": "2026-11-12T10:00:00Z",
  "library_versions": {"python": "3.12.3", "xgboost": "3.0.2", "scikit-learn": "1.7.0"},
  "features": ["tenure", "monthly_charges", "contract_type", "..."],
  "categorical_features": ["contract_type"],
  "training_rows": 120000,
  "training_data_hash": "sha256:...",
  "validation": {"metric": "pr_auc", "value": 0.41},
  "threshold": 0.23,
  "git_commit": "a1b2c3d"
}

The feature list in order is the most important field: a model fed columns in a different order (as a plain NumPy array) gives wrong predictions without any error. Store the threshold with the model too, since it belongs to this specific model (Thresholds).

flowchart LR
  T["Training run"] --> M["model.json / .ubj / .txt"]
  T --> J["metadata.json<br/>features, versions, metrics, threshold"]
  M --> R["Model registry or storage"]
  J --> R
  R --> S["Serving: load, check features, predict"]

Store the model, its metadata and an identifier as one unit.

Practical checklist

  • Use .ubj or .json for XGBoost, .txt for LightGBM; pin library versions for pickles.
  • After saving, reload in a fresh process and compare predictions.
  • Keep the feature names and order; pass DataFrames with named columns where the library checks them (XGBoost validates feature names by default; LightGBM checks the count, and predict_disable_shape_check should stay off).
  • Never overwrite a deployed model file: write a new, dated file and switch a pointer.
  • Keep the previous model for fast rollback.
  • Store models in object storage or a registry (MLflow, a bucket with versioning), not in git.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. Why prefer the native JSON or UBJ format over pickle for long-term storage?

    Pickle depends on exact class layouts and can execute code on load; native formats are designed for stability and safety.
  2. 2. You saved only the booster. What must you remember when serving?

    The booster contains trees only. Encoders, scalers and the column order must be reproduced by your own code.
  3. 3. What is the best test after saving a model?

    A prediction comparison proves the file is complete and the loader reproduces the model.
  4. 4. Which item of metadata is most likely to prevent silent errors?

    A model fed columns in the wrong order will return wrong predictions without raising an error.

Summary

  • Save boosters in native formats (.json/.ubj for XGBoost, text for LightGBM) and verify the round trip.
  • Use pickle or joblib only for pinned, trusted environments, and never load untrusted pickles.
  • Store metadata: library versions, ordered features, validation metrics, threshold, data and code identifiers.
  • Version model files, keep the previous one for rollback, and keep preprocessing alongside the model.

Next: Fast and Scalable Inference