Install & Compatibility
Where this runs
tested against v4.9.0 · 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
391MB installed
● package 391MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
OptunaSearchCV
✓ from optuna_integration.sklearn import OptunaSearchCV
✗ from optuna.integration import OptunaSearchCV
Integration modules have officially migrated from `optuna.integration` to `optuna_integration` for better separation and maintainability. While the old path might still work for backward compatibility, the new path is recommended.
LightGBMTuner
✓ from optuna_integration.lightgbm import LightGBMTuner
✗ from optuna.integration import LightGBMTuner
As with `OptunaSearchCV`, LightGBM integration classes have moved to the `optuna_integration` package.
This quickstart demonstrates how to use `OptunaSearchCV` from `optuna_integration.sklearn` to perform hyperparameter optimization for a scikit-learn `SVC` estimator. It defines a search space for the 'C' and 'kernel' parameters and runs a specified number of trials. The example also implicitly shows how an objective function for Optuna works for direct `study.optimize` usage (though `OptunaSearchCV` abstracts this for scikit-learn models).
import optuna
from optuna_integration.sklearn import OptunaSearchCV
from sklearn.datasets import load_iris
from sklearn.svm import SVC
from sklearn.model_selection import train_test_split
def objective_svc(trial):
svc_c = trial.suggest_float('svc_c', 1e-10, 1e10, log=True)
svc_gamma = trial.suggest_float('svc_gamma', 1e-10, 1e10, log=True)
classifier_obj = SVC(C=svc_c, gamma=svc_gamma)
X, y = load_iris(return_X_y=True)
X_train, X_test, y_train, y_test = train_test_split(X, y, random_state=0)
classifier_obj.fit(X_train, y_train)
return classifier_obj.score(X_test, y_test)
# Using OptunaSearchCV for a scikit-learn estimator
# This automatically creates an Optuna study and optimizes the hyperparameters
optuna_search = OptunaSearchCV(
estimator=SVC(gamma='auto', random_state=0),
param_distributions={
'C': optuna.distributions.FloatDistribution(1e-10, 1e10, log=True),
'kernel': ['linear', 'rbf']
},
n_trials=10,
random_state=0,
cv=3
)
X, y = load_iris(return_X_y=True)
optuna_search.fit(X, y)
print(f"Best parameters found by OptunaSearchCV: {optuna_search.best_params_}")
print(f"Best score found by OptunaSearchCV: {optuna_search.best_score_}")
Debug
Known issues
breakingThe integration modules have been migrated from the main `optuna` package to `optuna-integration`. Importing from `optuna.integration` is deprecated and will eventually be removed.fixUpdate import statements from `from optuna.integration import ...` to `from optuna_integration import ...`.
affects: Optuna 4.x and optuna-integration 1.0.0+
breakingOptuna (and by extension, optuna-integration) dropped support for Python 3.8 starting with Optuna 4.0.0.fixEnsure your Python environment is version 3.9 or higher.
affects: Optuna 4.0.0+ / optuna-integration 4.0.0+
deprecatedThe `verbosity` argument in `LightGBMTuner` has been removed. Use the `set_verbosity` method instead to control logging levels.fixReplace `LightGBMTuner(..., verbosity=...)` with `tuner = LightGBMTuner(...)` followed by `tuner.set_verbosity(...)`.
affects: Optuna 4.3.0+ / optuna-integration 4.3.0+
gotchaWhen using `OptunaSearchCV` with `cv` (cross-validation), ensure the underlying estimator can handle the data splits without issues. Some estimators might require specific random states or data types.fixCarefully review the documentation of the integrated estimator regarding its compatibility with scikit-learn's cross-validation utilities and potential data transformation needs.
affects: All versions
Errors
Common errors & fixes
ModuleNotFoundError: No module named 'optuna'
The core `optuna` library, which `optuna-integration` depends on, is not installed in the current Python environment.
fixInstall the `optuna` package: `pip install optuna`
AttributeError: 'AcceleratorConnector' object has no attribute 'distributed_backend'
This error typically occurs when using `optuna_integration.pytorch_lightning.PyTorchLightningPruningCallback` with newer versions of PyTorch Lightning (e.g., >= 1.8.0), where internal API methods like `_accelerator_connector.distributed_backend` have been removed or renamed.
fixUpdate `optuna-integration` to a version compatible with your PyTorch Lightning version. If the latest `optuna-integration` still causes issues, check the official Optuna documentation for compatibility notes or consider downgrading PyTorch Lightning. For instance, the fix often involves internal adjustments to `PyTorchLightningPruningCallback` to align with new PyTorch Lightning API changes.
ModuleNotFoundError: No module named 'optuna.integration.tfkeras'
Many integration modules, including `TFKerasPruningCallback`, were moved from the main `optuna` package to the `optuna-integration` package. Users might still try to import them from the old `optuna.integration` path.
fixEnsure `optuna-integration` is installed (`pip install optuna-integration`) and import the callback from the correct path: `from optuna_integration.tfkeras import TFKerasPruningCallback`.
ValueError: All the X fits failed.
This error occurs with `optuna_integration.sklearn.OptunaSearchCV` when every single trial (fit operation within cross-validation) fails due to issues such as invalid hyperparameters for the estimator, incorrect data, or problems with the scoring function.
ValueError: The entry associated with the validation name "valid_0" and the metric name "auc" is not found in the evaluation result list [...]
This error happens when using pruning callbacks like `LightGBMPruningCallback` or `XGBoostPruningCallback` because the `metric` or `observation_key` provided to the callback does not match any of the evaluation metrics actually reported by the underlying LightGBM or XGBoost model during training.
Upgrade
Version history
4.9.0latest on PyPI · released Jun 1, 2026
Audit
Dependencies
optunarequiredCore hyperparameter optimization framework.
scikit-learnoptionalRequired for scikit-learn integrations (e.g., OptunaSearchCV).
lightgbmoptionalRequired for LightGBM integrations (e.g., LightGBMTuner).
pytorchoptionalRequired for PyTorch integrations.
tensorflowoptionalRequired for TensorFlow/Keras integrations.