Hydra Optuna Sweeper

1.2.0 verified Fri May 01 auth: no python

A Hydra plugin that integrates Optuna for hyperparameter optimization. It enables Optuna samplers and pruners to be used as the sweeper in Hydra's multirun mode for efficient hyperparameter search. Current version: 1.2.0, compatible with Hydra 1.2 and 1.3. Maintained by the Hydra team at Facebook Research. Release cadence is irregular, tied to Hydra core releases.

pip install hydra-optuna-sweeper

Common errors

error ModuleNotFoundError: No module named 'hydra_optuna_sweeper' ↓

cause The package is installed but not importable as a top-level module; it's a Hydra plugin.

fix

Do not import directly; use Hydra's sweeper mechanism via config or CLI override.

error ValueError: Unknown sweeper: optuna. Available sweepers: basic ↓

cause The hydra-optuna-sweeper package is not installed or not detected by Hydra.

fix

Run pip install hydra-optuna-sweeper and ensure it's installed in the same environment as hydra-core.

Warnings

gotcha The Optuna sweeper is configured via Hydra's config system, not directly in code. Users often try to instantiate OptunaSweeper manually, which is not the intended usage. Instead, use Hydra's command-line overrides or a config file to set the sweeper. ↓

fix Use `hydra/sweeper=optuna` in the command line or in your main config's defaults list.

gotcha The Optuna sweeper requires a study direction (minimize or maximize) to be set via config. Failure to do so leads to ambiguous optimization. ↓

fix Add `hydra.sweeper.study_direction: minimize` (or maximize) to your config.

breaking In Hydra 1.2, the sweeper plugin API changed significantly. Older configs for hydra-optuna-sweeper may break if migrating from Hydra 1.1. ↓

fix Update your config to use the new plugin config structure: see Hydra 1.2 migration guide.

Imports

OptunaSweeper

wrong

from hydra_optuna_sweeper import OptunaSweeper

correct

from hydra_plugins.hydra_optuna_sweeper.optuna_sweeper import OptunaSweeper

Direct import fails because the plugin is installed as a Hydra plugin, not a top-level package.

Quickstart

Minimal example using Hydra with Optuna sweeper. Run with: `python my_app.py --multirun x=range(0.0,1.0,0.1) y=range(0.0,1.0,0.1) hydra/sweeper=optuna`

import hydra
from hydra.core.config_store import ConfigStore
from dataclasses import dataclass

@dataclass
class Config:
    x: float = 0.5
    y: float = 0.5

cs = ConfigStore.instance()
cs.store(name="config", node=Config)

@hydra.main(version_base=None, config_path=".", config_name="config")
def main(cfg: Config):
    return cfg.x ** 2 + cfg.y ** 2

if __name__ == "__main__":
    main()