---
title: Callback
description: API reference for all public classes and functions.
canonical: 'https://lightning.ai/docs/pytorch/stable/reference/extensions/callbacks'
---
# Callback {#callback}

Callbacks allow you to add arbitrary self-contained programs to your training.
At specific points during the flow of execution (hooks), the Callback interface allows you to design programs that encapsulate a full set of functionality.
It de-couples functionality that does not need to be in the [lightning module](/docs/pytorch/2.6.6/core-api/lightning_module.md) and can be shared across projects.

Lightning has a callback system to execute them when needed. Callbacks should capture NON-ESSENTIAL
logic that is NOT required for your [lightning module](/docs/pytorch/2.6.6/core-api/lightning_module.md) to run.

A complete list of Callback hooks can be found in `Callback`.

An overall Lightning system should have:

1. Trainer for all engineering
2. LightningModule for all research code.
3. Callbacks for non-essential code.

Example:

```python
from lightning.pytorch.callbacks import Callback

class MyPrintingCallback(Callback):
    def on_train_start(self, trainer, pl_module):
        print("Training is starting")

    def on_train_end(self, trainer, pl_module):
        print("Training is ending")

trainer = Trainer(callbacks=[MyPrintingCallback()])
```

We successfully extended functionality without polluting our super clean
[lightning module](/docs/pytorch/2.6.6/core-api/lightning_module.md) research code.

You can do pretty much anything with callbacks.

## Built-in Callbacks {#built-in-callbacks}

Lightning has a few built-in callbacks.

