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

The df.plot accessor requires altair, and specifically version >= 5.4.0 (where the required VegaFusion/plot API surface exists). If the import failed (_ALTAIR_AVAILABLE false) or the installed version parses below (5, 4, 0), polars raises polars.exceptions.ModuleUpgradeRequiredError instead of rendering a broken chart.

Source

Thrown at py-polars/src/polars/dataframe/frame.py:766

        >>> df = pl.DataFrame(
        ...     {
        ...         "day": ["Mon", "Tue", "Wed", "Thu", "Fri", "Sat", "Sun"] * 2,
        ...         "group": ["a"] * 7 + ["b"] * 7,
        ...         "value": [1, 3, 2, 4, 5, 6, 1, 1, 3, 2, 4, 5, 1, 2],
        ...     }
        ... )
        >>> df.plot.bar(
        ...     x="day", y="value", color="day", column="group"
        ... )  # doctest: +SKIP

        Or, to make a stacked version of the plot above:

        >>> df.plot.bar(x="day", y="value", color="group")  # doctest: +SKIP
        """
        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 DataFramePlot(self)

    @property
    @unstable()
    def style(self) -> GT:
        """
        Create a Great Table for styling.

        .. warning::
            This functionality is currently considered **unstable**. It may be
            changed at any point without it being considered a breaking change.

        Polars does not implement styling logic itself, but instead defers to
        the Great Tables package. Please see the `Great Tables reference <https://posit-dev.github.io/great-tables/reference/>`_
        for more information and documentation.

        Examples
        --------

View on GitHub (pinned to df599052da)

Solutions

1. pip install -U 'altair>=5.4.0'
2. Add altair to the project's plot extra/environment and rebuild the image/lockfile
3. If you cannot upgrade, gate plotting behind a version check or use df.to_pandas().plot / great_tables for tabular display

Example fix

# before (altair 5.3 installed)
df.plot.bar(x='a', y='b')  # ModuleUpgradeRequiredError

# after
# pip install -U 'altair>=5.4.0'
df.plot.bar(x='a', y='b')

import importlib.util

spec = importlib.util.find_spec('altair')
if spec is None:
    needs_install = True
else:
    import altair
    needs_install = tuple(int(p) for p in altair.__version__.split('.')[:3]) < (5, 4, 0)
if needs_install:
    print('pip install -U "altair>=5.4.0"')  # skip plotting path

from polars.exceptions import ModuleUpgradeRequiredError

try:
    chart = df.plot.bar(x='a', y='b')
except ModuleUpgradeRequiredError:
    chart = df.to_pandas().plot.bar(x='a', y='b')  # degrade gracefully

When it happens

Trigger: df.plot.bar(...), df.plot.point(...), any df.plot.<method> with altair not installed; altair 5.3.x or older pinned in the environment; a fresh venv where altair was listed as optional; altair installed but broken (import error counts as unavailable).

Common situations: Docker/CI images built from a requirements.txt that resolved an old altair; upgrading polars without upgrading altair; environments with restricted installs where the viz extra was never added (pip install 'polars[plot]').

Related errors

• altair>=5.4.0 is required for `.plot`
• could not get Databricks token: databricks-sdk is not instal
• great_tables is required for `.style`
• `read_database` queries require at least {module_name} versi
• 'pre_execution_query' is only supported in connectorx versio

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