Skip to content

About

Hyperparameter tuning for scikit-learn estimators with Optuna.

Resources

Code of conduct

Contributing

Security policy

Stars

4 stars

Watchers

1 watching

Forks

Latest commit

 

History

203 Commits

Folders and files

Sklearn-Optuna

Python Version License PyPI Version Conda Version codecov

What is Sklearn-Optuna?

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.

What are the features of Sklearn-Optuna?

  • Drop-in Scikit-Learn search: Extends BaseSearchCV and works with Pipeline, 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 Storage backend to persist trials to a database, or resume optimization by passing an existing study to fit()
  • Callbacks: Attach Optuna callbacks (e.g., MaxTrialsCallback) to control optimization flow
  • Pruning: Pass a Pruner to stop trials that are reliably worse than the best one after a few folds, instead of running every fold
  • Nested pipeline search: Use OptunaSearchCV inside another OptunaSearchCV for hierarchical hyperparameter optimization

How to install Sklearn-Optuna?

Install the Sklearn-Optuna package using pip:

pip install sklearn_optuna

or using uv:

uv pip install sklearn_optuna

or using conda:

conda install -c conda-forge sklearn_optuna

or using mamba:

mamba install -c conda-forge sklearn_optuna

or alternatively, add sklearn_optuna to your requirements.txt or pyproject.toml file.

How to get started with Sklearn-Optuna?

1. Define a search space with Optuna distributions

from optuna.distributions import FloatDistribution
from sklearn.linear_model import LogisticRegression

param_distributions = {
    "C": FloatDistribution(1e-2, 10.0, log=True),
}

2. Create and fit an OptunaSearchCV

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)

3. Inspect results

print(search.best_params_)   # {'C': 1.23}
print(search.best_score_)    # 0.95
search.best_estimator_.predict(X_test)

How do I use Sklearn-Optuna?

Full documentation is available at https://sklearn-optuna.readthedocs.io/.

Interactive examples are available in the examples/ directory:

Can I contribute?

We welcome contributions, feedback, and questions:

If you are interested in becoming a maintainer or taking a more active role, please reach out to Guillaume Tauzin on GitHub Discussions.

Where can I learn more?

For questions and discussions, you can also open a discussion.

License

This project is licensed under the terms of the Apache-2.0 License.

How do I cite Sklearn-Optuna?

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.

Acknowledgements

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.

Made by stateful-y

About

Hyperparameter tuning for scikit-learn estimators with Optuna.

Resources

Code of conduct

Contributing

Security policy

Stars

4 stars

Watchers

1 watching

Forks

Releases

Contributors

Languages