Lightning-AI / Lightning-AI/pytorch-lightning
`add_lightning_class_args` `required` argument ignored if not using subclass mode
Nobody has claimed this yet.
- Dominant language
- Python
- Stars
- 31.4k
- Forks
- 3.8k
- Avg merge
- 6d 7h
- Merged PRs (30d)
- 6
Description
### Bug description
`LightningCLI`'s method `add_lightning_class_args` has an optional argument `required` which defaults to `True`. According to the documentation, when `required=True`, the user must specify the callback/class (or it must be default-constructable); when `required=False` it need not be. However, [the `required` argument is ignored when `subclass_mode=False`](https://github.com/Lightning-AI/pytorch-lightning/blob/dd2912a045f1a1a0c87528b41c9854fc7454d4b0/src/lightning/pytorch/cli.py#L150
) as is the default. Simple example to reproduce:
```python
from lightning.pytorch import callbacks, cli
class FooCheckpoint(callbacks.ModelCheckpoint):
# Makes one argument required so it can't be default-constructed.
def __init__(self, dirpath, *args, **kwargs):
super().__init__(dirpath, *args, **kwargs)
class FooCLI(cli.LightningCLI):
def add_arguments_to_parser(
self, parser: cli.LightningArgumentParser
) -> None:
parser.add_lightning_class_args(
FooCheckpoint,
"checkpoint",
required=False,
)
```
Attempting to instantiate `FooCLI` with any choice of model and datamodule but without specify the checkpoint's required argument will result in a configuration error:
```
Validation failed: Key "fit.checkpoint.dirpath" is required but not included in config object or its value is None.
```
I don't have the full context but the fix may be non-trivial in that when `subclass_mode=False`, [`LightningCLI` calls `add_class_arguments` from the superclass](https://github.com/Lightning-AI/pytorch-lightning/blob/dd2912a045f1a1a0c87528b41c9854fc7454d4b0/src/lightning/pytorch/cli.py#L150), namely `jsonargparse.ArgumentParser`, and [that does not seem to support a `required` argument](https://github.com/omni-us/jsonargparse/blob/dcd0a5ae70d0ef5c7c053436375bcad9aa462c84/jsonargparse/_signatures.py#L46).
At the very least though the documentation should probably be modified to explain that `required=True` is ignored unless `subclass_mode=True`.
### What version are you seeing the problem on?
v2.5
### Reproduced in studio
_No response_
### How to reproduce the bug
```python
```
### Error messages and logs
```
Validation failed: Key "fit.checkpoint.dirpath" is required but not included in config object or its value is None.
```
### Environment
Current environment
* CUDA:
- GPU:
- NVIDIA GeForce GTX 1660 Ti
- available: True
- version: 12.4
* Lightning:
- lightning: 2.5.0.post0
- lightning-cloud: 0.5.70
- lightning-utilities: 0.14.3
- pytorch-lightning: 2.5.0.post0
- torch: 2.5.1
- torchmetrics: 1.7.1
* Packages:
- accelerate: 1.7.0
- aiohappyeyeballs: 2.6.1
- aiohttp: 3.11.18
- aiosignal: 1.3.2
- anyio: 4.9.0
- arrow: 1.3.0
- asttokens: 3.0.0
- attrs: 25.3.0
- autocommand: 2.2.2
- backports.tarfile: 1.2.0
- beautifulsoup4: 4.13.4
- black: 24.10.0
- blessed: 1.21.0
- boto3: 1.38.18
- botocore: 1.38.18
- certifi: 2025.4.26
- charset-normalizer: 3.4.2
- click: 8.2.0
- croniter: 1.3.15
- dateutils: 0.6.12
- decorator: 5.1.1
- deepdiff: 7.0.1
- deprecated: 1.2.13
- docker-pycreds: 0.4.0
- docstring-parser: 0.16
- editor: 1.6.6
- executing: 0.8.3
- fastapi: 0.88.0
- filelock: 3.18.0
- flake8: 7.1.1
- frozenlist: 1.6.0
- fsspec: 2023.12.2
- gitdb: 4.0.12
- gitpython: 3.1.44
- h11: 0.16.0
- hf-xet: 1.1.2
- huggingface-hub: 0.31.2
- idna: 3.10
- importlib-metadata: 8.5.0
- importlib-resources: 6.5.2
- inflect: 7.3.1
- inquirer: 3.4.0
- ipython: 9.1.0
- ipython-pygments-lexers: 1.1.1
- itsdangerous: 2.2.0
- jaraco.collections: 5.1.0
- jaraco.context: 5.3.0
- jaraco.functools: 4.0.1
- jaraco.text: 3.12.1
- jedi: 0.19.2
- jinja2: 3.1.6
- jmespath: 1.0.1
- jsonargparse: 4.40.0
- lightning: 2.5.0.post0
- lightning-cloud: 0.5.70
- lightning-utilities: 0.14.3
- lit: 17.0.6.dev0
- markdown-it-py: 3.0.0
- markupsafe: 3.0.2
- matplotlib-inline: 0.1.6
- maxwell: 0.2.6
- mccabe: 0.7.0
- mdurl: 0.1.2
- mkl-service: 2.4.0
- more-itertools: 10.3.0
- mpmath: 1.3.0
- multidict: 6.4.3
- mypy-extensions: 1.0.0
- networkx: 3.4.2
- numpy: 2.2.6
- nvidia-cublas-cu12: 12.4.5.8
- nvidia-cuda-cupti-cu12: 12.4.127
- nvidia-cuda-nvrtc-cu12: 12.4.127
- nvidia-cuda-runtime-cu12: 12.4.127
- nvidia-cudnn-cu12: 9.1.0.70
- nvidia-cufft-cu12: 11.2.1.3
- nvidia-curand-cu12: 10.3.5.147
- nvidia-cusolver-cu12: 11.6.1.9
- nvidia-cusparse-cu12: 12.3.1.170
- nvidia-nccl-cu12: 2.21.5
- nvidia-nvjitlink-cu12: 12.4.127
- nvidia-nvtx-cu12: 12.4.127
- opentelemetry-api: 1.30.0
- ordered-set: 4.1.0
- packaging: 24.2
- parso: 0.8.4
- pathspec: 0.10.3
- pexpect: 4.8.0
- pip: 25.1
- platformdirs: 4.3.8
- prompt-toolkit: 3.0.43
- propcache: 0.3.1
- protobuf: 5.29.4
- psutil: 6.1.1
- ptyprocess: 0.7.0
- pure-eval: 0.2.2
- pycodestyle: 2.12.1
- pydantic: 1.10.22
- pyflakes: 3.2.0
- pygments: 2.19.1
- pyjwt: 2.10.1
- python-dateutil: 2.9.0.post0
- python-multipart: 0.0.20
- pytorch-lightning: 2.5.0.post0
- pytz: 2025.2
- pyyaml: 6.0.2
- readchar: 4.2.1
- regex: 2024.11.6
- requests: 2.32.3
- rich: 14.0.0
- runs: 1.2.2
- s3transfer: 0.12.0
- safetensors: 0.5.3
- sentry-sdk: 2.28.0
- setproctitle: 1.3.6
- setuptools: 78.1.1
- six: 1.17.0
- smmap: 5.0.2
- sniffio: 1.3.1
- soupsieve: 2.7
- stack-data: 0.2.0
- starlette: 0.22.0
- starsessions: 1.3.0
- sympy: 1.13.1
- tokenizers: 0.21.1
- tomli: 2.0.1
- torch: 2.5.1
- torchmetrics: 1.7.1
- tqdm: 4.67.1
- traitlets: 5.14.3
- transformers: 4.51.3
- triton: 3.1.0
- typeguard: 4.3.0
- types-python-dateutil: 2.9.0.20250516
- typeshed-client: 2.7.0
- typing-extensions: 4.12.2
- urllib3: 2.4.0
- uvicorn: 0.34.2
- wandb: 0.18.7
- wcwidth: 0.2.13
- websocket-client: 1.8.0
- websockets: 11.0.3
- wheel: 0.45.1
- wrapt: 1.17.0
- xmod: 1.8.1
- yarl: 1.20.0
- yoyodyne: 0.3.2
- yoyodyne-pretrained: 0.1.0
- zipp: 3.21.0
* System:
- OS: Linux
- architecture:
- 64bit
- ELF
- processor: x86_64
- python: 3.13.2
- release: 5.15.167.4-microsoft-standard-WSL2
- version: #1 SMP Tue Nov 5 00:21:55 UTC 2024
### More info
_No response_
cc @mauvilsa
Contributor guide
First steps
- Read the whole issue, then the project's contributing guide.
- Comment on the issue to say you are picking it up — it saves two people doing the same work.
- Fork the repository and make your change on a branch.
- Open a pull request that references the issue number.
Research direction
Start in src/lightning/pytorch/cli.py at add_lightning_class_args and compare the superclass call with jsonargparse's _signatures.py, both linked in the report. Reproduce the FooCheckpoint example with subclass_mode=False and required=False; done means the omitted checkpoint argument is accepted without the reported validation error, with behavior covered by regression testing.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- python
- Domain
- cli
- Issue type
- Bug
- Difficulty
- 3/5
- Estimated time
- 1-2 days
- Activity status
- Stale
- Clarity
- Mostly clear
- Newbie friendliness
- 38/100