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

Series.plot is a convenience API that wraps the Series in a SeriesPlot backed by the altair visualization library. Polars requires altair >= 5.4.0 for the `.plot` namespace, and raises ModuleUpgradeRequiredError when altair is either not installed or installed at an older version. The error exists so users get a clear, actionable message instead of an obscure AttributeError from a missing altair feature.

Solutions

1. Install or upgrade altair to at least 5.4.0: pip install -U 'altair>=5.4.0' (or pip install 'polars[plot]' which pulls in the required altair).
2. If using uv/poetry/conda, add altair>=5.4.0 to the project dependencies and re-lock (e.g. poetry add 'altair@>=5.4.0').
3. If you cannot upgrade altair, replace s.plot.line() with an explicit chart: alt.Chart(df).mark_line().encode(x=..., y=...) after converting the Series with s.to_frame().

Example fix

// before
import polars as pl
s = pl.Series('y', [1, 2, 3])
s.plot.line()  # ModuleUpgradeRequiredError: altair>=5.4.0 is required for `.plot`

// after
# pip install -U 'altair>=5.4.0'
import polars as pl
s = pl.Series('y', [1, 2, 3])
s.plot.line()  # works

import importlib.util
if importlib.util.find_spec('altair') is None or __import__('altair').__version__ < '5.4.0':
    raise RuntimeError('Install altair>=5.4.0 (pip install -U "altair>=5.4.0") before using .plot')

def can_plot() -> bool:
    try:
        import altair
        return tuple(int(p) for p in altair.__version__.split('.')[:2]) >= (5, 4)
    except ImportError:
        return False

When it happens

Trigger: Calling any method under Series.plot (e.g. s.plot.line(), s.plot.point(), s.plot.bar()) while altair is not installed, or installed at a version below 5.4.0 (the _ALTAIR_AVAILABLE flag or parse_version(altair.__version__) < (5, 4, 0) check in Series.plot fails).

Common situations: Fresh environments where polars was installed without the 'plot' extra (polars[plot]); pinned altair versions in requirements.txt/lockfiles from before the 5.4.0 release; projects that dropped altair during dependency cleanup but kept plotting code; CI images with stale cached altair wheels.

Understand the failure class

Background: "not installed", "pip install", "required for": how missing-dependency errors surface across open-source libraries — this error's family across 34 libraries.

Related errors

• Altair has no method 'mark_
• Altair has no method 'mark_
• Cannot call `plot. ` when Series name is 'index
• cannot call `plot.line` when Series name is 'index'
• cannot use `plot.hist` when Series name is `'count()'`

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

Appendix: source

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

        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
    def _import_arrow_from_c(cls, name: str_, pointers: list_[tuple[int, int]]) -> Self:
        """
        Construct a Series from Arrows C interface.

        Parameters
        ----------
        name
            The name that should be given to the `Series`.
        pointers

View on GitHub (pinned to fe841f959e)