Reliability of _class_path in Lightning checkpoints when using instantiate_module

[aditya0by0]

Hi Lightning team ,

I have a question regarding the reliability and long-term guarantees of relying on _class_path stored inside Lightning checkpoints, specifically when using instantiate_module from lightning.pytorch.cli to instantiate the model class and data module class.

Context

In my project, I load a Lightning checkpoint and re-instantiate both the model and datamodule using:

from lightning.pytorch.cli import instantiate_module

This approach is entirely based on the assumption that the saved checkpoint contains a _class_path entry for:

• the model class (inside hyper_parameters)
• the datamodule class (inside datamodule_hyper_parameters)

These class paths are then consumed by instantiate_module to reconstruct the objects.

Below is a simplified version of what I currently do:

from lightning.pytorch.cli import instantiate_module
import torch

ckpt = torch.load(checkpoint_path, map_location="cpu", weights_only=False)

assert "_class_path" in ckpt["hyper_parameters"]
assert "_class_path" in ckpt["datamodule_hyper_parameters"]

model = instantiate_module(
    SomeBaseModelClass,
    {k: v for k, v in ckpt["hyper_parameters"].items() if k != "_instantiator"},
)

datamodule = instantiate_module(
    XYBaseDataModule,
    {k: v for k, v in ckpt["datamodule_hyper_parameters"].items() if k != "_instantiator"},
)

This works well with recent Lightning versions, and is very convenient for fully config-driven workflows.

Questions

1. Is it guaranteed that Lightning checkpoints will always contain the _class_path key for:

   • the model class (hyper_parameters)
   • the datamodule class (datamodule_hyper_parameters)?

2. Is _class_path:

   • always present for any checkpoint saved by Lightning?
   • or only guaranteed when the checkpoint is saved via LightningCLI (or CLI-based workflows)?

3. From which Lightning version did checkpoints start reliably including _class_path?

   • My understanding is that older Lightning versions did not always include it.

4. Is relying on instantiate_module for checkpoint restoration considered a supported and future-proof pattern, or is it more of an internal/CLI-specific mechanism?

5. Can users expect this behavior to remain stable in future Lightning releases?

[aditya0by0]

Note: I understand that Lightning provides the standard way to load checkpoints via LightningModule.load_from_checkpoint(...)

However, that approach requires the model class to be known explicitly at load time.

In my use case, all model and datamodule classes are already available in the environment, and the checkpoint itself contains the corresponding _class_path. Given this, I prefer to dynamically reconstruct both the model and datamodule directly from the checkpoint metadata using instantiate_module, without hard-coding the concrete classes beforehand.

This makes the loading process fully config- and checkpoint-driven, which is why the presence and stability of _class_path in checkpoints is important for my workflow.

[mauvilsa]

However, that approach requires the model class to be known explicitly at load time.

The idea was that it is not needed to know the class. The requirement is that what is in _class_path points to a subclass of the class used to call load_from_checkpoint. So, if you always use LightningModule.load_from_checkpoint, then any checkpoint should load because all modules are subclasses of LightningModule.

[aditya0by0]

Thanks for the clarification! You’re right that this behavior works for LightningModule.load_from_checkpoint. My confusion arose because the same does not hold for LightningDataModule.load_from_checkpoint. After some analysis, I found that this is due to a bug, and I’ve raised an issue for it:

• LightningDataModule.load_from_checkpoint does not restore subclass from datamodule_hyper_parameters #21477

[aditya0by0]

To answer some of my own questions:

Questions

1. Is it guaranteed that Lightning checkpoints will always contain the _class_path key for:

   • the model class (hyper_parameters)
   • the datamodule class (datamodule_hyper_parameters)?

After inspecting the lightning code and some minor analysis, I came to conclusion that _class_path is only stored in checkpoint when LightningCLI based approach is used .

2. Is _class_path:

   • always present for any checkpoint saved by Lightning?
   • or only guaranteed when the checkpoint is saved via LightningCLI (or CLI-based workflows)?

_class_path seems a property of CLI based approach, when model and datamodule is passed through CLI command like as following

python my_cli_script.py --model=model.yaml --data=data.yaml

where model.yaml and data.yaml could be as follows containing path to the respective class

model.yaml:

classpath: base.MyModel

data.yaml:

classpath: database.MyDataClass