I/O

Lossless save / load. Stock save_model / load_model round-trips the trees but loses best_iteration_, normalized feature_names_, and class label ordering. cbx.io.save writes a JSON sidecar next to the model file; cbx.io.load reads it.

from catboost_utils.io import save, load

save(model, "artifact.cbm")          # writes artifact.cbm + artifact.cbm.meta.json
restored = load("artifact.cbm")      # restores best_iteration, picks correct model class

Sidecar contents include catboost_utils_version, catboost_version, model_kind (classifier / regressor / catboost), feature_names, cat_features indices, class_names, best_iteration, training_params, and an ISO-8601 saved_at.

load() works without a sidecar (logs a warning), so external .cbm files still load — you just don't get the metadata back.

catboost_utils.io.persistence.save

save(
    model: Any,
    path: str | PathLike[str],
    *,
    format: str = "cbm",
) -> None

Save model to path and write a metadata sidecar.

Parameters:

Name	Type	Description	Default
model	Any	a fitted CatBoost / CBX model.	required
path	str | PathLike[str]	target file path.	required
format	str	forwarded to model.save_model(format=...) — "cbm" (default), "json", "onnx", etc.	'cbm'

catboost_utils.io.persistence.load

load(
    path: str | PathLike[str], *, format: str = "cbm"
) -> CatBoost

Load a model previously saved via save().

Parameters:

Name	Type	Description	Default
path	str | PathLike[str]	model file path.	required
format	str	passed to CatBoost's load_model.	'cbm'

Returns:

Type	Description
CatBoost	A fitted CatBoostClassifier / CatBoostRegressor / CatBoost
CatBoost	instance with metadata reattached when a sidecar is present.