Install & Compatibility
Where this runs
tested against v0.1.6 · pip install
no network on importno background threads
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
muslpy 3.10–3.95 runs
build_error
glibcpy 3.10–3.95 runs
installs and imports cleanly · install 9.8s · import 4.028s · 270MB
280MB installed
● package 280MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
_fit_context
✓ from sklearn_compat.base import _fit_context
Use this decorator on the `fit` method of custom estimators to handle parameter validation consistently across scikit-learn versions (especially from 1.2+).
validate_params
✓ from sklearn_compat.utils import validate_params
Use this decorator for functions that require parameter validation consistent with scikit-learn's conventions across different versions.
is_clusterer
✓ from sklearn_compat.base import is_clusterer
Back-ported utility to check if an estimator is a clusterer, ensuring consistent behavior across scikit-learn versions.
_check_targets
✓ from sklearn_compat.utils import _check_targets
Utility to ensure consistent handling of targets (`y`) across scikit-learn versions, particularly important for changes introduced in scikit-learn 1.8 where it might output 4 parameters.
This quickstart demonstrates how to create a scikit-learn compatible estimator using `sklearn-compat`'s `_fit_context` decorator. This decorator helps developers ensure their custom estimators correctly handle parameter validation and `fit` method behavior across different scikit-learn versions, particularly those after 1.2.
from sklearn.base import BaseEstimator, ClassifierMixin
from sklearn_compat.base import _fit_context
from sklearn.utils.validation import check_is_fitted
import numpy as np
class MyCompatibleClassifier(BaseEstimator, ClassifierMixin):
# The _fit_context decorator ensures proper parameter validation
# and handling consistent with scikit-learn's internal mechanisms
# across different versions (e.g., 1.2+).
@_fit_context(prefer_skip_nested_validation=True)
def fit(self, X, y):
if not isinstance(X, np.ndarray):
X = np.asarray(X)
if not isinstance(y, np.ndarray):
y = np.asarray(y)
self.classes_ = np.unique(y)
self.n_features_in_ = X.shape[1]
self.is_fitted_ = True
return self
def predict(self, X):
check_is_fitted(self)
# A simple prediction logic for demonstration
return np.full(X.shape[0], self.classes_[0])
# Example usage of the compatible classifier
X_train = np.array([[1, 2], [3, 4], [5, 6]])
y_train = np.array([0, 1, 0])
clf = MyCompatibleClassifier()
clf.fit(X_train, y_train)
print(f"Fitted classes: {clf.classes_}")
print(f"Predicted for [[7, 8]]: {clf.predict(np.array([[7, 8]]))}")
Debug
Known issues
breakingDirectly importing internal utilities from `sklearn` for multi-version support can lead to breaking changes as scikit-learn's internal API is not stable. `sklearn-compat` exists to provide stable compatibility layers.fixAlways import compatibility utilities like `_fit_context` or `validate_params` from `sklearn_compat.base` or `sklearn_compat.utils` instead of directly from `sklearn`'s internal modules.
affects: All scikit-learn versions (when trying to support multiple versions without sklearn-compat)
gotchaWhen trying to support `scikit-learn >= 1.2`, parameter validation for estimators and functions changed. Not using `_fit_context` on estimator's `fit` methods or `validate_params` on functions can lead to inconsistent behavior or failures.fixDecorate the `fit` method of your custom `BaseEstimator` with `from sklearn_compat.base import _fit_context`. For functions requiring validation, use `from sklearn_compat.utils import validate_params`.
affects: scikit-learn >= 1.2
gotchaScikit-learn 1.8 introduced changes to internal utilities like `_check_targets`, which now outputs 4 parameters. If your custom code expects a different signature, it will break.fixUse the `_check_targets` utility from `sklearn_compat.utils` to ensure consistent target checking that adapts to different scikit-learn versions.
affects: scikit-learn 1.8+
gotchaIn scikit-learn 1.5, many developer utilities were moved to dedicated modules. Importing them directly by their old paths will fail in newer versions.fix`sklearn-compat` provides a compatibility layer, so always use the `sklearn_compat` provided paths for these utilities to avoid needing version checks or conditional imports.
affects: scikit-learn 1.5+
gotchaThe `sklearn-compat` library offers a 'vendored' version in `src/sklearn_compat/_sklearn_compat.py` for those who prefer not to add a direct package dependency. Mixing the vendored version with an installed `sklearn-compat` package or using outdated vendored code can lead to conflicts or missed updates.fixDecide on a single approach: either install `sklearn-compat` via pip and depend on it, or explicitly vendor a specific version. Do not mix both, and ensure vendored code is kept up-to-date with `sklearn-compat` releases.
affects: All versions
Errors
Common errors & fixes
ModuleNotFoundError: No module named 'sklearn_compat'
The 'sklearn-compat' package has not been installed in your current Python environment.
fixpip install sklearn-compat
ImportError: cannot import name '_safe_split' from 'sklearn_compat'
The '_safe_split' function is located within the 'sklearn_compat.utils' submodule, not directly in the top-level 'sklearn_compat' package.
fixfrom sklearn_compat.utils import _safe_split
ImportError: cannot import name 'check_init_args' from 'sklearn_compat'
The 'check_init_args' function is located within the 'sklearn_compat.tests.common' submodule, not directly in the top-level 'sklearn_compat' package.
fixfrom sklearn_compat.tests.common import check_init_args
TypeError: check_init_args() missing 1 required positional argument: 'estimator'
The 'check_init_args' function requires an estimator class as its first argument but was called without it.
fixfrom sklearn_compat.tests.common import check_init_args
# Assuming MyEstimatorClass is your estimator class
check_init_args(MyEstimatorClass)
Upgrade
Version history
0.1.6latest on PyPI · released Jun 7, 2026
Audit
Dependencies
scikit-learnrequiredCore dependency; the library provides compatibility layers for scikit-learn versions >= 1.2, up to 1.9.