pola-rs/polars · error · ModuleNotFoundError

deltalake is not installed Please run: pip install…

Error message

deltalake is not installed

Please run: pip install deltalake

What it means

write_delta, sink_delta, and delta scan paths require the optional deltalake package. _check_if_delta_available raises ModuleNotFoundError with an install hint when the import flag _DELTALAKE_AVAILABLE is false.

Solutions

pip install deltalake
pip install 'polars[delta]' to pull the extra
Verify with python -c 'import deltalake' that the package is importable in the active interpreter

Example fix

// before
pip install polars
// after
pip install 'polars[delta]'

Defensive patterns

Strategy: validation

Validate before calling

import importlib.util
if importlib.util.find_spec('deltalake') is None:
    raise RuntimeError('deltalake not installed: pip install deltalake')

Try / catch

try:
    pl.write_delta(df, uri)
except ModuleNotFoundError as e:
    if 'deltalake' in str(e):
        raise SystemExit("Install: pip install 'polars[delta]'")

Prevention

Declare deltalake (or polars[delta]) in project dependencies
Smoke-test imports in CI before running delta jobs
Use extras when installing polars in Docker images

When it happens

Trigger: Calling pl.write_delta / pl.sink_delta / pl.scan_delta (or read_delta) in an environment where deltalake was never pip-installed.

Common situations: Fresh environments, Docker images, or CI where polars was installed without the delta extra.

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 pola-rs/polars@fe841f959e (2026-09-18). Data as JSON: /api/errors/903565625b26cf3a. Report an issue: GitHub.

Appendix: source

Thrown at py-polars/src/polars/io/delta/_utils.py:95

            version=version,
            storage_options=storage_options,
            **delta_table_options,
        )
    else:
        dl_tbl = deltalake.DeltaTable(
            table_path,
            storage_options=storage_options,
            **delta_table_options,
        )
        dl_tbl.load_as_version(version)

    return dl_tbl


def _check_if_delta_available() -> None:
    if not _DELTALAKE_AVAILABLE:
        msg = "deltalake is not installed\n\nPlease run: pip install deltalake"
        raise ModuleNotFoundError(msg)


def _check_for_unsupported_types(dtypes: list[DataType]) -> None:
    schema_dtypes = unpack_dtypes(*dtypes)
    unsupported_types = {Time, Null}
    # Note that this overlap check does NOT work correctly for Categorical, so
    # if Categorical is added back to unsupported_types a different check will
    # need to be used.

    if overlap := schema_dtypes & unsupported_types:
        msg = f"dataframe contains unsupported data types: {overlap!r}"
        raise TypeError(msg)


def _extract_table_statistics_from_delta_add_actions(
    add_actions_df: DataFrame,
    *,
    filter_columns: list[str],

View on GitHub (pinned to fe841f959e)