gevent is required for using LazyFrame.collect_async(gevent=

Error message

gevent is required for using LazyFrame.collect_async(gevent=True) orpolars.collect_all_async(gevent=True)

What it means

LazyFrame.collect_async(gevent=True) and polars.collect_all_async(gevent=True) integrate with gevent's hub via an async watcher; that integration requires the gevent package, whose availability polars determined when polars._utils.async_ was imported. This ImportError is raised in _GeventDataFrameResult.__init__ the moment gevent integration is requested but gevent is absent.

Source

Thrown at py-polars/src/polars/_utils/async_.py:29

    from collections.abc import Generator

    from polars import DataFrame
    from polars._plr import PyDataFrame


T = TypeVar("T")


class _GeventDataFrameResult(Generic[T]):
    __slots__ = ("_result", "_value", "_watcher")

    def __init__(self) -> None:
        if not _GEVENT_AVAILABLE:
            msg = (
                "gevent is required for using LazyFrame.collect_async(gevent=True) or"
                "polars.collect_all_async(gevent=True)"
            )
            raise ImportError(msg)

        from gevent.event import AsyncResult  # type: ignore[import-untyped]
        from gevent.hub import get_hub  # type: ignore[import-untyped]

        self._value: None | Exception | PyDataFrame | list[PyDataFrame] = None
        self._result = AsyncResult()

        self._watcher = get_hub().loop.async_()
        self._watcher.start(self._watcher_callback)

    def get(
        self,
        block: bool = True,  # noqa: FBT001
        timeout: float | int | None = None,
    ) -> T:
        return self.result.get(block=block, timeout=timeout)

    @property

View on GitHub (pinned to df599052da)

Solutions

Install gevent: `pip install gevent` (and add it to the deployment requirements)
Or drop `gevent=True` and use the default asyncio-based collect_async behavior
If tests don't need gevent semantics, parametrize the flag so tests run the asyncio path and only gunicorn runs gevent=True

Example fix

# before
res = lf.collect_async(gesture=False, gevent=True)  # ImportError: gevent is required ...

# after
# pip install gevent
res = lf.collect_async(gevent=True)
# or, without gevent:
res = lf.collect_async()  # asyncio-based

Defensive patterns

Strategy: validation

Validate before calling

import importlib.util

if not importlib.util.find_spec("gevent"):
    # fall back to the default asyncio-based API instead of failing
def collect(lf):
    return lf.collect_async() if importlib.util.find_spec("gevent") is None else lf.collect_async(gevent=True)

Type guard

import importlib.util

def gevent_available() -> bool:
    return importlib.util.find_spec("gevent") is not None

Try / catch

try:
    result = lf.collect_async(gevent=True)
except ImportError as e:
    if "gevent" not in str(e):
        raise
    result = lf.collect_async()  # asyncio fallback

Prevention

Add gevent to the same requirements as your gunicorn gevent worker config
Feature-flag the gevent path and default to asyncio in dev/test environments
Check importlib.util.find_spec('gevent') before requesting gevent=True

When it happens

Trigger: Calling `lf.collect_async(gevent=True)` or `pl.collect_all_async(lazy_frames, gevent=True)` in an interpreter where gevent is not installed — e.g. running code normally deployed under gunicorn+gevent workers in a plain dev shell or test runner.

Common situations: Production uses gunicorn[gevent] so gevent is present in prod but missing in dev/CI; requirements split so the web extra never reaches data-processing code paths; unit tests exercising async collect outside the gevent environment.

Related errors

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