Shortcuts

Trainer

class pytorch_lightning.trainer.trainer.Trainer(logger=True, checkpoint_callback=None, enable_checkpointing=True, callbacks=None, default_root_dir=None, gradient_clip_val=None, gradient_clip_algorithm=None, process_position=0, num_nodes=1, num_processes=None, devices=None, gpus=None, auto_select_gpus=False, tpu_cores=None, ipus=None, log_gpu_memory=None, progress_bar_refresh_rate=None, enable_progress_bar=True, overfit_batches=0.0, track_grad_norm=- 1, check_val_every_n_epoch=1, fast_dev_run=False, accumulate_grad_batches=None, max_epochs=None, min_epochs=None, max_steps=- 1, min_steps=None, max_time=None, limit_train_batches=None, limit_val_batches=None, limit_test_batches=None, limit_predict_batches=None, val_check_interval=None, flush_logs_every_n_steps=None, log_every_n_steps=50, accelerator=None, strategy=None, sync_batchnorm=False, precision=32, enable_model_summary=True, weights_summary='top', weights_save_path=None, num_sanity_val_steps=2, resume_from_checkpoint=None, profiler=None, benchmark=None, deterministic=False, reload_dataloaders_every_n_epochs=0, auto_lr_find=False, replace_sampler_ddp=True, detect_anomaly=False, auto_scale_batch_size=False, prepare_data_per_node=None, plugins=None, amp_backend='native', amp_level=None, move_metrics_to_cpu=False, multiple_trainloader_mode='max_size_cycle', stochastic_weight_avg=False, terminate_on_nan=None)[source]

Bases: pytorch_lightning.trainer.callback_hook.TrainerCallbackHookMixin, pytorch_lightning.trainer.optimizers.TrainerOptimizersMixin, pytorch_lightning.trainer.data_loading.TrainerDataLoadingMixin

Customize every aspect of training via flags.