> **Note**
>
> For a richer collection of callbacks, check out our
> [bolts library](https://lightning-bolts.readthedocs.io/en/stable/index.html).

- [`BackboneFinetuning`](/docs/pytorch/2.6.6/reference/extensions/lightning.pytorch.callbacks.BackboneFinetuning.md) — Finetune a backbone model based on a learning rate user-defined scheduling.
- [`BaseFinetuning`](/docs/pytorch/2.6.6/reference/extensions/lightning.pytorch.callbacks.BaseFinetuning.md) — This class implements the base logic for writing your own Finetuning Callback.
- [`BasePredictionWriter`](/docs/pytorch/2.6.6/reference/extensions/lightning.pytorch.callbacks.BasePredictionWriter.md) — Base class to implement how the predictions should be stored.
- [`BatchSizeFinder`](/docs/pytorch/2.6.6/reference/extensions/lightning.pytorch.callbacks.BatchSizeFinder.md) — Finds the largest batch size supported by a given model before encountering an out of memory (OOM) error.
- [`Callback`](/docs/pytorch/2.6.6/reference/extensions/lightning.pytorch.callbacks.Callback.md) — Abstract base class used to build new callbacks.
- [`DeviceStatsMonitor`](/docs/pytorch/2.6.6/reference/extensions/lightning.pytorch.callbacks.DeviceStatsMonitor.md) — Automatically monitors and logs device stats during training, validation and testing stage.
DeviceStatsMonitor is a special callback as it requires a logger to passed as argument to the Trainer.
- [`EarlyStopping`](/docs/pytorch/2.6.6/reference/extensions/lightning.pytorch.callbacks.EarlyStopping.md) — Monitor a metric and stop training when it stops improving.
- [`GradientAccumulationScheduler`](/docs/pytorch/2.6.6/reference/extensions/lightning.pytorch.callbacks.GradientAccumulationScheduler.md) — Change gradient accumulation factor according to scheduling.
- [`LambdaCallback`](/docs/pytorch/2.6.6/reference/extensions/lightning.pytorch.callbacks.LambdaCallback.md) — Create a simple callback on the fly using lambda functions.
- [`LearningRateFinder`](/docs/pytorch/2.6.6/reference/extensions/lightning.pytorch.callbacks.LearningRateFinder.md) — The LearningRateFinder callback enables the user to do a range test of good initial learning rates, to
reduce the amount of guesswork in picking a good starting learning rate.
- [`LearningRateMonitor`](/docs/pytorch/2.6.6/reference/extensions/lightning.pytorch.callbacks.LearningRateMonitor.md) — Automatically monitor and logs learning rate for learning rate schedulers during training.
- [`ModelCheckpoint`](/docs/pytorch/2.6.6/reference/extensions/lightning.pytorch.callbacks.ModelCheckpoint.md) — Save the model after every epoch by monitoring a quantity. Every logged metrics are passed to the
Logger for the version it gets saved in the same directory as the
checkpoint.
- [`ModelPruning`](/docs/pytorch/2.6.6/reference/extensions/lightning.pytorch.callbacks.ModelPruning.md) — Model pruning Callback, using PyTorch’s prune utilities. This callback is responsible of pruning networks
parameters during training.
- [`ModelSummary`](/docs/pytorch/2.6.6/reference/extensions/lightning.pytorch.callbacks.ModelSummary.md) — Generates a summary of all layers in a LightningModule.
- [`ProgressBar`](/docs/pytorch/2.6.6/reference/extensions/lightning.pytorch.callbacks.ProgressBar.md) — The base class for progress bars in Lightning. It is a Callback that keeps
track of the batch progress in the Trainer. You should implement your
highly custom progress bars with this as the base class
- [`RichModelSummary`](/docs/pytorch/2.6.6/reference/extensions/lightning.pytorch.callbacks.RichModelSummary.md) — Generates a summary of all layers in a LightningModule with rich text
formatting.
- [`RichProgressBar`](/docs/pytorch/2.6.6/reference/extensions/lightning.pytorch.callbacks.RichProgressBar.md) — Create a progress bar with rich text formatting.
- [`StochasticWeightAveraging`](/docs/pytorch/2.6.6/reference/extensions/lightning.pytorch.callbacks.StochasticWeightAveraging.md) — Implements the Stochastic Weight Averaging (SWA) Callback to average a model.
- [`Timer`](/docs/pytorch/2.6.6/reference/extensions/lightning.pytorch.callbacks.Timer.md) — The Timer callback tracks the time spent in the training, validation, and test loops and interrupts the Trainer
if the given time limit for the training loop is reached.
- [`TQDMProgressBar`](/docs/pytorch/2.6.6/reference/extensions/lightning.pytorch.callbacks.TQDMProgressBar.md) — This is the default progress bar used by Lightning. It prints to stdout using the tqdm package and
shows up to four different bars:
- [`WeightAveraging`](/docs/pytorch/2.6.6/reference/extensions/lightning.pytorch.callbacks.WeightAveraging.md) — A callback that updates an averaged model for Stochastic Weight Averaging (SWA) or Exponential Moving Average
(EMA) after each training step.

## Save Callback state {#save-callback-state}

Some callbacks require internal state in order to function properly. You can optionally
choose to persist your callback's state as part of model checkpoint files using
`state_dict` and `load_state_dict`.
Note that the returned state must be able to be pickled.

When your callback is meant to be used only as a singleton callback then implementing the above two hooks is enough
to persist state effectively. However, if passing multiple instances of the callback to the Trainer is supported, then
the callback must define a `state_key` property in order for Lightning
to be able to distinguish the different states when loading the callback state. This concept is best illustrated by
the following example.

```python
class Counter(Callback):
    def __init__(self, what="epochs", verbose=True):
        self.what = what
        self.verbose = verbose
        self.state = {"epochs": 0, "batches": 0}

    @property
    def state_key(self) -> str:
        # note: we do not include `verbose` here on purpose
        return f"Counter[what={self.what}]"

    def on_train_epoch_end(self, *args, **kwargs):
        if self.what == "epochs":
            self.state["epochs"] += 1

    def on_train_batch_end(self, *args, **kwargs):
        if self.what == "batches":
            self.state["batches"] += 1

    def load_state_dict(self, state_dict):
        self.state.update(state_dict)

    def state_dict(self):
        return self.state.copy()

# two callbacks of the same type are being used
trainer = Trainer(callbacks=[Counter(what="epochs"), Counter(what="batches")])
```

A Lightning checkpoint from this Trainer with the two stateful callbacks will include the following information:

```json
{
    "state_dict": ...,
    "callbacks": {
        "Counter{'what': 'batches'}": {"batches": 32, "epochs": 0},
        "Counter{'what': 'epochs'}": {"batches": 0, "epochs": 2},
        ...
    }
}
```

The implementation of a `state_key` is essential here. If it were missing,
Lightning would not be able to disambiguate the state for these two callbacks, and `state_key`
by default only defines the class name as the key, e.g., here `Counter`.

## Best Practices {#best-practices}

The following are best practices when using/designing callbacks.

1. Callbacks should be isolated in their functionality.
2. Your callback should not rely on the behavior of other callbacks in order to work properly.
3. Do not manually call methods from the callback.
4. Directly calling methods (eg. `on_validation_end`) is strongly discouraged.
5. Whenever possible, your callbacks should not depend on the order in which they are executed.

## Entry Points {#entry-points}

Lightning supports registering Trainer callbacks directly through
[Entry Points](https://setuptools.pypa.io/en/latest/userguide/entry_point.html). Entry points allow an arbitrary
package to include callbacks that the Lightning Trainer can automatically use, without you having to add them
to the Trainer manually. This is useful in production environments where it is common to provide specialized monitoring
and logging callbacks globally for every application.

Here is a callback factory function that returns two special callbacks:

```python
def my_custom_callbacks_factory():
    return [MyCallback1(), MyCallback2()]
```

If we make this `factories.py` file into an installable package, we can define an **entry point** for this factory function.
Here is a minimal example of the `setup.py` file for the package `my-package`:

```python
from setuptools import setup

setup(
    name="my-package",
    version="0.0.1",
    install_requires=["lightning"],
    entry_points={
        "lightning.pytorch.callbacks_factory": [
            # The format here must be [any name]=[module path]:[function name]
            "monitor_callbacks=factories:my_custom_callbacks_factory"
        ]
    },
)
```

The group name for the entry points is `lightning.pytorch.callbacks_factory` and it contains a list of strings that
specify where to find the function within the package.

Now, if you `pip install -e .` this package, it will register the `my_custom_callbacks_factory` function and Lightning
will automatically call it to collect the callbacks whenever you run the Trainer!

To unregister the factory, simply uninstall the package with `pip uninstall "my-package"`.

## Callback API {#callback-api}

Here is the full API of methods available in the Callback base class.

The `Callback` class is the base for all the callbacks in Lightning just like the `LightningModule` is the base for all models.
It defines a public interface that each callback implementation must follow, the key ones are:

### Properties {#properties}

#### state_key {#state-key}

``lightning.pytorch.callbacks.Callback.state_key``

### Hooks {#hooks}

#### setup {#setup}

``lightning.pytorch.callbacks.Callback.setup``

#### teardown {#teardown}

``lightning.pytorch.callbacks.Callback.teardown``

#### on_fit_start {#on-fit-start}

``lightning.pytorch.callbacks.Callback.on_fit_start``

#### on_fit_end {#on-fit-end}

``lightning.pytorch.callbacks.Callback.on_fit_end``

#### on_sanity_check_start {#on-sanity-check-start}

``lightning.pytorch.callbacks.Callback.on_sanity_check_start``

#### on_sanity_check_end {#on-sanity-check-end}

``lightning.pytorch.callbacks.Callback.on_sanity_check_end``

#### on_train_batch_start {#on-train-batch-start}

``lightning.pytorch.callbacks.Callback.on_train_batch_start``

#### on_train_batch_end {#on-train-batch-end}

``lightning.pytorch.callbacks.Callback.on_train_batch_end``

#### on_train_epoch_start {#on-train-epoch-start}

``lightning.pytorch.callbacks.Callback.on_train_epoch_start``

#### on_train_epoch_end {#on-train-epoch-end}

``lightning.pytorch.callbacks.Callback.on_train_epoch_end``

#### on_validation_epoch_start {#on-validation-epoch-start}

``lightning.pytorch.callbacks.Callback.on_validation_epoch_start``

#### on_validation_epoch_end {#on-validation-epoch-end}

``lightning.pytorch.callbacks.Callback.on_validation_epoch_end``

#### on_test_epoch_start {#on-test-epoch-start}

``lightning.pytorch.callbacks.Callback.on_test_epoch_start``

#### on_test_epoch_end {#on-test-epoch-end}

``lightning.pytorch.callbacks.Callback.on_test_epoch_end``

#### on_predict_epoch_start {#on-predict-epoch-start}

``lightning.pytorch.callbacks.Callback.on_predict_epoch_start``

#### on_predict_epoch_end {#on-predict-epoch-end}

``lightning.pytorch.callbacks.Callback.on_predict_epoch_end``

#### on_validation_batch_start {#on-validation-batch-start}

``lightning.pytorch.callbacks.Callback.on_validation_batch_start``

#### on_validation_batch_end {#on-validation-batch-end}

``lightning.pytorch.callbacks.Callback.on_validation_batch_end``

#### on_test_batch_start {#on-test-batch-start}

``lightning.pytorch.callbacks.Callback.on_test_batch_start``

#### on_test_batch_end {#on-test-batch-end}

``lightning.pytorch.callbacks.Callback.on_test_batch_end``

#### on_predict_batch_start {#on-predict-batch-start}

``lightning.pytorch.callbacks.Callback.on_predict_batch_start``

#### on_predict_batch_end {#on-predict-batch-end}

``lightning.pytorch.callbacks.Callback.on_predict_batch_end``

#### on_train_start {#on-train-start}

``lightning.pytorch.callbacks.Callback.on_train_start``

#### on_train_end {#on-train-end}

``lightning.pytorch.callbacks.Callback.on_train_end``

#### on_validation_start {#on-validation-start}

``lightning.pytorch.callbacks.Callback.on_validation_start``

#### on_validation_end {#on-validation-end}

``lightning.pytorch.callbacks.Callback.on_validation_end``

#### on_test_start {#on-test-start}

``lightning.pytorch.callbacks.Callback.on_test_start``

#### on_test_end {#on-test-end}

``lightning.pytorch.callbacks.Callback.on_test_end``

#### on_predict_start {#on-predict-start}

``lightning.pytorch.callbacks.Callback.on_predict_start``

#### on_predict_end {#on-predict-end}

``lightning.pytorch.callbacks.Callback.on_predict_end``

#### on_exception {#on-exception}

``lightning.pytorch.callbacks.Callback.on_exception``

#### state_dict {#state-dict}

``lightning.pytorch.callbacks.Callback.state_dict``

#### on_save_checkpoint {#on-save-checkpoint}

``lightning.pytorch.callbacks.Callback.on_save_checkpoint``

#### load_state_dict {#load-state-dict}

``lightning.pytorch.callbacks.Callback.load_state_dict``

#### on_load_checkpoint {#on-load-checkpoint}

``lightning.pytorch.callbacks.Callback.on_load_checkpoint``

#### on_before_backward {#on-before-backward}

``lightning.pytorch.callbacks.Callback.on_before_backward``

#### on_after_backward {#on-after-backward}

``lightning.pytorch.callbacks.Callback.on_after_backward``

#### on_before_optimizer_step {#on-before-optimizer-step}

``lightning.pytorch.callbacks.Callback.on_before_optimizer_step``

#### on_before_zero_grad {#on-before-zero-grad}

``lightning.pytorch.callbacks.Callback.on_before_zero_grad``

---

**Navigation**

- Parent: [Extensions](/docs/pytorch/2.6.6/reference/extensions.md)