Make pandas an optional dependency (#1831)

* Make pandas an optional dependency

* Fix mypy errors uncovered by merge

- Drop `base.utils.*` references in naive_bayes/{bernoulli,multinomial,complement}.py — mypy --strict does not treat re-exposed submodules as exported. Import `utils` directly instead.
- Add `TYPE_CHECKING` pandas import to river/tree/base.py so `pd.DataFrame` annotation resolves.
- Add type annotations to river/utils/pandas.py helpers and river/utils/test_pandas.py tests.
- Sync uv.lock with new optional-pandas dependency layout.

* Verify river works without pandas

- Add a no-pandas CI job (.github/workflows/code-quality.yml) that
  installs the dev environment, uninstalls pandas, and runs the full
  pytest suite. A conftest hook auto-skips test modules and doctest
  sources whose text mentions `import pandas`, `>>> pd.`, or
  `fetch_openml` (the latter routes through pandas inside scikit-learn).
- Lazy-load pandas in river.neural_net.mlp so importing river no longer
  pulls pandas in. The MLP estimator still requires pandas at call time;
  it now goes through utils.pandas.import_pandas() in learn_one /
  learn_many / __call__ / predict_one / predict_many.
- Update river.checks to skip the mini-batch consistency checks when
  pandas is not installed (mini-batch methods inherently need pandas).
- river.utils.pandas.import_pandas now raises an ImportError that
  points the user at `pip install "river[pandas]"`.
- Consolidate the pandas check in river.compat.river_to_sklearn to use
  river.utils.pandas.PANDAS_INSTALLED instead of its own duplicate.
- Drop the obsolete cibuildwheel TODO in pyproject.toml — pandas is now
  optional, so the comment's premise is gone.

* Cache and pre-download datasets in the no-pandas CI job

Without this step, dataset-using doctests print 'Downloading...' lines
that the doctest framework reports as unexpected output. Mirror the
existing 'ubuntu' job's cache + 'make download-datasets' steps.

* Simplify the optional-pandas helpers

- Cache `import_pandas()` with `functools.cache` so repeated calls in
  hot paths (mlp.py, naive_bayes, compose) collapse to a single dict
  lookup after the first call.
- Inline the install-hint string into the ImportError; the named
  constant added no reuse.
- Drop the "Mini-batch checks are skipped..." comment in checks; the
  `if utils.pandas.PANDAS_INSTALLED:` already says it.
- In compat.river_to_sklearn, import pandas directly inside the
  `PANDAS_INSTALLED` branch instead of going through `import_pandas()`.
  This is a module-load-time block already gated by the flag, so the
  indirection only obscured the intent.

---------

Co-authored-by: Max Halford <maxhalford25@gmail.com>

Author: zeel2104

.github/workflows/code-quality.yml

@@ -44,3 +44,32 @@ jobs:
       - name: Run pre-commit
         run: uv run pre-commit run --all-files
 
+  no-pandas:
+    name: Tests without pandas
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v5
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v7
+
+      - name: Install the project
+        run: uv sync --locked --all-extras --dev
+
+      - name: Cache datasets
+        uses: actions/cache@v4
+        with:
+          path: ~/river_data
+          key: river-data-${{ hashFiles('river/datasets/**/*.py', 'river/bandit/datasets/**/*.py', 'Makefile') }}
+          restore-keys: |
+            river-data-
+
+      - name: Download datasets
+        run: uv run make download-datasets
+
+      - name: Uninstall pandas
+        run: uv pip uninstall pandas
+
+      - name: Run tests
+        run: uv run --no-sync pytest
+

README.md

@@ -99,6 +99,12 @@ pip install river
 
 There are [wheels available](https://pypi.org/project/river/#files) for Linux, MacOS, and Windows. This means you most probably won't have to build River from source.
 
+River's core online interface (`learn_one` / `predict_one`) has no `pandas` dependency. The mini-batch interface (`learn_many`, `predict_many`, `predict_proba_many`, `transform_many`) is built on `pandas` and is opt-in:
+
+```sh
+pip install "river[pandas]"
+```
+
 You can install the latest development version from GitHub as so:
 
 ```sh

docs/introduction/installation.md

@@ -25,4 +25,18 @@ pip install git+ssh://git@github.com/online-ml/river.git --upgrade  # using SSH
 
 This method requires having Cython and Rust installed on your machine.
 
+## Mini-batch support (optional `pandas` extra)
+
+River's core online interface (`learn_one` / `predict_one`) does **not** require `pandas`. The mini-batch interface (`learn_many`, `predict_many`, `predict_proba_many`, `transform_many`) is built on top of `pandas.DataFrame` and `pandas.Series`, so `pandas` is an opt-in dependency.
+
+To install River together with `pandas`:
+
+```sh
+pip install "river[pandas]"
+# or
+uv add "river[pandas]"
+```
+
+If you call a mini-batch method without `pandas` installed, River raises an `ImportError` pointing you to this extra.
+
 Feel welcome to [open an issue on GitHub](https://github.com/online-ml/river/issues/new) if you are having any trouble.

docs/releases/unreleased.md

@@ -1,5 +1,10 @@
 # Unreleased
 
+## packaging
+
+- **Breaking:** `pandas` is no longer a hard dependency of River. The core online interface (`learn_one` / `predict_one`) works with `pip install river` alone. The mini-batch interface (`learn_many`, `predict_many`, `predict_proba_many`, `transform_many`) still requires `pandas`; install with `pip install "river[pandas]"`. Calling a `*_many` method without `pandas` raises an `ImportError` pointing to the extra.
+- Added a `no-pandas` CI job that installs River without `pandas` and runs the full test suite. A conftest hook auto-skips test modules and doctest sources that mention `pandas` (or `fetch_openml`, which goes through pandas inside scikit-learn).
+
 ## checks
 
 - Added ten new global estimator checks to `river.checks`: `check_predict_one_pure` (inference methods are pure), `check_transform_one` (transform_one is exercised and returns a dict), `check_clone_is_independent` (training the original does not mutate clones), `check_predict_many_matches_predict_one` / `check_predict_proba_many_matches_predict_proba_one` / `check_transform_many_matches_transform_one` (mini-batch ↔ one-at-a-time consistency for `base.MiniBatch*` estimators), `check_get_params_matches_signature` (`_get_params()` exposes every `__init__` keyword), `check_predict_one_before_any_learn` (cold-start inference does not crash), `check_repr_roundtrips_clone` (`repr(model) == repr(model.clone())`), `check_clone_with_new_params_applies` (`clone(new_params=...)` applies the overrides), `check_classifier_tracks_seen_labels` (`predict_proba_one` includes every label observed during training), and `check_no_state_aliasing_with_input` (mutating `x` after `learn_one` does not change model state). `_yield_datasets` now also yields a dataset for plain `base.Transformer` / `base.SupervisedTransformer` estimators, which were previously skipped by the dataset-driven checks.

pyproject.toml

@@ -8,11 +8,15 @@ readme = "README.md"
 license = "BSD-3-Clause"
 dependencies = [
     "scipy>=1.16,<2",
-    "pandas>=2.2,<3",
     "numpy>=2.3.4,<3",
     "altair>=5.0.0",
 ]
 
+[project.optional-dependencies]
+pandas = [
+    "pandas>=2.2,<3",
+]
+
 [project.urls]
 Homepage = "https://riverml.xyz/"
 Repository = "https://github.com/online-ml/river/"
@@ -30,6 +34,7 @@ dev = [
     "gymnasium>=0.29.0",
     "altair>=5.0.0",
     "mypy>=1.11.1",
+    "pandas>=2.2,<3",
     "pre-commit>=3.5.0",
     "pytest>=9.0.3",
     "ruff>=0.15.8",
@@ -82,7 +87,6 @@ default-groups = [
 
 [tool.cibuildwheel]
 build-frontend = "build[uv]"
-# TODO: re-enable 32-bit builds once pandas is removed as a dependency
 skip = ["*_i686", "*-win32", "*-musllinux_i686"]
 test-command = "python -c \"import river\""
 

river/anomaly/lof.py

@@ -1,13 +1,15 @@
 from __future__ import annotations
 
 import copy
-
-import pandas as pd
+import typing
 
 from river import anomaly
 from river.neighbors.base import DistanceFunc
 from river.utils.vectordict import euclidean_distance_dict
 
+if typing.TYPE_CHECKING:
+    import pandas as pd
+
 
 def check_equal(x_list: list, y_list: list):
     """

river/anomaly/svm.py

@@ -1,8 +1,6 @@
 from __future__ import annotations
 
-import pandas as pd
-
-from river import anomaly, linear_model, optim
+from river import anomaly, linear_model, optim, utils
 
 
 class OneClassSVM(linear_model.base.GLM, anomaly.base.AnomalyDetector):
@@ -105,6 +103,7 @@ def learn_one(self, x):
         super().learn_one(x, y=1)
 
     def learn_many(self, X):
+        pd = utils.pandas.import_pandas()
         super().learn_many(X, y=pd.Series(True, index=X.index))
 
     def score_one(self, x):

river/checks/__init__.py

@@ -146,7 +146,7 @@ def yield_checks(model: Estimator) -> typing.Iterator[typing.Callable]:
 
     """
 
-    from river import base
+    from river import base, utils
     from river.anomaly.base import AnomalyDetector
     from river.time_series.base import Forecaster
 
@@ -188,12 +188,13 @@ def yield_checks(model: Estimator) -> typing.Iterator[typing.Callable]:
     if isinstance(model, (base.Transformer, base.SupervisedTransformer)):
         dataset_checks.append(common.check_transform_one)
 
-    if isinstance(model, (base.MiniBatchClassifier, base.MiniBatchRegressor)):
-        dataset_checks.append(common.check_predict_many_matches_predict_one)
-    if isinstance(model, base.MiniBatchClassifier):
-        dataset_checks.append(common.check_predict_proba_many_matches_predict_proba_one)
-    if isinstance(model, (base.MiniBatchTransformer, base.MiniBatchSupervisedTransformer)):
-        dataset_checks.append(common.check_transform_many_matches_transform_one)
+    if utils.pandas.PANDAS_INSTALLED:
+        if isinstance(model, (base.MiniBatchClassifier, base.MiniBatchRegressor)):
+            dataset_checks.append(common.check_predict_many_matches_predict_one)
+        if isinstance(model, base.MiniBatchClassifier):
+            dataset_checks.append(common.check_predict_proba_many_matches_predict_proba_one)
+        if isinstance(model, (base.MiniBatchTransformer, base.MiniBatchSupervisedTransformer)):
+            dataset_checks.append(common.check_transform_many_matches_transform_one)
 
     if hasattr(model, "debug_one"):
         dataset_checks.append(common.check_debug_one)

river/cluster/textclust.py

@@ -3,7 +3,6 @@
 import math
 
 import numpy as np
-import pandas as pd
 
 from river import base
 
@@ -370,26 +369,28 @@ def _get_distance_matrix(self, clusters):
         ids = list(clusters.keys())
 
         # initialize all distances to 0
-        distances = pd.DataFrame(np.zeros((num_clusters, num_clusters)), columns=ids, index=ids)
+        distances = np.zeros((num_clusters, num_clusters))
+        positions = {cluster_id: pos for pos, cluster_id in enumerate(ids)}
 
         for idx, row in enumerate(ids):
             for col in ids[idx + 1 :]:
                 # use the macro-distance metric to calculate the distances to different micro-clusters
                 dist = self._macro_distance.dist(clusters[row], clusters[col], idf)
-                distances.loc[row, col] = dist
-                distances.loc[col, row] = dist
+                row_pos = positions[row]
+                col_pos = positions[col]
+                distances[row_pos, col_pos] = dist
+                distances[col_pos, row_pos] = dist
 
-        return distances
+        return ids, distances
 
     # This is a greedy implementation of single linkage agglomerative clustering. In the future we
     # will make this function more flexible
     def _agglomerative_clustering(self, micros, k):
         clusters = []
 
         ## calculate distance matrix
-        distm = self._get_distance_matrix(micros)
-
-        indices = distm.index
+        indices, distm = self._get_distance_matrix(micros)
+        positions = {cluster_id: pos for pos, cluster_id in enumerate(indices)}
 
         ## init empty clusters
         for i in range(0, len(micros)):
@@ -406,8 +407,9 @@ def _agglomerative_clustering(self, micros, k):
                     ## iterate over all clusters in sets
                     for c_i in clusters[i]:
                         for c_j in clusters[j]:
-                            if distm[c_i][c_j] < min_dist:
-                                min_dist = distm[c_i][c_j]
+                            dist = distm[positions[c_i], positions[c_j]]
+                            if dist < min_dist:
+                                min_dist = dist
                                 min_pair = (i, j)
 
             ## now merge

river/compat/river_to_sklearn.py

@@ -4,18 +4,12 @@
 import typing
 
 import numpy as np
-
-try:
-    import pandas as pd
-
-    PANDAS_INSTALLED = True
-except ImportError:
-    PANDAS_INSTALLED = False
 from sklearn import base as sklearn_base
 from sklearn import pipeline, preprocessing, utils
 from sklearn.utils.validation import validate_data
 
 from river import base, compose, stream
+from river.utils.pandas import PANDAS_INSTALLED
 
 __all__ = [
     "convert_river_to_sklearn",
@@ -30,6 +24,8 @@
 STREAM_METHODS: dict[type, typing.Callable] = {np.ndarray: stream.iter_array}
 
 if PANDAS_INSTALLED:
+    import pandas as pd
+
     STREAM_METHODS[pd.DataFrame] = stream.iter_pandas
 
 # Params passed to sklearn.utils.check_X_y and sklearn.utils.check_array