Deep Forest (DF21): A Cascade Forest Implementation for Tabular Data

What Deep Forest Solves and Who It Is For

Deep Forest is a tree-based ensemble method that stacks layers of forests instead of neurons. The README frames it as "an effective & powerful option to the tree-based machine learning algorithms such as Random Forest or GBDT." The stated advantages are accuracy, ease of use through fewer parameters to tune, training speed, and scalability to large data. That framing tells you who the intended user is: someone already working with tabular data and already comfortable with scikit-learn, who wants to try an ensemble that is not a random forest and not a gradient-boosted tree.

The README is also explicit about who it is not for. It states that DF21 is optimized for what a tree-based ensemble excels at, namely tabular data, and that anyone wanting the multi-grained scanning part for structured data such as images should refer to the original gcForest implementation. That is an unusually direct scoping statement, and it removes the most common misunderstanding about Deep Forest, which is that it is a general alternative to convolutional networks. In this repository, it is not.

The Two Estimators and Their scikit-learn Style Surface

The public API consists of two classes imported from the deepforest package: CascadeForestClassifier and CascadeForestRegressor. Both follow the scikit-learn estimator pattern. You construct the model with keyword arguments, call fit on training arrays, then call predict on held-out arrays. The README's classification example passes random_state=1 to the constructor, fits on X_train and y_train, and scores with accuracy_score from sklearn.metrics. The regression example does the same with mean_squared_error.

Because the interface mirrors scikit-learn, the integration cost is low: train_test_split, accuracy_score, and mean_squared_error all work without adapters. The README describes parameter tuning as a topic with its own documentation page rather than something you must do to get a first result. The design intent is that the cascade handles depth and ensemble composition internally, so the user supplies fewer hyperparameters than a gradient boosting library typically demands. Whether that holds for your dataset is something you would check against the Parameters Tunning page, not something the README demonstrates with a tuning comparison.

How the Cascade Mechanism Is Described

The README does not lay out the internal data flow step by step. What it gives is the name and the provenance: DF21 is an implementation of Deep Forest 2021.2.1, and it cites the two Zhou and Feng papers, the 2017 IJCAI conference paper and the 2019 National Science Review journal article. The cascade structure itself is defined in those papers, not in the README.

What the README does establish is the boundary of the implementation. The multi-grained scanning component, which is the part of the original Deep Forest design that converts raw structured input into feature vectors, is not the focus here. The README directs readers to the original gcForest repository for that. So the mechanism you get in this package is the cascade of forests operating on an already-tabular feature matrix. If you need to understand layer count, growth rules, or how each layer's predictions feed the next, the README will not answer it; the documentation site and the cited papers will. Treat the documentation as the primary source and the README as an entry point.

Installing and Running the Quickstart

Installation is a single pip command: pip install deep-forest. The package is distributed on PyPI, and the README links to the PyPI project page and to the Python version badge there. It does not restate a minimum Python version in prose, so the PyPI page is where you confirm compatibility with your interpreter.

The classification quickstart is short enough to quote the shape of it. Import load_digits and train_test_split from sklearn, import accuracy_score, then import CascadeForestClassifier from deepforest. Split the digits data with random_state=1, build the model with random_state=1, fit, predict, and print the accuracy. The README shows the output as 98.667 percent. The regression example uses load_boston with CascadeForestRegressor and reports an MSE of 8.068. Two notes on those numbers: they are the README's own printed output, not an independent benchmark, and load_boston has been deprecated in recent scikit-learn releases, so that example may need substitution on a current environment. Both examples set random_state=1, which is the only reproducibility lever the README demonstrates.

Where Deep Forest Is the Wrong Choice

The clearest limitation is stated by the project itself: this is not the implementation to use for images or other structured input where multi-grained scanning would matter. The README routes those users to the original gcForest repository. If your problem is computer vision or raw signal processing, DF21 is out of scope by the authors' own description.

A second constraint is the release cadence. The most recent release listed is v0.1.7 from October 2022, following v0.1.6 in September 2022 and v0.1.5 in April 2021. The repository shows a push in May 2026, so development activity on the default branch has continued past the last tagged release, but the version number is still 0.1.x. For a team that needs a stable, versioned dependency with a predictable upgrade path, that is a signal to weigh. A pre-1.0 version number does not by itself mean the code is unstable, but it does mean the maintainers have not declared the API frozen.

A third point is the licence. The repository metadata reports NOASSERTION, which means no standard licence identifier was detected. You cannot assume MIT or BSD from the metadata alone. Anyone planning to ship this inside a product needs to read the actual licence file in the repository before doing so.

How It Compares to a Gradient Boosting Library

The natural alternative is a gradient boosting implementation such as XGBoost, LightGBM, or scikit-learn's own HistGradientBoostingClassifier. The difference in approach is structural. Gradient boosting fits trees sequentially, each new tree correcting the residual error of the ensemble so far. Deep Forest, as described in the cited papers, stacks forests in layers, where each layer's output becomes input to the next. The README positions DF21 against both Random Forest and GBDT as a third option in the tree-ensemble family, and claims better accuracy than existing tree-based ensemble methods.

That claim is the project's own and the README offers no comparison table, no dataset list, and no ablation to support it. If you are choosing between Deep Forest and a boosting library, the honest position is that you would need to run both on your own data. What the README does support is a difference in tuning burden: it advertises fewer parameters to tune, which is a real cost difference if your team has limited time for hyperparameter search. A boosting library typically rewards careful tuning with better results; Deep Forest's pitch is that you get a competitive result with less of that work. Which trade you prefer depends on whether you have the tuning budget.

Maintenance, Versioning, and Licence Check

The upgrade cost here is low in interface terms, because the two estimator classes follow scikit-learn conventions and the README's examples have not changed shape across the 0.1.x line as far as the material shows. The risk is on the versioning side: with the latest tag at v0.1.7 and the repository still pre-1.0, a future release could rename or restructure the public classes without a major version bump to signal it. Pinning the version in your requirements file is the straightforward mitigation, and it costs nothing.

On licensing, the metadata reports NOASSERTION. That is not a licence grant and not a licence denial; it means the automated detection did not match a known identifier. The practical step is to open the licence file in the repository and read it, then have whoever handles compliance at your organisation confirm whether the terms fit your distribution model. This is not legal advice, and the repository metadata alone is not enough to make the call.

The documentation site at deep-forest.readthedocs.io is the place to check for parameter details and any behaviour the README omits. Given that the README defers tuning guidance to a dedicated page there, that page is where the practical detail lives, and it is worth reading before you commit to the library for a production model.

Editorial conclusion

Adopt Deep Forest if your data is tabular and you want a tree-ensemble baseline that scikit-learn's API conventions already prepared you for. Do not adopt it if you need image or structured-signal handling, since the README directs those users to the original gcForest implementation instead. Before committing, verify that your installed Python version matches what PyPI reports for deep-forest, and run the load_digits classification example to confirm the expected accuracy on your machine.

Official sources

1. Issues
2. LAMDA-NJU/Deep-Forest on GitHub
3. Project website
4. README
5. Releases