Registry / ai-ml / hydra-optuna-sweeper

hydra-optuna-sweeper

library1.2.0pypypi✓ verified 83d ago

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.

ai-ml llm-agents

pip install hydra-optuna-sweeper

github ↗package ↗

INSTALL

IMPORT

SIG · HYDRA-OPTUNA-SWEEP

hydra-optuna-sweeper

ai-mlpythonv1.2.0

Install

12.4s avg

Import

617ms

Disk

294MB

Pass rate

10/ 10

Env Coverage10 / 10

glibc

3.9–3.13

musl

3.9–3.13

Install & Compatibility

Where this runs

tested against v1.2.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

musl

py 3.10–3.95 runs

installs and imports cleanly · install 0.0s · import 0.640s · 291.9MB

glibc

py 3.10–3.95 runs

installs and imports cleanly · install 12.4s · import 0.594s · 281MB

294MB installed

● package 294MB

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

OptunaSweeper

✓ from hydra_plugins.hydra_optuna_sweeper.optuna_sweeper import OptunaSweeper

✗ from hydra_optuna_sweeper import OptunaSweeper

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

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()

Debug

Known issues

gotchaThe 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.

affects: all

gotchaThe 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.

affects: all

breakingIn 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.

affects: hydra-core<1.2

Errors

Common errors & fixes

ModuleNotFoundError: No module named 'hydra_optuna_sweeper'

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.

ValueError: Unknown sweeper: optuna. Available sweepers: basic

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.

Upgrade

Version history

1.2.0latest on PyPI · released May 17, 2022

Audit

Dependencies

hydra-corerequiredCore dependency; this is a Hydra plugin.

optunarequiredOptuna is the optimization library used by the sweeper.

Agent activity

17 hits · last 30 days

node

OpenAI (training)

Resources

githubhttps://github.com/facebookresearch/hydra ↗

packagehttps://pypi.org/project/hydra-optuna-sweeper/ ↗