Lightning-AI/pytorch-lightning · error · ModuleNotFoundError

`RichProgressBar` requires `rich` >= 10.2.2. Install it by r

Error message

`RichProgressBar` requires `rich` >= 10.2.2. Install it by running `pip install -U rich`.

What it means

RichProgressBar is an optional progress-bar callback that depends on the third-party `rich` library (>=10.2.2). Lightning marks it unavailable at import time when rich isn't installed; constructing the callback then raises ModuleNotFoundError with pip install instructions.

Source

Thrown at src/lightning/pytorch/callbacks/progress/rich_progress.py:310

        ModuleNotFoundError:
            If required `rich` package is not installed on the device.

    Note:
        PyCharm users will need to enable “emulate terminal” in output console option in
        run/debug configuration to see styled output.
        Reference: https://rich.readthedocs.io/en/latest/introduction.html#requirements

    """

    def __init__(
        self,
        refresh_rate: int = 100,
        leave: bool = False,
        theme: RichProgressBarTheme = RichProgressBarTheme(),
        console_kwargs: Optional[dict[str, Any]] = None,
    ) -> None:
        if not _RICH_AVAILABLE:
            raise ModuleNotFoundError(
                "`RichProgressBar` requires `rich` >= 10.2.2. Install it by running `pip install -U rich`."
            )

        super().__init__()
        self._refresh_rate: int = refresh_rate
        self._leave: bool = leave
        self._console: Optional[Console] = None
        self._console_kwargs = console_kwargs or {}
        self._enabled: bool = True
        self.progress: Optional[CustomProgress] = None
        self.train_progress_bar_id: Optional[TaskID]
        self.val_sanity_progress_bar_id: Optional[TaskID] = None
        self.val_progress_bar_id: Optional[TaskID]
        self.test_progress_bar_id: Optional[TaskID]
        self.predict_progress_bar_id: Optional[TaskID]
        self._reset_progress_bar_ids()
        self._metric_component: Optional[MetricsTextColumn] = None
        self._progress_stopped: bool = False

View on GitHub (pinned to 9fed5c27d2)

Solutions

  1. Run `pip install -U rich` (or `pip install lightning[rich]` if using the extras syntax) to install/upgrade rich >= 10.2.2
  2. Alternatively fall back to the default TQDMProgressBar, which needs no extra dependency
  3. Pin rich>=10.2.2 in your project requirements so environments are reproducible

Example fix

# before (ModuleNotFoundError)
trainer = pl.Trainer(callbacks=[RichProgressBar()])
# after
# pip install -U rich
trainer = pl.Trainer(callbacks=[RichProgressBar()])
# or fallback:
from lightning.pytorch.callbacks import TQDMProgressBar
trainer = pl.Trainer(callbacks=[TQDMProgressBar()])
Defensive patterns

Strategy: fallback

Validate before calling

from lightning.fabric.utilities.imports import _RICH_AVAILABLE
if not _RICH_AVAILABLE:
    progress = TQDMProgressBar()
else:
    progress = RichProgressBar()

Type guard

try:
    import rich  # noqa
    _RICH_OK = rich.__version__ >= '10.2.2'
except ImportError:
    _RICH_OK = False

Try / catch

try:
    bar = RichProgressBar()
except ModuleNotFoundError:
    bar = TQDMProgressBar()

Prevention

When it happens

Trigger: Instantiating RichProgressBar() in an environment where the `rich` package is missing or older than 10.2.2 (the import guard _RICH_AVAILABLE is False); typical in minimal/SLURM/container environments where only core requirements are installed.

Common situations: Running on a cluster or Docker image built from requirements without the 'rich' extra; using a fresh virtualenv with only torch and lightning; CI environments that skip optional dependencies.

Understand the failure class

Background: "X is not installed. Please install it with pip install Y": missing optional dependency errors — ImportError/ValueError raised when a library's optional extra was never installed — this error's family across 22 libraries.

Related errors

AI-assisted analysis of Lightning-AI/pytorch-lightning@9fed5c27d2 (2026-08-28). Data as JSON: /api/errors/b49f373b713e39d7. Report an issue: GitHub.