Sklearn-Optuna provides OptunaSearchCV, a drop-in replacement for Scikit-Learn's
GridSearchCV and RandomizedSearchCV that uses Optuna for hyperparameter optimization. It extends BaseSearchCV so that fit(), score(), best_params_, cv_results_, and all other Scikit-Learn search attributes work exactly as expected.
With Sklearn-Optuna, you gain immediate access to sophisticated Bayesian optimization while maintaining full compatibility with Scikit-Learn's Pipeline, cross-validation, and serialization. Perfect for data scientists who want smarter hyperparameter search without learning a new API.
Note: This project is inspired by Optuna-Integration's OptunaSearchCV.
- Drop-in Scikit-Learn search: Extends
BaseSearchCVand works withPipeline,clone(),get_params()/set_params(), and any estimator - Smart optimization: TPE, CMA-ES, and other samplers explore the search space more efficiently than grid or random search
- Flexible distributions: Optuna distributions (
FloatDistribution,IntDistribution,CategoricalDistribution) for log-scaled, bounded, and categorical spaces - Study persistence: Pass a
Storagebackend to persist trials to a database, or resume optimization by passing an existing study tofit() - Callbacks: Attach Optuna callbacks (e.g.,
MaxTrialsCallback) to control optimization flow - Pruning: Pass a
Prunerto stop trials that are reliably worse than the best one after a few folds, instead of running every fold - Nested pipeline search: Use
OptunaSearchCVinside anotherOptunaSearchCVfor hierarchical hyperparameter optimization
Install the Sklearn-Optuna package using pip:
pip install sklearn_optunaor using uv:
uv pip install sklearn_optunaor using conda:
conda install -c conda-forge sklearn_optunaor using mamba:
mamba install -c conda-forge sklearn_optunaor alternatively, add sklearn_optuna to your requirements.txt or pyproject.toml file.
from optuna.distributions import FloatDistribution
from sklearn.linear_model import LogisticRegression
param_distributions = {
"C": FloatDistribution(1e-2, 10.0, log=True),
}from sklearn_optuna import OptunaSearchCV, Sampler
import optuna
search = OptunaSearchCV(
LogisticRegression(max_iter=200),
param_distributions,
n_trials=20,
sampler=Sampler(sampler=optuna.samplers.TPESampler, seed=42),
cv=5,
)
search.fit(X_train, y_train)print(search.best_params_) # {'C': 1.23}
print(search.best_score_) # 0.95
search.best_estimator_.predict(X_test)Full documentation is available at https://sklearn-optuna.readthedocs.io/.
Interactive examples are available in the examples/ directory:
- Online: https://sklearn-optuna.readthedocs.io/en/latest/pages/examples/
- Locally: Run
just example quickstartoruv run marimo edit examples/quickstart.pyto open an interactive notebook
We welcome contributions, feedback, and questions:
- Report issues or request features: GitHub Issues
- Join the discussion: GitHub Discussions
- Contributing Guide: CONTRIBUTING.md
If you are interested in becoming a maintainer or taking a more active role, please reach out to Guillaume Tauzin on GitHub Discussions.
- Full documentation: https://sklearn-optuna.readthedocs.io/
- Interactive Examples: https://sklearn-optuna.readthedocs.io/en/latest/pages/examples/
For questions and discussions, you can also open a discussion.
This project is licensed under the terms of the Apache-2.0 License.
If you use Sklearn-Optuna in work you publish, please cite it:
Guillaume Tauzin. Sklearn-Optuna: An Optuna integration for hyperparameter tuning in Scikit-Learn. https://github.com/stateful-y/sklearn-optuna
Or in BibTeX:
@software{sklearn_optuna,
author = "Guillaume Tauzin",
title = "{Sklearn-Optuna: An Optuna integration for hyperparameter tuning in Scikit-Learn}",
url = "https://github.com/stateful-y/sklearn-optuna",
license = "Apache-2.0"
}Reference managers can read CITATION.cff directly. To cite a specific version, see the citation page.
This project is maintained by stateful-y, an ML consultancy specializing in data science & engineering. If you're interested in collaborating or learning more about our services, please visit our website.