Parameters
  • accelerator (Union[str, Accelerator, None]) –

    Supports passing different accelerator types (“cpu”, “gpu”, “tpu”, “ipu”, “hpu”, “auto”) as well as custom accelerator instances.

    Deprecated since version v1.5: Passing training strategies (e.g., ‘ddp’) to accelerator has been deprecated in v1.5.0 and will be removed in v1.7.0. Please use the strategy argument instead.

  • accumulate_grad_batches (Union[int, Dict[int, int], None]) – Accumulates grads every k batches or as set up in the dict. Default: None.

  • amp_backend (str) – The mixed precision backend to use (“native” or “apex”). Default: 'native''.

  • amp_level (Optional[str]) – The optimization level to use (O1, O2, etc…). By default it will be set to “O2” if amp_backend is set to “apex”.

  • auto_lr_find (Union[bool, str]) – If set to True, will make trainer.tune() run a learning rate finder, trying to optimize initial learning for faster convergence. trainer.tune() method will set the suggested learning rate in self.lr or self.learning_rate in the LightningModule. To use a different key set a string instead of True with the key name. Default: False.

  • auto_scale_batch_size (Union[str, bool]) – If set to True, will initially run a batch size finder trying to find the largest batch size that fits into memory. The result will be stored in self.batch_size in the LightningModule. Additionally, can be set to either power that estimates the batch size through a power search or binsearch that estimates the batch size through a binary search. Default: False.

  • auto_select_gpus (bool) – If enabled and gpus is an integer, pick available gpus automatically. This is especially useful when GPUs are configured to be in “exclusive mode”, such that only one process at a time can access them. Default: False.

  • benchmark (Optional[bool]) – Sets torch.backends.cudnn.benchmark. Defaults to True if deterministic is False. Overwrite to manually set a different value. Default: None.

  • callbacks (Union[List[Callback], Callback, None]) – Add a callback or list of callbacks. Default: None.

  • checkpoint_callback (Optional[bool]) –

    If True, enable checkpointing. Default: None.

    Deprecated since version v1.5: checkpoint_callback has been deprecated in v1.5 and will be removed in v1.7. Please consider using enable_checkpointing instead.

  • enable_checkpointing (bool) – If True, enable checkpointing. It will configure a default ModelCheckpoint callback if there is no user-defined ModelCheckpoint in callbacks. Default: True.

  • check_val_every_n_epoch (int) – Check val every n train epochs. Default: 1.

  • default_root_dir (Optional[str]) – Default path for logs and weights when no logger/ckpt_callback passed. Default: os.getcwd(). Can be remote file paths such as s3://mybucket/path or ‘hdfs://path/’

  • detect_anomaly (bool) – Enable anomaly detection for the autograd engine. Default: False.

  • deterministic (bool) – If True, sets whether PyTorch operations must use deterministic algorithms. Default: False.

  • devices (Union[List[int], str, int, None]) – Will be mapped to either gpus, tpu_cores, num_processes or ipus, based on the accelerator type.

  • fast_dev_run (Union[int, bool]) – Runs n if set to n (int) else 1 if set to True batch(es) of train, val and test to find any bugs (ie: a sort of unit test). Default: False.

  • flush_logs_every_n_steps (Optional[int]) –

    How often to flush logs to disk (defaults to every 100 steps).

    Deprecated since version v1.5: flush_logs_every_n_steps has been deprecated in v1.5 and will be removed in v1.7. Please configure flushing directly in the logger instead.

  • gpus (Union[List[int], str, int, None]) – Number of GPUs to train on (int) or which GPUs to train on (list or str) applied per node Default: None.

  • gradient_clip_val (Union[int, float, None]) – The value at which to clip gradients. Passing gradient_clip_val=None disables gradient clipping. If using Automatic Mixed Precision (AMP), the gradients will be unscaled before. Default: None.

  • gradient_clip_algorithm (Optional[str]) – The gradient clipping algorithm to use. Pass gradient_clip_algorithm="value" to clip by value, and gradient_clip_algorithm="norm" to clip by norm. By default it will be set to "norm".

  • limit_train_batches (Union[int, float, None]) – How much of training dataset to check (float = fraction, int = num_batches). Default: 1.0.

  • limit_val_batches (Union[int, float, None]) – How much of validation dataset to check (float = fraction, int = num_batches). Default: 1.0.

  • limit_test_batches (Union[int, float, None]) – How much of test dataset to check (float = fraction, int = num_batches). Default: 1.0.

  • limit_predict_batches (Union[int, float, None]) – How much of prediction dataset to check (float = fraction, int = num_batches). Default: 1.0.

  • logger (Union[LightningLoggerBase, Iterable[LightningLoggerBase], bool]) – Logger (or iterable collection of loggers) for experiment tracking. A True value uses the default TensorBoardLogger. False will disable logging. If multiple loggers are provided and the save_dir property of that logger is not set, local files (checkpoints, profiler traces, etc.) are saved in default_root_dir rather than in the log_dir of any of the individual loggers. Default: True.

  • log_gpu_memory (Optional[str]) –

    None, ‘min_max’, ‘all’. Might slow performance.

    Deprecated since version v1.5: Deprecated in v1.5.0 and will be removed in v1.7.0 Please use the DeviceStatsMonitor callback directly instead.

  • log_every_n_steps (int) – How often to log within steps. Default: 50.

  • prepare_data_per_node (Optional[bool]) –

    If True, each LOCAL_RANK=0 will call prepare data. Otherwise only NODE_RANK=0, LOCAL_RANK=0 will prepare data

    Deprecated since version v1.5: Deprecated in v1.5.0 and will be removed in v1.7.0 Please set prepare_data_per_node in LightningDataModule and/or LightningModule directly instead.

  • process_position (int) –

    Orders the progress bar when running multiple models on same machine.

    Deprecated since version v1.5: process_position has been deprecated in v1.5 and will be removed in v1.7. Please pass TQDMProgressBar with process_position directly to the Trainer’s callbacks argument instead.

  • progress_bar_refresh_rate (Optional[int]) –

    How often to refresh progress bar (in steps). Value 0 disables progress bar. Ignored when a custom progress bar is passed to callbacks. Default: None, means a suitable value will be chosen based on the environment (terminal, Google COLAB, etc.).

    Deprecated since version v1.5: progress_bar_refresh_rate has been deprecated in v1.5 and will be removed in v1.7. Please pass TQDMProgressBar with refresh_rate directly to the Trainer’s callbacks argument instead. To disable the progress bar, pass enable_progress_bar = False to the Trainer.

  • enable_progress_bar (bool) – Whether to enable to progress bar by default. Default: False.

  • profiler (Union[BaseProfiler, str, None]) – To profile individual steps during training and assist in identifying bottlenecks. Default: None.

  • overfit_batches (Union[int, float]) – Overfit a fraction of training data (float) or a set number of batches (int). Default: 0.0.

  • plugins (Union[Strategy, PrecisionPlugin, ClusterEnvironment, CheckpointIO, LayerSync, str, List[Union[Strategy, PrecisionPlugin, ClusterEnvironment, CheckpointIO, LayerSync, str]], None]) – Plugins allow modification of core behavior like ddp and amp, and enable custom lightning plugins. Default: None.

  • precision (Union[int, str]) – Double precision (64), full precision (32), half precision (16) or bfloat16 precision (bf16). Can be used on CPU, GPU, TPUs, HPUs or IPUs. Default: 32.

  • max_epochs (Optional[int]) – Stop training once this number of epochs is reached. Disabled by default (None). If both max_epochs and max_steps are not specified, defaults to max_epochs = 1000. To enable infinite training, set max_epochs = -1.

  • min_epochs (Optional[int]) – Force training for at least these many epochs. Disabled by default (None).

  • max_steps (int) – Stop training after this number of steps. Disabled by default (-1). If max_steps = -1 and max_epochs = None, will default to max_epochs = 1000. To enable infinite training, set max_epochs to -1.

  • min_steps (Optional[int]) – Force training for at least these number of steps. Disabled by default (None).

  • max_time (Union[str, timedelta, Dict[str, int], None]) – Stop training after this amount of time has passed. Disabled by default (None). The time duration can be specified in the format DD:HH:MM:SS (days, hours, minutes seconds), as a datetime.timedelta, or a dictionary with keys that will be passed to datetime.timedelta.

  • num_nodes (int) – Number of GPU nodes for distributed training. Default: 1.

  • num_processes (Optional[int]) – Number of processes for distributed training with accelerator="cpu". Default: 1.

  • num_sanity_val_steps (int) – Sanity check runs n validation batches before starting the training routine. Set it to -1 to run all batches in all validation dataloaders. Default: 2.

  • reload_dataloaders_every_n_epochs (int) – Set to a non-negative integer to reload dataloaders every n epochs. Default: 0.

  • replace_sampler_ddp (bool) – Explicitly enables or disables sampler replacement. If not specified this will toggled automatically when DDP is used. By default it will add shuffle=True for train sampler and shuffle=False for val/test sampler. If you want to customize it, you can set replace_sampler_ddp=False and add your own distributed sampler.

  • resume_from_checkpoint (Union[str, Path, None]) –

    Path/URL of the checkpoint from which training is resumed. If there is no checkpoint file at the path, an exception is raised. If resuming from mid-epoch checkpoint, training will start from the beginning of the next epoch.

    Deprecated since version v1.5: resume_from_checkpoint is deprecated in v1.5 and will be removed in v2.0. Please pass the path to Trainer.fit(..., ckpt_path=...) instead.

  • strategy (Union[str, Strategy, None]) – Supports different training strategies with aliases as well custom strategies. Default: None.

  • sync_batchnorm (bool) – Synchronize batch norm layers between process groups/whole world. Default: False.

  • terminate_on_nan (Optional[bool]) –

    If set to True, will terminate training (by raising a ValueError) at the end of each training batch, if any of the parameters or the loss are NaN or +/-inf.

    Deprecated since version v1.5: Trainer argument terminate_on_nan was deprecated in v1.5 and will be removed in 1.7. Please use detect_anomaly instead.

  • detect_anomaly – Enable anomaly detection for the autograd engine. Default: False.

  • tpu_cores (Union[List[int], str, int, None]) – How many TPU cores to train on (1 or 8) / Single TPU to train on (1) Default: None.

  • ipus (Optional[int]) – How many IPUs to train on. Default: None.

  • track_grad_norm (Union[int, float, str]) – -1 no tracking. Otherwise tracks that p-norm. May be set to ‘inf’ infinity-norm. If using Automatic Mixed Precision (AMP), the gradients will be unscaled before logging them. Default: -1.

  • val_check_interval (Union[int, float, None]) – How often to check the validation set. Pass a float in the range [0.0, 1.0] to check after a fraction of the training epoch. Pass an int to check after a fixed number of training batches. Default: 1.0.

  • enable_model_summary (bool) – Whether to enable model summarization by default. Default: True.

  • weights_summary (Optional[str]) –

    Prints a summary of the weights when training begins.

    Deprecated since version v1.5: weights_summary has been deprecated in v1.5 and will be removed in v1.7. To disable the summary, pass enable_model_summary = False to the Trainer. To customize the summary, pass ModelSummary directly to the Trainer’s callbacks argument.

  • weights_save_path (Optional[str]) –

    Where to save weights if specified. Will override default_root_dir for checkpoints only. Use this if for whatever reason you need the checkpoints stored in a different place than the logs written in default_root_dir. Can be remote file paths such as s3://mybucket/path or ‘hdfs://path/’ Defaults to default_root_dir.

    Deprecated since version v1.6: weights_save_path has been deprecated in v1.6 and will be removed in v1.8. Please pass dirpath directly to the ModelCheckpoint callback.

  • move_metrics_to_cpu (bool) – Whether to force internal logged metrics to be moved to cpu. This can save some gpu memory, but can make training slower. Use with attention. Default: False.

  • multiple_trainloader_mode (str) – How to loop over the datasets when there are multiple train loaders. In ‘max_size_cycle’ mode, the trainer ends one epoch when the largest dataset is traversed, and smaller datasets reload when running out of their data. In ‘min_size’ mode, all the datasets reload when reaching the minimum length of datasets. Default: "max_size_cycle".

  • stochastic_weight_avg (bool) –

    Whether to use Stochastic Weight Averaging (SWA). Default: False.

    Deprecated since version v1.5: stochastic_weight_avg has been deprecated in v1.5 and will be removed in v1.7. Please pass StochasticWeightAveraging directly to the Trainer’s callbacks argument instead.

