Description
# Lightning Utilities [](https://badge.fury.io/py/lightning-utilities) [](https://github.com/Lightning-AI/utilities/blob/main/LICENSE) [](https://pepy.tech/project/lightning-utilities) [](https://pypi.org/project/lightning-utilities/) [](https://github.com/Lightning-AI/utilities/actions/workflows/ci-testing.yml) [](https://github.com/Lightning-AI/utilities/actions/workflows/ci-use-checks.yaml) [](https://lit-utilities.readthedocs.io/en/latest/?badge=latest) [](https://results.pre-commit.ci/latest/github/Lightning-AI/utilities/main) __This repository covers the following use-cases:__ 1. _Reusable GitHub workflows_ 2. _Shared GitHub actions_ 3. _General Python utilities in `lightning_utilities.core`_ 4. _CLI `python -m lightning_utilities.cli --help`_ ## 1. Reusable workflows __Usage:__ ```yaml name: Check schema on: [push] jobs: check-schema: uses: Lightning-AI/utilities/.github/workflows/check-schema.yml@v0.5.0 with: azure-dir: "" # skip Azure check check-code: uses: Lightning-AI/utilities/.github/workflows/check-code.yml@main with: actions-ref: main # normally you shall use the same version as the workflow ``` See usage of other workflows in [.github/workflows/ci-use-checks.yaml](https://github.com/Lightning-AI/utilities/tree/main/.github/workflows/ci-use-checks.yaml). ## 2. Reusable composite actions See available composite actions [.github/actions/](https://github.com/Lightning-AI/utilities/tree/main/.github/actions). __Usage:__ ```yaml name: Do something with cache on: [push] jobs: pytest: runs-on: ubuntu-24.04 steps: - uses: actions/checkout@v3 - uses: actions/setup-python@v4 with: python-version: 3.10 - uses: Lightning-AI/utilities/.github/actions/cache with: python-version: 3.10 requires: oldest # or latest ``` ## 3. General Python utilities `lightning_utilities.core` <details> <summary>Installation</summary> From source: ```bash pip install https://github.com/Lightning-AI/utilities/archive/refs/heads/main.zip ``` From pypi: ```bash pip install lightning_utilities ``` </details> __Usage:__ Example for optional imports: ```python from lightning_utilities.core.imports import module_available if module_available("some_package.something"): from some_package import something ``` ## 4. CLI `lightning_utilities.cli` The package provides common CLI commands. <details> <summary>Installation</summary> From pypi: ```bash pip install lightning_utilities[cli] ``` </details> __Usage:__ ```bash python -m lightning_utilities.cli [group] [command] ``` <details> <summary>Example for setting min versions</summary> ```console $ cat requirements/test.txt coverage>=5.0 codecov>=2.1 pytest>=6.0 pytest-cov pytest-timeout $ python -m lightning_utilities.cli requirements set-oldest $ cat requirements/test.txt coverage==5.0 codecov==2.1 pytest==6.0 pytest-cov pytest-timeout ``` </details>
Release History
| Version | Changes | Urgency | Date |
|---|---|---|---|
| 0.15.3 | Imported from PyPI (0.15.3) | Low | 4/21/2026 |
| v0.15.3 | ## What's Changed ### Added - Added support for Python 3.14 ([#464](https://github.com/Lightning-AI/utilities/pull/464)) - Added AGENTS.md ([#428](https://github.com/Lightning-AI/utilities/pull/428)) - feat: specify standalone port ([#447](https://github.com/Lightning-AI/utilities/pull/447)) - chore(ci): add python version to build matrix ([#465](https://github.com/Lightning-AI/utilities/pull/465)) ### Changed - Dropped support for Python 3.9, now requires Python >=3.10 ([#463](ht | Low | 2/11/2026 |
| v0.15.2 | ## What's Changed * CLI: replace dependencies also in `pyproject.toml` by @Borda in https://github.com/Lightning-AI/utilities/pull/423 --- **Full Changelog**: https://github.com/Lightning-AI/utilities/compare/v0.15.1...v0.15.2 | Low | 8/6/2025 |
| v0.15.1 | ## What's Changed * fix simple scripts for `sys.argv` by @Borda in https://github.com/Lightning-AI/utilities/pull/418 * fix parsing for scripts by @Borda in https://github.com/Lightning-AI/utilities/pull/419 * fix CLI accepting optional args by @Borda in https://github.com/Lightning-AI/utilities/pull/420 --- **Full Changelog**: https://github.com/Lightning-AI/utilities/compare/v0.15.0...v0.15.1 | Low | 8/4/2025 |
| v0.15.0 | ## What's Changed * CLI: replace min dependencies also in `pyproject.toml` by @Borda in https://github.com/Lightning-AI/utilities/pull/414 * switch CLI from `fire` to `jsonargparse` by @Borda in https://github.com/Lightning-AI/utilities/pull/371 * CI: make timeout configurable for install jobs in check-package.yml by @Borda in https://github.com/Lightning-AI/utilities/pull/412 * CI: relax `markdown-link-check` by @Borda in https://github.com/Lightning-AI/utilities/pull/416 * CI: simplify | Low | 7/26/2025 |
| v0.14.3 | ## What's Changed - CI: fix parsing Azure schema by @Borda in https://github.com/Lightning-AI/utilities/pull/384 - script: update usage of coverage in standalone by @Borda in https://github.com/Lightning-AI/utilities/pull/383 - docs: fix building rtfd by @Borda in https://github.com/Lightning-AI/utilities/pull/379 --- **Full Changelog**: https://github.com/Lightning-AI/utilities/compare/v0.14.2...v0.14.3 | Low | 4/3/2025 |
| v0.14.2 | ## What's Changed * CI: fixed using schema action by @Borda in https://github.com/Lightning-AI/utilities/pull/376 --- **Full Changelog**: https://github.com/Lightning-AI/utilities/compare/v0.14.1...v0.14.2 | Low | 3/20/2025 |
| v0.14.1 | ## What's Changed * add generic testing for standalone by @Borda in https://github.com/Lightning-AI/utilities/pull/374 * fix python version parsing for stacklevel by @Borda in https://github.com/Lightning-AI/utilities/pull/375 * build(deps): update twine requirement from ==6.0.* to ==6.1.* in /requirements by @dependabot in https://github.com/Lightning-AI/utilities/pull/360 * build(deps): update check-jsonschema requirement from ==0.30.* to ==0.31.* in /requirements by @dependabot in https | Low | 3/16/2025 |
| v0.14.0 | ## What's Changed * CI: fix missing action input by @Borda in https://github.com/Lightning-AI/utilities/pull/370 * CLI: add replace package name by @Borda in https://github.com/Lightning-AI/utilities/pull/372 --- **Full Changelog**: https://github.com/Lightning-AI/utilities/compare/v0.13.0...v0.14.0 | Low | 3/7/2025 |
| v0.13.1.post0 | ## What's Changed * ci: add `azure-schema-version` by @Borda in https://github.com/Lightning-AI/utilities/pull/369 --- **Full Changelog**: https://github.com/Lightning-AI/utilities/compare/v0.13.0...v0.13.1 | Low | 3/4/2025 |
| v0.13.0 | ### Changed * CI: bump runners from `20.04` to `24.04` by @ethanwharris in https://github.com/Lightning-AI/utilities/pull/368 ### Fixed * fixed resetting dataclass's `cached_property` once `apply_to_collection` is called by @GdoongMathew in https://github.com/Lightning-AI/utilities/pull/363 --- **Full Changelog**: https://github.com/Lightning-AI/utilities/compare/v0.12.0...v0.13.0 | Low | 3/4/2025 |
| v0.12.0 | ## [0.12.0] - 2025-01-31 ### Changed - Bump minimal Python version to be 3.9 (#331) - CLI: update parsing inputs (#333) - CI: bump upload/download artifact `v4` (#344, #345) - CI: make `actions-ref` optional if used only for listing packages (#345) - CI: split install action for archive and wheel (#347) --- **Full Changelog**: https://github.com/Lightning-AI/utilities/compare/v0.11.0...v0.12.0 | Low | 1/31/2025 |
| v0.11.9 | ## [0.11.9] - 2024-11-19 ### Changed - CI: split and rename `custom-import` to `custom-import-code` (#325) ### Fixed - fixed missing package's CLI (#332) **Full Changelog**: https://github.com/Lightning-AI/utilities/compare/v0.11.8...v0.11.9 | Low | 11/19/2024 |
| v0.11.8 | ## What's Changed * ci: enable custom env. vars in pkg check by @Borda in https://github.com/Lightning-AI/utilities/pull/317 **Full Changelog**: https://github.com/Lightning-AI/utilities/compare/v0.11.7...v0.11.8 | Low | 10/15/2024 |
| v0.11.7 | ## What's Changed * ci/cron: fix inputs by @Borda in https://github.com/Lightning-AI/utilities/pull/297 * Pass `include-hidden-files: true` to `actions/upload-artifact` by @shino16 in https://github.com/Lightning-AI/utilities/pull/303 ## New Contributors * @shino16 made their first contribution in https://github.com/Lightning-AI/utilities/pull/303 **Full Changelog**: https://github.com/Lightning-AI/utilities/compare/v0.11.6...v0.11.7 | Low | 9/2/2024 |
| v0.11.6 | ## What's Changed * CI: rename `import-extras` to `custom-import` by @Borda in https://github.com/Lightning-AI/utilities/pull/287 * CI: update mypy check by @Borda in https://github.com/Lightning-AI/utilities/pull/288 * Fix parsing pre-release package versions by @awaelchli in https://github.com/Lightning-AI/utilities/pull/292 **Full Changelog**: https://github.com/Lightning-AI/utilities/compare/v0.11.5...v0.11.6 | Low | 7/23/2024 |
| v0.11.5 | ## What's Changed * Fix extras check in RequirementCache (https://github.com/Lightning-AI/utilities/pull/283) **Full Changelog**: https://github.com/Lightning-AI/utilities/compare/v0.11.4...v0.11.5 | Low | 7/15/2024 |
| v0.11.4 | ## What's Changed * Replace deprecated `pkg_resources` (https://github.com/Lightning-AI/utilities/pull/281) **Full Changelog**: https://github.com/Lightning-AI/utilities/compare/v0.11.3...v0.11.4 | Low | 7/14/2024 |
| v0.11.3.post0 | ## What's Changed ### Fixed - CI: freeze tools for Pkg action (#273) --- **Full Changelog**: https://github.com/Lightning-AI/utilities/compare/v0.11.2...v0.11.3.post0 | Low | 6/26/2024 |
| v0.11.2 | ## What's Changed ### Fixed - docs: fix parsing non-trivial package name (#247) --- **Full Changelog**: https://github.com/Lightning-AI/utilities/compare/v0.11.1...v0.11.2 | Low | 3/27/2024 |
| v0.11.1 | ## What's Changed ### Changed - docs: fix/use PyPI versions for pinning links (#243) - CI: enable setting python version for package build (#244) ### Fixed - docs: do not replace external link for itself (#245) --- **Full Changelog**: https://github.com/Lightning-AI/utilities/compare/v0.11.0...v0.11.1 | Low | 3/25/2024 |
| v0.11.0 | ## What's Changed ### Added - docs: enable pin version in links to external docs (#236) ### Changed - CI: parametrize source folder for typing check (#228) - bump `py3.8` and Ruff cleaning (#234) --- **Full Changelog**: https://github.com/Lightning-AI/utilities/compare/v0.10.1...v0.11.0 | Low | 3/18/2024 |
| v0.10.1 | ## What's Changed ### Fixed - Avoid accidental namedtuple conversion in `apply_to_collection` (#210) **Full Changelog**: https://github.com/Lightning-AI/utilities/compare/v0.10.0...v0.10.1 --- ## New Contributors * @GdoongMathew made their first contribution in #210 | Low | 1/18/2024 |
| v0.10.0 | ## What's Changed ### Added - CI: added `install-extras` in install check allowing deduplication eventual circular install dependency (#184, #185) - Added `rank_zero_only(..., default=?)` argument to return a default value on rank > 1 (#187) ### Changed - Updated/Extended the `requires` wrapper (#146) - CI: updated/extended cleaning old and/or specific caches (#159) - CI: unified/extended docs makes flows (#162) - CI: allow Other targets for building docs (#179) - CI: narrow sco | Low | 11/17/2023 |
| v0.9.0 | ## What's Changed * docs: fetch all external resources when building docs by @Borda in https://github.com/Lightning-AI/utilities/pull/142 * add requirements script by @Borda and @SkafteNicki in https://github.com/Lightning-AI/utilities/pull/132, https://github.com/Lightning-AI/utilities/pull/139 * do not erase function types in decorators by @alanhdu in https://github.com/Lightning-AI/utilities/pull/135 * CI: fix passing install flags by @Borda in https://github.com/Lightning-AI/utilities | Low | 6/29/2023 |
| v0.8.0 | ## What's Changed * More resilient `RequirementCache` that checks for module import-ability by @carmocca in https://github.com/Lightning-AI/utilities/pull/112 * Added checking markdown links by @shenoynikhil in https://github.com/Lightning-AI/utilities/pull/81 * Added requirements parser by @Borda in https://github.com/Lightning-AI/utilities/pull/107 * Make `apply_to_collection` importable from top level by @awaelchli in https://github.com/Lightning-AI/utilities/pull/120 * ci: remove dupl | Low | 3/10/2023 |
| v0.7.1 | **Full Changelog**: https://github.com/Lightning-AI/utilities/compare/v0.7.0...v0.7.1 | Low | 2/22/2023 |
| v0.7.0 | ## What's Changed * allow frozen dataclasses in `apply_to_collection` by @janEbert in https://github.com/Lightning-AI/utilities/pull/98 * ci/docs: allow passing env. variables by @Borda in https://github.com/Lightning-AI/utilities/pull/96 * fix & extend `StrEnum.from_str` by @Borda in https://github.com/Lightning-AI/utilities/pull/99 * refactor `StrEnum.from_str` by @carmocca in https://github.com/Lightning-AI/utilities/pull/102 * fix: adding `py.typed` to MANIFEST.in by @AlexanderVanEck in | Low | 2/20/2023 |
| 0.6.0.post0 | ## What's Changed * lower min `packaging` version by @Borda in https://github.com/Lightning-AI/utilities/pull/91 **Full Changelog**: https://github.com/Lightning-AI/utilities/compare/v0.6.0...0.6.0.post0 | Low | 1/25/2023 |
| v0.6.0 | ## What's Changed * Introduce ModuleAvailableCache by @awaelchli in https://github.com/Lightning-AI/utilities/pull/86 * fix calling actions in external re-usable workflows by @Borda in https://github.com/Lightning-AI/utilities/pull/51 * ci: abstract package actions by @Borda in https://github.com/Lightning-AI/utilities/pull/48 * ci: checkout submodules recursive by @justusschock in https://github.com/Lightning-AI/utilities/pull/82 * ci: using outputs & cache dispatch by @Borda in https:// | Low | 1/23/2023 |
| v0.5.0 | ## What's Changed * Fix requirements parsing by @ethanwharris in https://github.com/Lightning-AI/utilities/pull/69 * Add method to lazily import modules by @ehofesmann in https://github.com/Lightning-AI/utilities/pull/71 * add requires wrapper by @Borda in https://github.com/Lightning-AI/utilities/pull/70 * fix: Add py.typed by @AlexanderVanEck in https://github.com/Lightning-AI/utilities/pull/72 * Fix & extend pkg install check by @Borda in https://github.com/Lightning-AI/utilities/pull/76 | Low | 12/22/2022 |
| v0.4.2 | ## What's Changed * Fix MANIFEST by @carmocca in https://github.com/Lightning-AI/utilities/pull/68 **Full Changelog**: https://github.com/Lightning-AI/utilities/compare/v0.4.1...v0.4.2 | Low | 11/25/2022 |
| v0.4.1 | ## What's Changed * fixing cannot import name 'metadata' from 'importlib' by @Borda in https://github.com/Lightning-AI/utilities/pull/65 **Full Changelog**: https://github.com/Lightning-AI/utilities/compare/v0.4.0...v0.4.1 | Low | 10/31/2022 |
| v0.4.0 | ## What's Changed * Don't require `fire` as base dependency and add `lightning_tools[dev]` installation by @akihironitta in https://github.com/Lightning-AI/utilities/pull/42 * CI: pip list action by @akihironitta in https://github.com/Lightning-AI/utilities/pull/17 * CI: Add reusable workflow to clear caches within a repository by @akihironitta in https://github.com/Lightning-AI/utilities/pull/43 * CI: increase verbosity and comment schema file location by @akihironitta in https://github.com | Low | 10/28/2022 |
| v0.3.0 | ## What's Changed * Copy over the rank-zero utilities by @carmocca in https://github.com/Lightning-AI/utilities/pull/36 * Copy over `is_overridden` by @carmocca in https://github.com/Lightning-AI/utilities/pull/35 * Update version for a 0.3.0 release by @carmocca in https://github.com/Lightning-AI/utilities/pull/40 * Integrate `StrEnum` by @carmocca in https://github.com/Lightning-AI/utilities/pull/38 * Copy over `get_all_subclasses` by @carmocca in https://github.com/Lightning-AI/utilities | Low | 9/6/2022 |
| v0.2.0 | ## What's Changed * Add import utilities by @carmocca in https://github.com/Lightning-AI/utilities/pull/20 * Add import caches by @carmocca in https://github.com/Lightning-AI/utilities/pull/21 * pl-devtools -> lightning_tools by @carmocca in https://github.com/Lightning-AI/utilities/pull/27 * Fix repo link by @carmocca in https://github.com/Lightning-AI/utilities/pull/29 * lightning_tools -> lightning_utilities by @carmocca in https://github.com/Lightning-AI/utilities/pull/30 * Add core an | Low | 9/5/2022 |