imbalanced-learn: Resampling Estimators That Stay Inside the scikit-learn API
A Python Package to Tackle the Curse of Imbalanced Datasets in Machine Learning
At a glance
- What is it?
- imbalanced-learn is an MIT-licensed scikit-learn-contrib package of re-sampling techniques for skewed class distributions. Its value is not the algorithms themselves but the fact that they fit, transform and sample like ordinary scikit-learn objects, which is also where its constraints begin.
- Who is it for?
- Adopt imbalanced-learn if you already build scikit-learn pipelines and need resampling that composes with cross-validation rather than a script that edits a CSV once. Do not adopt it if your imbalance is mild enough for class_weight, or if you need drift monitoring, which the package does not provide.
- Can I use it commercially?
- Yes. MIT is a permissive licence: you can use, modify and sell software built on it, as long as you keep its copyright and licence notices.
- Is it still maintained?
- Yes. The repository last received commits 78 days ago.
- What is it written in?
- Mainly Python, according to GitHub's language statistics.
Answers come from the project's GitHub data, last synced on September 15, 2026, and from our analysis. They are not legal advice.
DEEP OPEN-SOURCE ANALYSIS
The Problem It Targets: Skewed Classes, Not Skewed Metrics
The README states the premise directly: most classification algorithms perform optimally when the number of samples per class is roughly the same, and highly skewed datasets have become more common. That framing matters because it is narrower than the general complaint about imbalanced data. The package does not promise better metrics. It promises to change the training distribution so that the decision boundary is not pulled toward the majority class by sheer count.
That distinction decides who the package is for. If your minority class is 40 percent of the data, resampling is a blunt instrument and probably unnecessary. If it is 2 percent, and your model predicts the majority class for every row while still scoring well on accuracy, resampling is one of the few interventions that changes what the model sees during fitting. The README describes the goal as offsetting the imbalance to arrive at a fairer decision boundary, which is a statement about the fitted model, not about a metric you compute afterward.
The package sits under scikit-learn-contrib, the umbrella for projects that extend scikit-learn without being part of its core. That placement tells you what to expect from the API surface and what not to expect from release cadence.
What the API Actually Does: fit, transform, sample
The README does not enumerate the algorithms, pointing instead to the user guide for details. What it does establish is the compatibility claim with scikit-learn. In practice that means the samplers follow the estimator conventions: a sampler is constructed with its parameters, fitted on the training data, and then applied to produce a resampled dataset. Because they are objects rather than functions, they can be placed inside a Pipeline, which is the property that separates this package from a one-off script that oversamples a CSV before splitting.
That placement is not cosmetic. If you resample before splitting into train and test, synthetic minority points derived from the full dataset leak information across the split, and your reported score is optimistic. Keeping the sampler inside a Pipeline means it is fitted only on the training fold during cross-validation. The package's compatibility with scikit-learn is what makes that pattern available; the README does not spell out the leakage argument, but the design only pays off if you use it that way.
The README also mentions TensorFlow and Keras as optional dependencies, described as being for dealing with TensorFlow and Keras models. So the intended reach extends past pure scikit-learn estimators, though the README gives no example of how that integration looks. Treat that as unverified until you check the documentation.
Installation and the Dependency Floor
Two install paths are documented. From PyPI: pip install -U imbalanced-learn. From conda-forge: conda install -c conda-forge imbalanced-learn. The README also documents a source install: clone the repository, cd into it, then pip install . For development work it gives pip install --no-build-isolation --editable . and notes that contributors are advised to install pre-commit and run pre-commit install.
The dependency floor is explicit and worth reading before you upgrade. Python must be at least 3.10, NumPy at least 1.25.2, SciPy at least 1.11.4, and scikit-learn at least 1.4.2. Pytest 7.2.2 or newer is listed as a required dependency rather than a development extra, which is unusual for a library and means the test runner lands in your environment whether you want it or not. Optional dependencies are Pandas 2.0.3 or newer for dataframes, TensorFlow 2.16.1 or newer, and Keras 3.3.3 or newer. The examples additionally need Matplotlib 3.7.3 and Seaborn 0.12.2.
The README states endorsement of SPEC 0 from the Scientific Python Ecosystem Coordination, specifically the recommendation on minimum supported dependencies. That is a commitment about how quickly the floor moves, and it is the reason the scikit-learn minimum is pinned rather than left open. If you are locked to an older scikit-learn, check the version compatibility before installing, because the requirement is a hard floor, not a suggestion.
Testing and the Maintenance Surface
The README documents one test command: make coverage. That implies a Makefile in the repository drives the test suite through pytest and collects coverage. There is no documented command for running a single test file or a subset of tests, and no documented marker scheme for slow tests. If you plan to modify the package, expect to read the Makefile rather than follow the README.
The project states that its development process follows the scikit-learn community's, and directs contributors to scikit-learn's development guide rather than writing its own. That is a real maintenance advantage: contribution norms, review expectations and API conventions are inherited from a project with a long public history. It is also a constraint, because changes that would fit imbalanced-learn's needs but diverge from scikit-learn conventions are unlikely to be accepted.
The release history supplied shows 0.14.0 in August 2025, 0.14.1 in December 2025, and 0.14.2 in June 2026, with the last push to the default branch dated June 2026. That is a steady cadence on the 0.14 line, not a burst of activity. The practical upgrade cost is the dependency floor: a minor release that raises the minimum scikit-learn version can force an upgrade of your entire modelling stack, so pin imbalanced-learn and scikit-learn together rather than letting the resolver decide.
Where It Is the Wrong Tool
Resampling changes the data, and that has costs the README does not discuss. Synthetic minority generation produces points that were never observed. Any downstream calibration, probability estimate, or threshold you derive from the resampled fit is a property of the resampled distribution, not the original one. If your application needs calibrated probabilities, resampling is the wrong first move.
The package also does nothing about the reason many imbalanced datasets are imbalanced. If the minority class is rare because it is genuinely rare, resampling helps the model see it. If it is rare because of a labelling or collection artifact, resampling amplifies the artifact. Nothing in the package detects that distinction.
There is a scale constraint too. Resampling operates on the training set in memory. For very large datasets, generating synthetic minority samples or duplicating them multiplies the row count, and the cost lands on every fit inside your cross-validation loop. The README gives no guidance on dataset size, and the documentation does not promise any particular scaling behaviour. If your training set is already at the edge of what fits in memory, adding resampled rows is a problem the package does not solve for you.
Finally, the package addresses training-time imbalance only. It has no component for monitoring whether the class distribution shifts after deployment, and nothing in the README suggests otherwise.
The Real Alternative: class_weight in scikit-learn
The most direct alternative is scikit-learn's own class_weight parameter, available on many classifiers. The difference in approach is fundamental. class_weight leaves the training data untouched and instead changes how much each sample contributes to the loss: minority samples are weighted more heavily, majority samples less. Resampling changes the data itself, either by removing majority samples or by adding minority ones.
That difference has consequences. Weighting is cheaper, since nothing is duplicated or synthesized, and it preserves the original data distribution, so probability estimates are less distorted. Resampling gives you control that weighting cannot: you can choose exactly how many minority samples to create and by what mechanism, which matters when the minority class has internal structure worth preserving. Weighting also requires the classifier to accept the parameter, which not every estimator does; resampling works with any estimator that accepts a two-dimensional array.
A reasonable default is to try class_weight first, because it is a one-line change, and reach for imbalanced-learn when you need a specific resampling behaviour or when the estimator you are using has no weighting option. The README does not make this comparison, and it presents resampling as the answer rather than one option among several.
Licence and Citation
The package is MIT licensed, which permits use in proprietary software, modification, and redistribution provided the copyright notice and permission notice are retained. The README does not reproduce the licence text or discuss any exception, so read the LICENSE file in the repository for the exact terms. This is a description of the licence identifier, not legal advice.
The README asks that scientific publications cite the 2017 Journal of Machine Learning Research paper by Lemaitre, Nogueira and Aridas, and gives the BibTeX entry under the key JMLR:v18:16-365, volume 18, number 17, pages 1 to 5. If you use the package in academic work, that citation is the one the maintainers request. There is no separate commercial licence or contributor licence agreement mentioned, which is consistent with the MIT terms.
Editorial conclusion
Adopt imbalanced-learn if you already build scikit-learn pipelines and need resampling that composes with cross-validation rather than a script that edits a CSV once. Do not adopt it if your imbalance is mild enough for class_weight, or if you need drift monitoring, which the package does not provide. Before committing, check the user guide at imbalanced-learn.org for the sampler you intend to use and confirm it behaves inside a Pipeline, since that is the only place its compatibility claim is actually tested by your own code.
Community notes