call_hook(hook_name, *args, pl_module=None, **kwargs)[source]

Deprecated since version v1.6: The Trainer’s call_hook method was deprecated in v1.6 and will be removed in v1.8.

Return type

Any

fit(model, train_dataloaders=None, val_dataloaders=None, datamodule=None, ckpt_path=None)[source]

Runs the full optimization routine.

Parameters
Return type

None

classmethod get_deprecated_arg_names()[source]

Returns a list with deprecated Trainer arguments.

Return type

List

predict(model=None, dataloaders=None, datamodule=None, return_predictions=None, ckpt_path=None)[source]

Run inference on your data. This will call the model forward function to compute predictions. Useful to perform distributed and batched predictions. Logging is disabled in the predict hooks.

Parameters
Return type

Union[List[Any], List[List[Any]], None]

Returns

Returns a list of dictionaries, one for each provided dataloader containing their respective predictions.

reset_predict_dataloader(model=None)[source]

Resets the predict dataloader and determines the number of batches.

Parameters

model (Optional[LightningModule]) – The LightningModule if called outside of the trainer scope.

Return type

None

reset_test_dataloader(model=None)[source]

Resets the test dataloader and determines the number of batches.

Parameters

model (Optional[LightningModule]) – The LightningModule if called outside of the trainer scope.

