---

name: optuna description: "Use this skill for Optuna hyperparameter optimization workflows: studies, trials, samplers, pruners, storage, CLI, visualization, artifacts, integrations, and advanced APIs." disable-model-invocation: true metadata: disco-role: operating license: NOASSERTION

Optuna Repo Skill

Use this skill when working with Optuna, a Python framework for hyperparameter optimization. It routes tasks across study/trial workflows, search algorithms, pruning, persistent storage, CLI operations, result analysis, visualization, artifacts, integrations, and advanced APIs.

First Checks

Install or verify Optuna before using workflow-specific guidance:

python -m pip install optuna
python - <<'PY'
import optuna
print(optuna.__version__)
study = optuna.create_study(direction="minimize")
print(study.study_name)
PY

For a source checkout, use an editable install only when repo development or local API inspection is intended:

python -m pip install -e .
optuna --help

Read references/repo-provenance.md before deciding whether this generated skill is current for a different Optuna checkout. Use references/package-overview.md for package layout, optional extras, and cross-skill routing notes. Use references/troubleshooting.md for cross-cutting install/import, optional dependency, CLI, and runtime failures.

Route by Task

• Use sub-skills/optimization-workflows/SKILL.md for objective functions, create_study, Study.optimize, Study.ask, Study.tell, callbacks, attributes, fixed/reused parameters, multi-objective basics, and extracting best trials.
• Use sub-skills/samplers-pruners/SKILL.md for choosing, configuring, customizing, or debugging samplers and pruners such as TPE, Grid, CMA-ES, NSGA-II, Hyperband, Median, Threshold, Patient, and Wilcoxon.
• Use sub-skills/cli-and-storage/SKILL.md for optuna CLI commands, OPTUNA_STORAGE, SQLite/RDB URLs, RDBStorage, JournalStorage, GrpcStorageProxy, storage upgrades, heartbeat, and stale-trial behavior.
• Use sub-skills/analysis-visualization/SKILL.md for get_param_importances, trial dataframes, Plotly/Matplotlib visualizations, Pareto fronts, hypervolume history, and optional visualization dependency checks.
• Use sub-skills/artifacts-integrations/SKILL.md for optuna.artifacts, filesystem/S3/GCS artifact stores, integration callback imports, missing SDKs, credentials, and local artifact roundtrips.
• Use sub-skills/advanced-apis/SKILL.md for terminator, search-space helpers, logging, exceptions, experimental warnings, constraints notes, and cautious use of private hypervolume utilities.

Common Workflow Composition

• Start in optimization-workflows to define a correct objective and study lifecycle.
• Add samplers-pruners when the task asks for better search behavior, reproducibility, early stopping, constraints, or custom algorithms.
• Add cli-and-storage when studies must persist, resume, coordinate workers, or be controlled from shell commands.
• Add analysis-visualization after trials exist and the task becomes reporting, ranking, plotting, or export.
• Add artifacts-integrations when trials produce files or need framework/cloud integration callbacks.
• Add advanced-apis only for specialized Optuna APIs or cross-cutting debugging not owned by the main workflows.

Safe Bundled Diagnostics

Run these local helpers from an environment where optuna is importable:

python scripts/check_optuna_env.py
python sub-skills/optimization-workflows/scripts/basic_optimization_smoke.py
python sub-skills/cli-and-storage/scripts/storage_smoke.py
python sub-skills/artifacts-integrations/scripts/filesystem_artifact_smoke.py

These scripts are self-contained and use temporary files or in-memory studies. They do not require cloud credentials, network access, GPUs, large datasets, or the original repository checkout.

Optional Dependencies

The base Optuna package supports core studies, trials, in-memory storage, RDB storage dependencies, CLI, and local filesystem artifacts. Some workflows need optional packages:

• plotly or matplotlib for visualization backends.
• pandas for Study.trials_dataframe.
• scikit-learn for default fANOVA-style importances and OptunaSearchCV.
• cmaes, scipy, or torch for selected advanced samplers/pruners.
• boto3, google-cloud-storage, redis, grpcio, and framework packages for cloud stores, distributed storage, and integrations.

Treat missing optional packages as routing/troubleshooting signals, not as evidence that base Optuna is broken.