sklearn-optuna 0.1.0a1

An Optuna integration for hyperparameter tuning in Scikit-Learn

What is Sklearn-Optuna?

OptunaSearchCV is 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 sklearn search attributes work exactly as expected.

Optuna's tree-structured Parzen estimator (TPE), CMA-ES, and other samplers explore the search space more efficiently than grid or random search, while Optuna distributions (FloatDistribution, IntDistribution, CategoricalDistribution) let you express log-scaled, conditional, and mixed-type parameter spaces. Sklearn-Optuna requires Python 3.11+, scikit-learn ≥ 1.6, and Optuna ≥ 3.5.

Note: This project is inspired by optuna-integration's OptunaSearchCV.

What are the features of Sklearn-Optuna?

• Drop-in sklearn search: Extends BaseSearchCV — works with Pipeline, clone(), get_params()/set_params(), and any estimator that follows the sklearn interface.
• Optuna samplers: Choose TPE, CMA-ES, Random, or any Optuna sampler through the Sampler wrapper, with full sklearn parameter introspection.
• Flexible distributions: Use Optuna's FloatDistribution, IntDistribution, and CategoricalDistribution for log-scaled, bounded, and categorical search spaces.
• Study persistence and reuse: Pass a Storage backend to persist trials to a database, or resume optimization by passing an existing study to fit(study=...).
• Callbacks: Attach Optuna callbacks (e.g., MaxTrialsCallback) via the Callback wrapper to control optimization flow.
• Nested pipeline search: Use OptunaSearchCV as a step inside a pipeline tuned by another OptunaSearchCV and tune its Sampler during 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 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?

• Documentation: https://sklearn-optuna.readthedocs.io/
• Interactive examples: https://sklearn-optuna.readthedocs.io/en/latest/pages/examples/
• GitHub Discussions: https://github.com/stateful-y/sklearn-optuna/discussions

License

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