Return type

None

reset_train_dataloader(model=None)[source]

Resets the train dataloader and initialises required variables (number of batches, when to validate, etc.).

Parameters

model (Optional[LightningModule]) – The LightningModule if calling this outside of the trainer scope.

Return type

None

reset_train_val_dataloaders(model=None)[source]

Resets train and val dataloaders if none are attached to the trainer.

The val dataloader must be initialized before training loop starts, as the training loop inspects the val dataloader to determine whether to run the evaluation loop. :type _sphinx_paramlinks_pytorch_lightning.trainer.trainer.Trainer.reset_train_val_dataloaders.model: Optional[LightningModule] :param _sphinx_paramlinks_pytorch_lightning.trainer.trainer.Trainer.reset_train_val_dataloaders.model: The LightningModule if called outside of the trainer scope.

Return type

None

reset_val_dataloader(model=None)[source]

Resets the validation dataloader and determines the number of batches.

Parameters

model (Optional[LightningModule]) – The LightningModule if called outside of the trainer scope.

Return type

None

save_checkpoint(filepath, weights_only=False, storage_options=None)[source]

Runs routine to create a checkpoint.

Parameters
  • filepath (Union[str, Path]) – Path where checkpoint is saved.

  • weights_only (bool) – If True, will only save the model weights.

  • storage_options (Optional[Any]) – parameter for how to save to storage, passed to CheckpointIO plugin

Return type

None

