reflex-dev/reflex · error · ImportError

Please install pandas to use dataframes in your app.

Error message

Please install pandas to use dataframes in your app.

What it means

Raised when a state var or default value of type pd.DataFrame is requested but pandas is not installed in the environment. reflex-base attempts `import pandas` lazily and converts the ImportError into a friendlier message telling you to install pandas. It occurs in get_default_value_for_type when generating a default for a DataFrame-annotated field.

Source

Thrown at packages/reflex-base/src/reflex_base/utils/types.py:1373

    if is_optional(t):
        return None

    origin = get_origin(t) if is_generic_alias(t) else t
    if origin is Literal:
        args = get_args(t)
        return args[0] if args else None
    if safe_issubclass(origin, TYPES_THAT_HAS_DEFAULT_VALUE):
        return origin()
    if safe_issubclass(origin, Mapping):
        return {}
    if is_dataframe(origin):
        try:
            import pandas as pd

            return pd.DataFrame()
        except ImportError as e:
            msg = "Please install pandas to use dataframes in your app."
            raise ImportError(msg) from e
    return None


IMMUTABLE_TYPES = (
    int,
    float,
    bool,
    str,
    bytes,
    frozenset,
    tuple,
    type(None),
    Enum,
)


def is_immutable(i: Any) -> bool:
    """Check if a value is immutable.

View on GitHub (pinned to 45b8ed5ab7)

Solutions

1. Install pandas into the environment Reflex runs in: uv add pandas (or pip install pandas)
2. If using Docker, add pandas to the image / requirements and rebuild
3. Verify with `uv run python -c "import pandas"` in the same environment the app runs
4. If you don't need dataframes, remove/change the DataFrame annotation causing the default lookup

Example fix

# before
class State(rx.State):
    df: pd.DataFrame  # ImportError: Please install pandas...
# after (shell)
uv add pandas

import importlib.util
if importlib.util.find_spec('pandas') is None:
    raise SystemExit('pandas is required for this app: pip install pandas')

def has_pandas() -> bool:
    import importlib.util
    return importlib.util.find_spec('pandas') is not None

try:
    import pandas as pd  # noqa: F401
except ImportError as e:
    raise SystemExit('Please install pandas to use dataframes in your app.') from e

When it happens

Trigger: Annotating state (e.g. df: pd.DataFrame) or calling code that needs a default DataFrame while pandas is absent, e.g. a fresh venv with only reflex installed, or a deployment image (Docker) that never ran `pip install pandas`.

Common situations: Deploying to a slim Docker/CI image without pandas; teammates with different lockfiles; adding pandas-dependent code locally but forgetting to add it to requirements.txt/pyproject dependencies.

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

• ChildrenTypeError(component=cls.__name__, child=child)
• Do not override _add_style directly. Use add_style instead.
• The component `{comp_name}` cannot have `{child_name}` as a
• The component `{comp_name}` only allows the components: {val
• The component `{child_name}` can only be a child of the comp

AI-assisted analysis of reflex-dev/reflex@45b8ed5ab7 (2026-08-28). Data as JSON: /api/errors/77fbefdb34305623. Report an issue: GitHub.