Quickstart

The recommended entry point is CBXClassifier / CBXRegressor — a drop-in replacement for the stock CatBoost classes with the UX layer built in.

from catboost_utils import CBXClassifier

model = CBXClassifier(
    iterations=500,
    auto_cat_features=True,    # detect str/category/bool columns automatically
    nan_fill="__NA__",         # explicit NaN handling for cat features (no magic)
    early_stopping="auto",     # sane defaults when eval_set is provided
)
model.fit(X_train, y_train, eval_set=(X_val, y_val))

isinstance(model, CatBoostClassifier) is still True. clone(), GridSearchCV, and pickle work.

Or wrap an existing model

If you already have a stock CatBoostClassifier from someone else's code:

from catboost import CatBoostClassifier
from catboost_utils import wrap

model = wrap(CatBoostClassifier(iterations=500))
model.fit(X, y)

wrap() swaps the class, so the same instance now has all the CBX behavior — error translation, feature-name resolution — without losing identity.

Validate first

from catboost_utils import validate

report = validate(X_train, y_train, cat_features=["city"])
report.raise_if_failed()    # raises on blocking issues
report                       # in Jupyter: rich HTML table of warnings

Where to next

Each module is independent. Browse the Modules section.