test(model=None, dataloaders=None, ckpt_path=None, verbose=True, datamodule=None)[source]

Perform one evaluation epoch over the test set. It’s separated from fit to make sure you never run on your test set until you want to.

Parameters
Return type

List[Dict[str, float]]

Returns

List of dictionaries with metrics logged during the test phase, e.g., in model- or callback hooks like test_step(), test_epoch_end(), etc. The length of the list corresponds to the number of test dataloaders used.

tune(model, train_dataloaders=None, val_dataloaders=None, datamodule=None, scale_batch_size_kwargs=None, lr_find_kwargs=None)[source]

Runs routines to tune hyperparameters before training.

Parameters
Return type

Dict[str, Union[int, _LRFinder, None]]

validate(model=None, dataloaders=None, ckpt_path=None, verbose=True, datamodule=None)[source]

Perform one evaluation epoch over the validation set.

Parameters
Return type

List[Dict[str, float]]

Returns

List of dictionaries with metrics logged during the validation phase, e.g., in model- or callback hooks like validation_step(), validation_epoch_end(), etc. The length of the list corresponds to the number of validation dataloaders used.

property checkpoint_callback: Optional[pytorch_lightning.callbacks.model_checkpoint.ModelCheckpoint]

The first ModelCheckpoint callback in the Trainer.callbacks list, or None if it doesn’t exist.

Return type

Optional[ModelCheckpoint]

property checkpoint_callbacks: List[pytorch_lightning.callbacks.model_checkpoint.ModelCheckpoint]

A list of all instances of ModelCheckpoint found in the Trainer.callbacks list.

Return type

List[ModelCheckpoint]

property ckpt_path: Optional[str]

Set to the path/URL of a checkpoint loaded via fit(), validate(), test(), or predict(). None otherwise.

Return type

Optional[str]

property current_epoch: int

The current epoch, updated after the epoch end hooks are run.

Return type

int

property default_root_dir: str

The default location to save artifacts of loggers, checkpoints etc.

It is used as a fallback if logger or checkpoint callback do not define specific save paths.

Return type

str

property device_ids: List[int]

List of device indexes per node.

Return type

List[int]

property early_stopping_callback: Optional[pytorch_lightning.callbacks.early_stopping.EarlyStopping]

The first EarlyStopping callback in the Trainer.callbacks list, or None if it doesn’t exist.

Return type

Optional[EarlyStopping]

property early_stopping_callbacks: List[pytorch_lightning.callbacks.early_stopping.EarlyStopping]

A list of all instances of EarlyStopping found in the Trainer.callbacks list.

Return type

List[EarlyStopping]

property enable_validation: bool

Check if we should run validation during training.

Return type

bool

property estimated_stepping_batches: Union[int, float]

Estimated stepping batches for the complete training inferred from DataLoaders, gradient accumulation factor and distributed setup.

Examples:

def configure_optimizers(self):
    optimizer = ...
    scheduler = torch.optim.lr_scheduler.OneCycleLR(
        optimizer, max_lr=1e-3, total_steps=self.trainer.estimated_stepping_batches
    )
    return [optimizer], [scheduler]
Return type

Union[int, float]

property global_step: int

The number of optimizer steps taken (does not reset each epoch).

This includes multiple optimizers and TBPTT steps (if enabled).

Return type

int

property model: torch.nn.modules.module.Module

The LightningModule, but possibly wrapped into DataParallel or DistributedDataParallel.

To access the pure LightningModule, use lightning_module() instead.

Return type

Module

property num_devices: int

Number of devices the trainer uses per node.

Return type

int

property prediction_writer_callbacks: List[pytorch_lightning.callbacks.prediction_writer.BasePredictionWriter]

A list of all instances of BasePredictionWriter found in the Trainer.callbacks list.

Return type

List[BasePredictionWriter]

property progress_bar_callback: Optional[pytorch_lightning.callbacks.progress.base.ProgressBarBase]

An instance of ProgressBarBase found in the Trainer.callbacks list, or None if one doesn’t exist.

Return type

Optional[ProgressBarBase]

property progress_bar_dict: dict

Read-only for progress bar metrics.

Return type

dict

property weights_save_path: str

The default root location to save weights (checkpoints), e.g., when the ModelCheckpoint does not define a file path.

Deprecated since version v1.6: Trainer.weights_save_path has been deprecated in v1.6 and will be removed in v1.8.

Return type

str