{"id":23866,"library":"hydra-optuna-sweeper","title":"Hydra Optuna Sweeper","description":"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.","status":"active","version":"1.2.0","language":"python","source_language":"en","source_url":"https://github.com/facebookresearch/hydra/tree/main/plugins/hydra_optuna_sweeper","tags":["hydra","optuna","hyperparameter-optimization","sweeper"],"install":[{"cmd":"pip install hydra-optuna-sweeper","lang":"bash","label":"Standard install"}],"dependencies":[{"reason":"Core dependency; this is a Hydra plugin.","package":"hydra-core","optional":false},{"reason":"Optuna is the optimization library used by the sweeper.","package":"optuna","optional":false}],"imports":[{"note":"Direct import fails because the plugin is installed as a Hydra plugin, not a top-level package.","wrong":"from hydra_optuna_sweeper import OptunaSweeper","symbol":"OptunaSweeper","correct":"from hydra_plugins.hydra_optuna_sweeper.optuna_sweeper import OptunaSweeper"}],"quickstart":{"code":"import hydra\nfrom hydra.core.config_store import ConfigStore\nfrom dataclasses import dataclass\n\n@dataclass\nclass Config:\n    x: float = 0.5\n    y: float = 0.5\n\ncs = ConfigStore.instance()\ncs.store(name=\"config\", node=Config)\n\n@hydra.main(version_base=None, config_path=\".\", config_name=\"config\")\ndef main(cfg: Config):\n    return cfg.x ** 2 + cfg.y ** 2\n\nif __name__ == \"__main__\":\n    main()","lang":"python","description":"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`"},"warnings":[{"fix":"Use `hydra/sweeper=optuna` in the command line or in your main config's defaults list.","message":"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.","severity":"gotcha","affected_versions":"all"},{"fix":"Add `hydra.sweeper.study_direction: minimize` (or maximize) to your config.","message":"The Optuna sweeper requires a study direction (minimize or maximize) to be set via config. Failure to do so leads to ambiguous optimization.","severity":"gotcha","affected_versions":"all"},{"fix":"Update your config to use the new plugin config structure: see Hydra 1.2 migration guide.","message":"In Hydra 1.2, the sweeper plugin API changed significantly. Older configs for hydra-optuna-sweeper may break if migrating from Hydra 1.1.","severity":"breaking","affected_versions":"hydra-core<1.2"}],"env_vars":null,"last_verified":"2026-05-01T00:00:00.000Z","next_check":"2026-07-30T00:00:00.000Z","problems":[{"fix":"Do not import directly; use Hydra's sweeper mechanism via config or CLI override.","cause":"The package is installed but not importable as a top-level module; it's a Hydra plugin.","error":"ModuleNotFoundError: No module named 'hydra_optuna_sweeper'"},{"fix":"Run `pip install hydra-optuna-sweeper` and ensure it's installed in the same environment as hydra-core.","cause":"The hydra-optuna-sweeper package is not installed or not detected by Hydra.","error":"ValueError: Unknown sweeper: optuna. Available sweepers: basic"}],"ecosystem":"pypi","meta_description":null,"install_score":null,"install_tag":null,"quickstart_score":null,"quickstart_tag":null}