Lightning Utilities

0.15.3 · active · verified Mon Apr 06

Lightning Utilities is a toolbox providing general Python utilities, reusable GitHub workflows, and shared GitHub actions for the broader Lightning ecosystem. It aims to offer common functionalities and development practices across Lightning-AI projects. The current version is 0.15.3, with frequent releases including patch and minor versions every few weeks.

Warnings

breaking Dropped support for Python 3.9. Users must upgrade to Python 3.10 or newer.
Fix: Upgrade your Python environment to version 3.10 or later.
breaking The internal CLI backend switched from `fire` to `jsonargparse`.
Fix: If you were directly interacting with the `lightning_utilities.cli` module, be aware that argument parsing and internal mechanisms have changed. Consult the `jsonargparse` documentation for updated CLI patterns.
deprecated The `apply_to_collection` utility in `pytorch_lightning.utilities.apply_func` is deprecated.
Fix: Migrate your imports from `pytorch_lightning.utilities.apply_func.apply_to_collection` to `lightning_utilities.core.apply_func.apply_to_collection`.
gotcha Using `apply_to_collection` on frozen dataclasses without explicitly setting `allow_frozen=True` can raise a `MisconfigurationException`.
Fix: If you intend to modify a frozen dataclass using `apply_to_collection`, ensure you pass `allow_frozen=True` to the function call. Otherwise, ensure your dataclass is not frozen or handle the `MisconfigurationException`.
gotcha To use the `lightning_utilities.cli` module, you must install the library with the `[cli]` extra, i.e., `pip install 'lightning-utilities[cli]'`.
Fix: Ensure `jsonargparse` is installed either by installing `lightning-utilities[cli]` or `jsonargparse[signatures]` directly if you intend to use the CLI utilities.

Install

pip install lightning-utilities Default Installation
pip install 'lightning-utilities[cli]' Installation with CLI support

Imports

module_available
```
from lightning_utilities.core.imports import module_available
```
A utility for conditionally importing modules only if they are available.
apply_to_collection
```
from lightning_utilities.core.apply_func import apply_to_collection
```
The `apply_to_collection` utility has been moved from `pytorch_lightning.utilities` to `lightning_utilities.core` in PyTorch Lightning v1.8.0 and higher.
cli
```
import lightning_utilities.cli
```
Provides common command-line interface (CLI) commands, e.g., for managing requirements.

Quickstart

This example demonstrates the core `apply_to_collection` utility, which recursively applies a function to all elements of a specified data type within a collection.

from lightning_utilities.core.apply_func import apply_to_collection

def double(x):
    return x * 2

data = [1, {'a': 2, 'b': [3, 4]}, (5, 6)]
result = apply_to_collection(data, int, double)
print(result)
# Expected output: [2, {'a': 4, 'b': [6, 8]}, (10, 12)]

view raw JSON →