Introduction

In TensorFlow eager mode, restoring from a checkpoint means recreating the Python objects that own the variables and then loading saved values into them. The checkpoint does not magically rebuild your entire program structure; it restores the variable state of the objects you connect to tf.train.Checkpoint.

What a TensorFlow Checkpoint Actually Stores

A TensorFlow checkpoint stores variable values associated with trackable objects such as:

• models
• layers
• optimizers
• custom tf.Module instances

That means restore works best when you rebuild the same object graph in code and then ask TensorFlow to populate it.

In eager mode, this feels natural because the objects are ordinary Python objects with live variables.

A Minimal Save and Restore Flow

1import tensorflow as tf
2
3class MyModel(tf.keras.Model):
4    def __init__(self):
5        super().__init__()
6        self.dense = tf.keras.layers.Dense(1)
7
8    def call(self, x):
9        return self.dense(x)
10
11model = MyModel()
12optimizer = tf.keras.optimizers.Adam()
13
14x = tf.ones((2, 3))
15_ = model(x)  # build variables
16
17ckpt = tf.train.Checkpoint(model=model, optimizer=optimizer)
18path = ckpt.save("/tmp/example_ckpt")
19print(path)

Now restore it by recreating the same objects.

1import tensorflow as tf
2
3class MyModel(tf.keras.Model):
4    def __init__(self):
5        super().__init__()
6        self.dense = tf.keras.layers.Dense(1)
7
8    def call(self, x):
9        return self.dense(x)
10
11model = MyModel()
12optimizer = tf.keras.optimizers.Adam()
13_ = model(tf.ones((2, 3)))  # build variables first
14
15ckpt = tf.train.Checkpoint(model=model, optimizer=optimizer)
16latest = tf.train.latest_checkpoint("/tmp")
17ckpt.restore(latest)
18
19print(model(tf.ones((1, 3))))

The key steps are recreate, build, then restore.

Why Building Matters

If the model has not created its variables yet, there may be nothing to restore into.

For subclassed Keras models especially, variables are often created only after the first call. That is why many restore examples call the model once with a dummy input before restore.

If you skip this step, TensorFlow may defer or partially apply restoration, which can be confusing when debugging.

Restoring the Latest Checkpoint

The most common pattern is:

latest = tf.train.latest_checkpoint(checkpoint_dir)
if latest:
    ckpt.restore(latest)

This is useful for training resumption because it does not require hardcoding a specific checkpoint filename.

If the training loop also needs optimizer state, include the optimizer in the checkpoint object as shown earlier.

Model Weights Versus Full Training State

There are two common goals:

• restore only model weights for inference
• restore model plus optimizer for continued training

For inference-only use, checkpointing the model alone is often enough.

ckpt = tf.train.Checkpoint(model=model)
ckpt.restore(latest)

For training resumption, include the optimizer so moments and slot variables come back too.

Checkpoint Restore Status

TensorFlow exposes a restore status object that helps validate what happened.

status = ckpt.restore(latest)
status.expect_partial()

or, if you expect a full exact match:

status.assert_existing_objects_matched()

These checks are useful when the model definition changed and you want to know whether the checkpoint still lines up with the current code.

Checkpoint Versus SavedModel

A checkpoint is excellent for training state. It is not the same thing as a portable exported inference artifact.

Use checkpoints when:

• resuming training
• restoring eager-mode objects in Python
• keeping optimizer state

Use SavedModel when:

• exporting a model for serving
• moving the model across runtime boundaries
• preserving callable signatures for deployment

Confusing those two formats causes a lot of restore frustration.

Common Pitfalls

The most common mistake is trying to restore before the subclassed model has created its variables.

Another mistake is expecting a checkpoint to rebuild your custom Python object structure automatically. You still need to instantiate the model and related objects in code.

A third issue is forgetting the optimizer when resuming training, which restores weights but loses optimizer state.

Finally, if the current model architecture no longer matches the checkpoint, restore may only be partial. Use the restore status checks instead of assuming a full match.

Summary

• In eager mode, recreate the model objects first, then restore checkpoint values into them.
• Build subclassed models before restoring so variables exist.
• Use tf.train.Checkpoint to track model and optimizer state.
• 'tf.train.latest_checkpoint is the normal way to find the newest checkpoint.'
• Include the optimizer if you want to resume training, not just inference.
• Checkpoints restore variable state; they do not replace object construction in your Python code.