---
title: Callback
description: Abstract base class used to build new callbacks.
canonical: >-
  https://lightning.ai/docs/pytorch/stable/optional-api/api/lightning.pytorch.callbacks.Callback
---
# Callback {#callback}

### `class lightning.pytorch.callbacks.Callback` {#lightning.pytorch.callbacks.Callback}

Bases: [`object`](https://docs.python.org/3/builtins/functions.html#object "(in Python v3.15)")

Abstract base class used to build new callbacks.

Subclass this class and override any of the relevant hooks

#### `load_state_dict(state_dict)` {#lightning.pytorch.callbacks.Callback.load_state_dict}

Called when loading a checkpoint, implement to reload callback state given callback’s `state_dict`.

Parameters:

**state\_dict** ([`dict`](https://docs.python.org/3/builtins/stdtypes.html#dict "(in Python v3.15)")\[[`str`](https://docs.python.org/3/builtins/stdtypes.html#str "(in Python v3.15)"), [`Any`](https://docs.python.org/3/library/typing.html#typing.Any "(in Python v3.15)")\]) – the callback state returned by `state_dict`.

Return type:

[`None`](https://docs.python.org/3/builtins/constants.html#None "(in Python v3.15)")

#### `on_after_backward(trainer, pl_module)` {#lightning.pytorch.callbacks.Callback.on_after_backward}

Called after `loss.backward()` and before optimizers are stepped.

Return type:

[`None`](https://docs.python.org/3/builtins/constants.html#None "(in Python v3.15)")

#### `on_before_backward(trainer, pl_module, loss)` {#lightning.pytorch.callbacks.Callback.on_before_backward}

Called before `loss.backward()`.

Return type:

[`None`](https://docs.python.org/3/builtins/constants.html#None "(in Python v3.15)")

#### `on_before_optimizer_step(trainer, pl_module, optimizer)` {#lightning.pytorch.callbacks.Callback.on_before_optimizer_step}

Called before `optimizer.step()`.

Return type:

[`None`](https://docs.python.org/3/builtins/constants.html#None "(in Python v3.15)")

#### `on_before_zero_grad(trainer, pl_module, optimizer)` {#lightning.pytorch.callbacks.Callback.on_before_zero_grad}

Called before `optimizer.zero_grad()`.

Return type:

[`None`](https://docs.python.org/3/builtins/constants.html#None "(in Python v3.15)")

#### `on_exception(trainer, pl_module, exception)` {#lightning.pytorch.callbacks.Callback.on_exception}

Called when any trainer execution is interrupted by an exception.

Return type:

[`None`](https://docs.python.org/3/builtins/constants.html#None "(in Python v3.15)")

#### `on_fit_end(trainer, pl_module)` {#lightning.pytorch.callbacks.Callback.on_fit_end}

Called when fit ends.

Return type:

[`None`](https://docs.python.org/3/builtins/constants.html#None "(in Python v3.15)")

#### `on_fit_start(trainer, pl_module)` {#lightning.pytorch.callbacks.Callback.on_fit_start}

Called when fit begins.

Return type:

[`None`](https://docs.python.org/3/builtins/constants.html#None "(in Python v3.15)")

#### `on_load_checkpoint(trainer, pl_module, checkpoint)` {#lightning.pytorch.callbacks.Callback.on_load_checkpoint}

Called when loading a model checkpoint, use to reload state.

Parameters:

*   **trainer** ([`Trainer`](/docs/pytorch/2.5.5/optional-api/api/lightning.pytorch.trainer.trainer.Trainer.md#lightning.pytorch.trainer.trainer.Trainer "lightning.pytorch.trainer.trainer.Trainer")) – the current [`Trainer`](/docs/pytorch/2.5.5/optional-api/api/lightning.pytorch.trainer.trainer.Trainer.md#lightning.pytorch.trainer.trainer.Trainer "lightning.pytorch.trainer.trainer.Trainer") instance.
    
*   **pl\_module** ([`LightningModule`](/docs/pytorch/2.5.5/optional-api/api/lightning.pytorch.core.LightningModule.md#lightning.pytorch.core.LightningModule "lightning.pytorch.core.module.LightningModule")) – the current [`LightningModule`](/docs/pytorch/2.5.5/optional-api/api/lightning.pytorch.core.LightningModule.md#lightning.pytorch.core.LightningModule "lightning.pytorch.core.LightningModule") instance.
    
*   **checkpoint** ([`dict`](https://docs.python.org/3/builtins/stdtypes.html#dict "(in Python v3.15)")\[[`str`](https://docs.python.org/3/builtins/stdtypes.html#str "(in Python v3.15)"), [`Any`](https://docs.python.org/3/library/typing.html#typing.Any "(in Python v3.15)")\]) – the full checkpoint dictionary that got loaded by the Trainer.
    

Return type:

[`None`](https://docs.python.org/3/builtins/constants.html#None "(in Python v3.15)")

#### `on_predict_batch_end(trainer, pl_module, outputs, batch, batch_idx, dataloader_idx=0)` {#lightning.pytorch.callbacks.Callback.on_predict_batch_end}

Called when the predict batch ends.

Return type:

[`None`](https://docs.python.org/3/builtins/constants.html#None "(in Python v3.15)")

#### `on_predict_batch_start(trainer, pl_module, batch, batch_idx, dataloader_idx=0)` {#lightning.pytorch.callbacks.Callback.on_predict_batch_start}

Called when the predict batch begins.

Return type:

[`None`](https://docs.python.org/3/builtins/constants.html#None "(in Python v3.15)")

#### `on_predict_end(trainer, pl_module)` {#lightning.pytorch.callbacks.Callback.on_predict_end}

Called when predict ends.

Return type:

[`None`](https://docs.python.org/3/builtins/constants.html#None "(in Python v3.15)")

#### `on_predict_epoch_end(trainer, pl_module)` {#lightning.pytorch.callbacks.Callback.on_predict_epoch_end}

Called when the predict epoch ends.

Return type:

[`None`](https://docs.python.org/3/builtins/constants.html#None "(in Python v3.15)")

#### `on_predict_epoch_start(trainer, pl_module)` {#lightning.pytorch.callbacks.Callback.on_predict_epoch_start}

Called when the predict epoch begins.

Return type:

[`None`](https://docs.python.org/3/builtins/constants.html#None "(in Python v3.15)")

#### `on_predict_start(trainer, pl_module)` {#lightning.pytorch.callbacks.Callback.on_predict_start}

Called when the predict begins.

Return type:

[`None`](https://docs.python.org/3/builtins/constants.html#None "(in Python v3.15)")

#### `on_sanity_check_end(trainer, pl_module)` {#lightning.pytorch.callbacks.Callback.on_sanity_check_end}

Called when the validation sanity check ends.

Return type:

[`None`](https://docs.python.org/3/builtins/constants.html#None "(in Python v3.15)")

#### `on_sanity_check_start(trainer, pl_module)` {#lightning.pytorch.callbacks.Callback.on_sanity_check_start}

Called when the validation sanity check starts.

Return type:

[`None`](https://docs.python.org/3/builtins/constants.html#None "(in Python v3.15)")

#### `on_save_checkpoint(trainer, pl_module, checkpoint)` {#lightning.pytorch.callbacks.Callback.on_save_checkpoint}

Called when saving a checkpoint to give you a chance to store anything else you might want to save.

Parameters:

*   **trainer** ([`Trainer`](/docs/pytorch/2.5.5/optional-api/api/lightning.pytorch.trainer.trainer.Trainer.md#lightning.pytorch.trainer.trainer.Trainer "lightning.pytorch.trainer.trainer.Trainer")) – the current [`Trainer`](/docs/pytorch/2.5.5/optional-api/api/lightning.pytorch.trainer.trainer.Trainer.md#lightning.pytorch.trainer.trainer.Trainer "lightning.pytorch.trainer.trainer.Trainer") instance.
    
*   **pl\_module** ([`LightningModule`](/docs/pytorch/2.5.5/optional-api/api/lightning.pytorch.core.LightningModule.md#lightning.pytorch.core.LightningModule "lightning.pytorch.core.module.LightningModule")) – the current [`LightningModule`](/docs/pytorch/2.5.5/optional-api/api/lightning.pytorch.core.LightningModule.md#lightning.pytorch.core.LightningModule "lightning.pytorch.core.LightningModule") instance.
    
*   **checkpoint** ([`dict`](https://docs.python.org/3/builtins/stdtypes.html#dict "(in Python v3.15)")\[[`str`](https://docs.python.org/3/builtins/stdtypes.html#str "(in Python v3.15)"), [`Any`](https://docs.python.org/3/library/typing.html#typing.Any "(in Python v3.15)")\]) – the checkpoint dictionary that will be saved.
    

Return type:

[`None`](https://docs.python.org/3/builtins/constants.html#None "(in Python v3.15)")

#### `on_test_batch_end(trainer, pl_module, outputs, batch, batch_idx, dataloader_idx=0)` {#lightning.pytorch.callbacks.Callback.on_test_batch_end}

Called when the test batch ends.

Return type:

[`None`](https://docs.python.org/3/builtins/constants.html#None "(in Python v3.15)")

#### `on_test_batch_start(trainer, pl_module, batch, batch_idx, dataloader_idx=0)` {#lightning.pytorch.callbacks.Callback.on_test_batch_start}

Called when the test batch begins.

Return type:

[`None`](https://docs.python.org/3/builtins/constants.html#None "(in Python v3.15)")

#### `on_test_end(trainer, pl_module)` {#lightning.pytorch.callbacks.Callback.on_test_end}

Called when the test ends.

Return type:

[`None`](https://docs.python.org/3/builtins/constants.html#None "(in Python v3.15)")

#### `on_test_epoch_end(trainer, pl_module)` {#lightning.pytorch.callbacks.Callback.on_test_epoch_end}

Called when the test epoch ends.

Return type:

[`None`](https://docs.python.org/3/builtins/constants.html#None "(in Python v3.15)")

#### `on_test_epoch_start(trainer, pl_module)` {#lightning.pytorch.callbacks.Callback.on_test_epoch_start}

Called when the test epoch begins.

Return type:

[`None`](https://docs.python.org/3/builtins/constants.html#None "(in Python v3.15)")

#### `on_test_start(trainer, pl_module)` {#lightning.pytorch.callbacks.Callback.on_test_start}

Called when the test begins.

Return type:

[`None`](https://docs.python.org/3/builtins/constants.html#None "(in Python v3.15)")

#### `on_train_batch_end(trainer, pl_module, outputs, batch, batch_idx)` {#lightning.pytorch.callbacks.Callback.on_train_batch_end}

Called when the train batch ends. :rtype: [`None`](https://docs.python.org/3/builtins/constants.html#None "(in Python v3.15)")

Note

The value `outputs["loss"]` here will be the normalized value w.r.t `accumulate_grad_batches` of the loss returned from `training_step`.

#### `on_train_batch_start(trainer, pl_module, batch, batch_idx)` {#lightning.pytorch.callbacks.Callback.on_train_batch_start}

Called when the train batch begins.

Return type:

[`None`](https://docs.python.org/3/builtins/constants.html#None "(in Python v3.15)")

#### `on_train_end(trainer, pl_module)` {#lightning.pytorch.callbacks.Callback.on_train_end}

Called when the train ends.

Return type:

[`None`](https://docs.python.org/3/builtins/constants.html#None "(in Python v3.15)")

#### `on_train_epoch_end(trainer, pl_module)` {#lightning.pytorch.callbacks.Callback.on_train_epoch_end}

Called when the train epoch ends.

To access all batch outputs at the end of the epoch, you can cache step outputs as an attribute of the [`lightning.pytorch.core.LightningModule`](/docs/pytorch/2.5.5/optional-api/api/lightning.pytorch.core.LightningModule.md#lightning.pytorch.core.LightningModule "lightning.pytorch.core.LightningModule") and access them in this hook:

```python
class MyLightningModule(L.LightningModule):
    def __init__(self):
        super().__init__()
        self.training_step_outputs = []

    def training_step(self):
        loss = ...
        self.training_step_outputs.append(loss)
        return loss


class MyCallback(L.Callback):
    def on_train_epoch_end(self, trainer, pl_module):
        # do something with all training_step outputs, for example:
        epoch_mean = torch.stack(pl_module.training_step_outputs).mean()
        pl_module.log("training_epoch_mean", epoch_mean)
        # free up the memory
        pl_module.training_step_outputs.clear()
```

Return type:

[`None`](https://docs.python.org/3/builtins/constants.html#None "(in Python v3.15)")

#### `on_train_epoch_start(trainer, pl_module)` {#lightning.pytorch.callbacks.Callback.on_train_epoch_start}

Called when the train epoch begins.

Return type:

[`None`](https://docs.python.org/3/builtins/constants.html#None "(in Python v3.15)")

#### `on_train_start(trainer, pl_module)` {#lightning.pytorch.callbacks.Callback.on_train_start}

Called when the train begins.

Return type:

[`None`](https://docs.python.org/3/builtins/constants.html#None "(in Python v3.15)")

#### `on_validation_batch_end(trainer, pl_module, outputs, batch, batch_idx, dataloader_idx=0)` {#lightning.pytorch.callbacks.Callback.on_validation_batch_end}

Called when the validation batch ends.

Return type:

[`None`](https://docs.python.org/3/builtins/constants.html#None "(in Python v3.15)")

#### `on_validation_batch_start(trainer, pl_module, batch, batch_idx, dataloader_idx=0)` {#lightning.pytorch.callbacks.Callback.on_validation_batch_start}

Called when the validation batch begins.

Return type:

[`None`](https://docs.python.org/3/builtins/constants.html#None "(in Python v3.15)")

#### `on_validation_end(trainer, pl_module)` {#lightning.pytorch.callbacks.Callback.on_validation_end}

Called when the validation loop ends.

Return type:

[`None`](https://docs.python.org/3/builtins/constants.html#None "(in Python v3.15)")

#### `on_validation_epoch_end(trainer, pl_module)` {#lightning.pytorch.callbacks.Callback.on_validation_epoch_end}

Called when the val epoch ends.

Return type:

[`None`](https://docs.python.org/3/builtins/constants.html#None "(in Python v3.15)")

#### `on_validation_epoch_start(trainer, pl_module)` {#lightning.pytorch.callbacks.Callback.on_validation_epoch_start}

Called when the val epoch begins.

Return type:

[`None`](https://docs.python.org/3/builtins/constants.html#None "(in Python v3.15)")

#### `on_validation_start(trainer, pl_module)` {#lightning.pytorch.callbacks.Callback.on_validation_start}

Called when the validation loop begins.

Return type:

[`None`](https://docs.python.org/3/builtins/constants.html#None "(in Python v3.15)")

#### `setup(trainer, pl_module, stage)` {#lightning.pytorch.callbacks.Callback.setup}

Called when fit, validate, test, predict, or tune begins.

Return type:

[`None`](https://docs.python.org/3/builtins/constants.html#None "(in Python v3.15)")

#### `state_dict()` {#lightning.pytorch.callbacks.Callback.state_dict}

Called when saving a checkpoint, implement to generate callback’s `state_dict`.

Return type:

[`dict`](https://docs.python.org/3/builtins/stdtypes.html#dict "(in Python v3.15)")\[[`str`](https://docs.python.org/3/builtins/stdtypes.html#str "(in Python v3.15)"), [`Any`](https://docs.python.org/3/library/typing.html#typing.Any "(in Python v3.15)")\]

Returns:

A dictionary containing callback state.

#### `teardown(trainer, pl_module, stage)` {#lightning.pytorch.callbacks.Callback.teardown}

Called when fit, validate, test, predict, or tune ends.

Return type:

[`None`](https://docs.python.org/3/builtins/constants.html#None "(in Python v3.15)")

#### `property state_key: str` {#lightning.pytorch.callbacks.Callback.state_key}

Identifier for the state of the callback.

Used to store and retrieve a callback’s state from the checkpoint dictionary by `checkpoint["callbacks"][state_key]`. Implementations of a callback need to provide a unique state key if 1) the callback has state and 2) it is desired to maintain the state of multiple instances of that callback.

---

**Navigation**

- Parent: [Api](/docs/pytorch/2.5.5/optional-api/api.md)