In Keras, what does ModelCheckpoint(save_best_only=True) change about when a file is written?

## What the callback does `keras.callbacks.ModelCheckpoint` is the standard way to persist a model *during* a `fit()` run rather than after it. You never call it yourself; you construct it and hand it to `model.fit(..., callbacks=[ckpt])`, and Keras invokes its hooks around each epoch and batch. Its job is narrow: decide *whether* to save right now, and *what* to write. ``` ckpt = keras.callbacks.ModelCheckpoint( filepath="ckpt/best.keras", monitor="val_loss", mode="min", save_best_only=True, ) ``` ## save_best_only, and what "best" means With the default `save_best_only=False`, the callback writes at the end of every epoch. If `filepath` is a constant string, each write overwrites the previous file, so you end up with the *last* epoch, not the best one. That is the classic beginner outcome: training visibly overfit after epoch 12, and the file on disk is epoch 40. With `save_best_only=True`, the callback keeps an internal `best` value. At the end of each epoch it reads `logs[self.monitor]` and compares. The comparison direction comes from `mode`: - `mode="min"` — an improvement is a *smaller* value. Correct for losses and error metrics. - `mode="max"` — an improvement is a *larger* value. Correct for accuracy, AUC, F1. - `mode="auto"` (the default) — Keras infers the direction from the metric name, treating names that look like accuracy/AUC as `max` and everything else as `min`. `auto` is right most of the time and wrong exactly when your metric has an unusual name. If you have a custom metric where higher is better and the name does not advertise it, set `mode` explicitly rather than trusting the guess. ## The monitor key must actually exist The monitored value is looked up in the `logs` dict Keras passes to the callback at epoch end. That dict contains the epoch's training metrics under their metric names, plus validation metrics prefixed with `val_` — but the `val_` entries only exist when `fit()` was given `validation_data` or `validation_split`. So `monitor="val_loss"` with no validation data, or `monitor="val_acc"` when the compiled metric is named `accuracy` (giving `val_accuracy`), both miss. Keras does not raise; it emits a warning saying the monitored value is not available and skips the save. A run can therefore complete with an empty checkpoint directory and no error. When a checkpoint file is mysteriously missing, check the metric name first. ## The filepath is a template `filepath` is run through Python string formatting with the epoch number and the contents of `logs`, so `"model.{epoch:02d}-{val_loss:.3f}.keras"` produces `model.07-0.312.keras`. A templated path keeps every write as a separate file — useful for inspecting a training trajectory, dangerous for disk usage on a long run. A constant path keeps exactly one file. Combining a constant path with `save_best_only=True` is the usual production choice: one file, always the best epoch. ## Keras 3 extension rules and what is inside the file Keras 3 validates the suffix. With `save_weights_only=False` (the default) the path must end in `.keras`, the backend-agnostic v3 archive; with `save_weights_only=True` it must end in `.weights.h5`. Passing the wrong suffix raises rather than guessing. The distinction matters beyond naming: a full `.keras` save carries architecture, weights and the optimizer's state, so reloading gives you an optimizer that can continue training sensibly. A weights-only file carries the weight values alone — trainable kernels and biases, plus non-trainable weights such as BatchNormalization moving statistics — but no optimizer slots, so resuming from it restarts the optimizer's momentum from scratch. ## save_freq `save_freq="epoch"` is the default. Passing an integer switches to "every N training batches", which is how you checkpoint inside a very long epoch. Note that `save_best_only` still needs a monitored value to compare, and validation metrics only refresh once per epoch, so mid-epoch best-only checkpointing on a `val_` metric compares against a stale number. ## What it does not do ModelCheckpoint writes artifacts; it does not resume anything. Restarting a killed run means loading the file yourself and passing `initial_epoch` to `fit()`, and the callback keeps no memory of its `best` value across processes — a fresh run starts with an empty best and will happily overwrite a better file from the previous run.