{"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,"search_vec":"'1.2':40 '1.2.0':36 '1.3':42 'cadenc':52 'compat':37 'core':58 'current':34 'effici':31 'enabl':14 'facebook':49 'hydra':1,5,26,39,46,57,60 'hyperparamet':11,32,63 'hyperparameter-optim':62 'integr':8 'irregular':54 'maintain':43 'mode':29 'multirun':28 'optim':12,64 'optuna':2,9,15,61 'plugin':6 'pruner':18 'releas':51,59 'research':50 'sampler':16 'search':33 'sweeper':3,24,65 'team':47 'tie':55 'use':21 'version':35","created_at":"2026-05-01T08:10:02.678829+00:00","updated_at":"2026-05-01T08:10:02.678829+00:00","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,"quickstart_score":null,"quickstart_tag":null,"pypi_latest":"1.2.0","cli_name":"","cli_version":null,"type":"library","homepage":null,"github":"https://github.com/facebookresearch/hydra","docs":null,"changelog":null,"pypi":"https://pypi.org/project/hydra-optuna-sweeper/","npm":null,"openapi_spec":null,"status_page":null,"smithery":null,"categories":["ai-ml","llm-agents"],"base_url":null,"auth_type":null,"provenance":{"verified_status":"passing","verified_at":"2026-06-29","last_verified":"2026-06-29","next_check":"2026-07-29","install_tag":null}}