sklearn-optuna 0.1.0a5

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
• 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:

• Online: https://sklearn-optuna.readthedocs.io/en/latest/pages/examples/
• Locally: Run just example quickstart or uv run marimo edit examples/quickstart.py to open an interactive notebook

Can I contribute?

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.

Where can I learn more?

• 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.

License

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

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.