---
id: river
version: "0.25.0"
license: BSD-3-Clause
license_treatment: permissive
maintenance: active
---

# river — Online machine learning in Python

License: permissive · Maintenance: active · Downloads: 213.4K/mo

## What it is and what it does

River is a Python library for online machine learning on streaming data, designed for scenarios where models must learn continuously from new observations without revisiting historical data. It implements a wide range of algorithms—linear models, decision trees, random forests, nearest neighbors, anomaly detection, clustering, and time series forecasting—all optimized for the online learning paradigm where predictions and model updates interleave on single samples.

The library emphasizes user-friendliness and clarity over raw performance, with a core interface (`learn_one`/`predict_one`) that has no pandas dependency. It depends on scipy, numpy, and altair for visualization. River targets scenarios where concept drift matters, where production systems are event-driven, or where you need a model that adapts to new data without batch retraining. It requires Python 3.11 or above.

Use it for:

- Real-time fraud detection systems that adapt to evolving fraud patterns without retraining on historical data
- Sensor data anomaly detection in IoT deployments where data arrives continuously and must be processed one observation at a time
- Adaptive recommendation systems that learn user preferences from streaming interaction events
- Time series forecasting for stock prices or weather data where concept drift is common
- Online clustering of streaming data for customer segmentation that evolves over time
- Model validation and evaluation in production contexts where data distribution may shift

## Worth the install?

AI-flagged interpretation of the facts above — verify before relying.

River provides online machine learning algorithms that learn from streaming data one sample at a time, including linear models, decision trees, anomaly detection, clustering, and time series forecasting.

Yes. River is worth installing if you need online machine learning on streaming data—a genuinely different problem from batch learning. Active maintenance, no known vulnerabilities, permissive licensing, and prebuilt wheels across platforms make it low-friction. Start with it if concept drift, event-driven learning, or single-sample-at-a-time processing matches your use case; skip it if standard batch learning suffices.

## Install

pip install river
uv add river
poetry add river

## Installing river

Before you install: Medium install friction with prebuilt wheels for Python 3.11+ across Linux, macOS, and Windows. Active maintenance with a recent release (75 days ago) and 5916 repository stars. Core functionality has no pandas dependency; pandas support is opt-in.

License in practice: BSD-3-Clause permissive license allows commercial use, modification, and distribution with minimal restrictions, making it suitable for most production and research contexts.

Quickstart:

pip install river

from river import compose, linear_model, metrics, preprocessing

model = compose.Pipeline(
    preprocessing.StandardScaler(),
    linear_model.LogisticRegression()
)
metric = metrics.Accuracy()

for x, y in dataset:
    y_pred = model.predict_one(x)
    metric.update(y, y_pred)
    model.learn_one(x, y)

Requires Python 3.11 or above. Development installation from source requires Cython and Rust.

Verify before relying:

- Performance characteristics compared to batch learning libraries for specific use cases
- Memory footprint and scalability limits for very high-frequency streaming scenarios
- Maturity and stability of individual algorithm implementations within the library

## Package facts

- License: BSD-3-Clause (permissive)
- Python support: supports_current
- Install friction: medium
- Maintenance: active
- Downloads: 213.4K/month (top 15,000 on PyPI)
- Known vulnerabilities: none known

## Tags

online machine learning streaming, incremental learning algorithms, concept drift detection, online classification regression, stream processing machine learning, one-sample-at-a-time learning, event-based model training, streaming-ml, concept-drift, online-learning

[View on SkillFed](https://skillfed.io/packages/river) · [View on PyPI](https://pypi.org/project/river/)