pola-rs/polars · error · ModuleUpgradeRequiredError

altair>=5.4.0 is required for `.plot`

Error message

altair>=5.4.0 is required for `.plot`

What it means

Raised by Series.plot (py-polars/src/polars/series/series.py:466) when Altair is missing or older than 5.4.0. Polars implements the .plot namespace lazily and checks availability plus version (parse_version(altair.__version__) < (5,4,0)) on first access, throwing ModuleUpgradeRequiredError — a polars exception subclassing ModuleNotFoundError — so it also reads like an import error in logs.

Source

Thrown at py-polars/src/polars/series/series.py:466

        Examples
        --------
        Histogram:

        >>> s = pl.Series([1, 4, 4, 6, 2, 4, 3, 5, 5, 7, 1])
        >>> s.plot.hist()  # doctest: +SKIP

        KDE plot:

        >>> s.plot.kde()  # doctest: +SKIP

        Line plot:

        >>> s.plot.line()  # doctest: +SKIP
        """  # noqa: W505
        if not _ALTAIR_AVAILABLE or parse_version(altair.__version__) < (5, 4, 0):
            msg = "altair>=5.4.0 is required for `.plot`"
            raise ModuleUpgradeRequiredError(msg)
        return SeriesPlot(self)

    @classmethod
    def _from_pyseries(cls, pyseries: PySeries) -> Self:
        series = cls.__new__(cls)
        series._s = pyseries
        return series

    @classmethod
    @deprecated(
        "`_import_from_c` is deprecated; use `_import_arrow_from_c` instead. If "
        "you are using an extension, please compile it with the latest 'pyo3-polars'"
    )
    def _import_from_c(cls, name: str_, pointers: list_[tuple[int, int]]) -> Self:
        # `_import_from_c` was deprecated in 1.3
        return cls._from_pyseries(PySeries._import_arrow_from_c(name, pointers))

    @classmethod

View on GitHub (pinned to df599052da)

Solutions

1. Install or upgrade: pip install -U "altair>=5.4.0"
2. Pin altair in requirements/pyproject so environments are reproducible
3. In shared code, guard the plotting path: check importlib.util.find_spec('altair') and the version before calling .plot, and degrade gracefully (e.g. skip chart or fall back to matplotlib)

Example fix

# before (ModuleUpgradeRequiredError: altair>=5.4.0 is required for `.plot`)
s.plot.hist()

# after — install once:
# pip install -U "altair>=5.4.0"
s.plot.hist()

import importlib.util, importlib.metadata

def plot_available() -> bool:
    if importlib.util.find_spec("altair") is None:
        return False
    from packaging.version import Version
    return Version(importlib.metadata.version("altair")) >= Version("5.4.0")

if plot_available():
    s.plot.hist()  # type: ignore[union-attr]
else:
    print("altair>=5.4.0 not installed — skipping chart")

try:
    chart = s.plot.hist()
except ModuleNotFoundError as e:  # ModuleUpgradeRequiredError subclasses this
    if "altair" in str(e):
        raise RuntimeError("run: pip install -U 'altair>=5.4.0'") from e
    raise

When it happens

Trigger: s.plot.hist() in an environment where altair is not installed, or with altair 4.x / early 5.x (< 5.4.0) installed. Common after upgrading polars in a stale env, or on CI where altair was never added because polars itself installs without it.

Common situations: Fresh clones / Docker images / CI runners where the optional altair dependency is absent; version pins that force an old altair; sharing notebooks across machines with different envs. The error surfaces only when .plot is accessed, so imports succeed and tests pass until plotting.

Related errors

• altair>=5.4.0 is required for `.plot`
• cannot use `plot.hist` when Series name is `'count()'`
• cannot use `plot.kde` when Series name is `'density'`
• cannot call `plot.line` when Series name is 'index'
• Cannot call `plot.{attr}` when Series name is 'index'

AI-assisted analysis of pola-rs/polars@df599052da (2026-08-16). Data as JSON: /api/errors/f59079f2854da89e. Report an issue: GitHub.