{"library":"lightning-utilities","title":"Lightning Utilities","description":"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.","status":"active","version":"0.15.3","language":"en","source_language":"en","source_url":"https://github.com/Lightning-AI/utilities","tags":["pytorch-lightning","utilities","cli","machine-learning","devops"],"install":[{"cmd":"pip install lightning-utilities","lang":"bash","label":"Default Installation"},{"cmd":"pip install 'lightning-utilities[cli]'","lang":"bash","label":"Installation with CLI support"}],"dependencies":[{"reason":"Requires Python 3.10 or newer.","package":"python","optional":false},{"reason":"Required for the CLI functionality.","package":"jsonargparse","optional":true}],"imports":[{"note":"A utility for conditionally importing modules only if they are available.","symbol":"module_available","correct":"from lightning_utilities.core.imports import module_available"},{"note":"The `apply_to_collection` utility has been moved from `pytorch_lightning.utilities` to `lightning_utilities.core` in PyTorch Lightning v1.8.0 and higher.","wrong":"from pytorch_lightning.utilities.apply_func import apply_to_collection","symbol":"apply_to_collection","correct":"from lightning_utilities.core.apply_func import apply_to_collection"},{"note":"Provides common command-line interface (CLI) commands, e.g., for managing requirements.","symbol":"cli","correct":"import lightning_utilities.cli"}],"quickstart":{"code":"from lightning_utilities.core.apply_func import apply_to_collection\n\ndef double(x):\n    return x * 2\n\ndata = [1, {'a': 2, 'b': [3, 4]}, (5, 6)]\nresult = apply_to_collection(data, int, double)\nprint(result)\n# Expected output: [2, {'a': 4, 'b': [6, 8]}, (10, 12)]","lang":"python","description":"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."},"warnings":[{"fix":"Upgrade your Python environment to version 3.10 or later.","message":"Dropped support for Python 3.9. Users must upgrade to Python 3.10 or newer.","severity":"breaking","affected_versions":">=0.15.3"},{"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.","message":"The internal CLI backend switched from `fire` to `jsonargparse`.","severity":"breaking","affected_versions":">=0.15.0"},{"fix":"Migrate your imports from `pytorch_lightning.utilities.apply_func.apply_to_collection` to `lightning_utilities.core.apply_func.apply_to_collection`.","message":"The `apply_to_collection` utility in `pytorch_lightning.utilities.apply_func` is deprecated.","severity":"deprecated","affected_versions":"pytorch-lightning >=1.8.0"},{"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`.","message":"Using `apply_to_collection` on frozen dataclasses without explicitly setting `allow_frozen=True` can raise a `MisconfigurationException`.","severity":"gotcha","affected_versions":"All versions (behavior changed/clarified in v0.13.0)"},{"fix":"Ensure `jsonargparse` is installed either by installing `lightning-utilities[cli]` or `jsonargparse[signatures]` directly if you intend to use the CLI utilities.","message":"To use the `lightning_utilities.cli` module, you must install the library with the `[cli]` extra, i.e., `pip install 'lightning-utilities[cli]'`.","severity":"gotcha","affected_versions":"All versions with CLI functionality"}],"env_vars":null,"last_verified":"2026-04-06T00:00:00.000Z","next_check":"2026-07-05T00:00:00.000Z"}