optuna-examples: a directory of runnable Optuna scripts, not a library

What optuna-examples actually is, and what it is not

This repository is a catalog of example scripts for Optuna, the Python hyperparameter optimization framework. It exists because Optuna's own documentation is reference-shaped: it describes classes and methods, but a reader who wants to tune a LightGBM model or prune a PyTorch training loop has to assemble the integration themselves. The examples close that gap. Each directory targets one framework or one scenario, and the README lists them by category: basic black-box optimization, multi-objective optimization, machine learning integrations, pruning, samplers, terminators, visualization, distributed optimization, and MLOps platforms.

The audience is narrow and specific. If you have never used Optuna, the simplest script in the README is a better entry point than anything in the repository tree, because it fits on one screen. If you already know the API and need to know how the PyTorch Lightning integration module handles pruning, the examples are exactly the right artifact. Between those two poles, the repository is mostly a map: the README tells you which file answers which question, and the file shows the answer.

What it is not: a library, a package, or a stable interface. There is nothing to import from optuna-examples. The top-level entries are directories and configuration files, and the only Python file listed at the root is quickstart.ipynb. The pyproject.toml configures Black and isort for the repository's own code style, not a build target. If you were hoping for a pip-installable wrapper around these patterns, this is the wrong place to look.

How the repository is organized, and why that matters for finding things

The directory layout mirrors the categories in the README almost one to one. basic/ holds the quadratic function examples and the simple pruning example. multi_objective/ holds the BoTorch and PyTorch multi-objective scripts. pytorch/, tensorflow/, keras/, lightgbm/, xgboost/, catboost/, fastai/, haiku/, sklearn/, skimage/, transformers/, dask_ml/, and rapids/ each hold the integration examples for that framework. samplers/, pruners/, terminator/, and faq/ hold the smaller, more focused scripts. dask/, kubernetes/, ray/, and spark/ cover distributed execution.

The useful consequence is that you can navigate by framework name without reading the README. If your model is in XGBoost, xgboost/ contains xgboost_simple.py, xgboost_integration.py, and xgboost_cv_integration.py. The naming pattern is consistent enough that guessing a path is usually faster than searching. The cost is that the repository has no index beyond the README, and the README itself is a set of collapsed details blocks, so a plain-text read of it loses the structure that a browser renders.

One asymmetry is worth noting. Most directories contain a single script per scenario, but xgboost/ and pytorch/ contain several, because pruning and cross-validation change the integration shape. If you copy from the wrong file you will get a working script that does not demonstrate the thing you needed. Read the file's imports before you read its body: the integration modules are imported from optuna.integration, and that import is the signal that the script is showing you the framework-specific path rather than the manual one.

Installing nothing: running your first example

There is no installation step for optuna-examples itself. The repository is cloned or browsed, and its scripts are run against an environment where Optuna and the relevant framework are already installed. The requirements.txt at the root is scoped to the notebook: it lists jupyter, plotly, and scikit-learn, with a comment stating they are used in quickstart.ipynb. It is not a full dependency list for the examples, and installing it will not make the PyTorch or LightGBM scripts run.

The practical sequence is to clone the repository, create an environment, and install Optuna plus whichever framework the example you want uses. The README's simplest codeblock is the fastest way to confirm Optuna itself works before you touch anything framework-specific:

import optuna


def objective(trial):
    x = trial.suggest_float("x", -100, 100)
    return x ** 2


if __name__ == "__main__":
    study = optuna.create_study()
    study.optimize(objective, n_trials=1000, timeout=3)
    print(f"Best params is {study.best_params} with value {study.best_value}")

The comment in that block states that optimization finishes after evaluating 1000 times or 3 seconds, whichever comes first. You should see a printed line with the best parameter value and the best objective value. Once that runs, move to the directory for your framework and run the simple script there. Expect to install that framework separately; the repository does not pin versions, so a script written against an older API may need small edits.

For the notebook path, the root requirements.txt is the one to install:

pip install -r requirements.txt

That covers jupyter, plotly, and scikit-learn, which the README associates with quickstart.ipynb. It does not cover Optuna itself, and it does not cover any of the framework directories.

Pruning, samplers and terminators: the parts that are not about a framework

The framework directories get the attention, but the smaller directories hold the material that is hardest to reconstruct from the API reference. basic/pruning.py demonstrates pruning logic without an integration module, which is what you want if your training loop is custom and no integration exists for it. The README separately lists integration-based pruning examples for Catalyst, CatBoost, FastAI, Keras, LightGBM, PyTorch, PyTorch Ignite, PyTorch Lightning, TensorFlow, and XGBoost, plus a cross-validation variant for XGBoost. The distinction between the manual example and the integration examples is the most useful thing the README communicates, because it tells you whether you need to write the pruning callback yourself.

samplers/ contains two scripts with different purposes. warm_starting_cma.py shows CMA-ES with warm starting, which matters when you have prior knowledge about where good parameters live. simulated_annealing_sampler.py is labeled in the README as an example of defining a user-defined sampler, so it is a template for the sampler interface rather than a recommendation to use simulated annealing. That framing is honest and worth preserving when you read the file: it is teaching the extension point.

terminator/ holds two scripts, one plain and one combining the terminator with OptunaSearchCV. The README's tip section points to faq/max_trials_callback.py for defining your own termination criterion, noting that this is the path when n_trials and timeout are not sufficient. Between the terminator directory and that callback example, the repository covers both the built-in stopping mechanism and the manual one, which is more than most example collections bother with.

Where the examples stop being enough

The repository is a set of demonstrations, and demonstrations omit the parts that make code survive contact with a real workload. There is no guidance in the README on how to choose a storage backend for a long-running study, no discussion of what happens when a trial crashes mid-run, and no rollback or recovery procedure documented anywhere in the README. If your optimization runs for days across a cluster, the examples show you how to submit trials, not how to operate the study.

The distributed examples illustrate the boundary. dask/dask_simple.py, kubernetes/README.md, and ray/ray_joblib.py each show one way to spread trials across workers. The Kubernetes entry is a README rather than a script, which suggests there is setup beyond the code, but the top-level README does not describe what that setup involves. Anyone planning a Kubernetes deployment should read kubernetes/README.md directly rather than inferring from the category listing.

Version drift is the other practical limit. The repository has no retrieved releases and no pinned dependency file for the examples, so the scripts track the main branch of Optuna and of each framework. The pyproject.toml sets target-version to py37 for formatting, which says the repository's style baseline is old, not that the scripts run on 3.7. Treat every example as a starting point that may need adjustment for the versions you have installed, and read the imports first when a script fails.

How this differs from writing the integration yourself

The alternative to browsing optuna-examples is reading the Optuna documentation and writing the integration from scratch. The difference is not quality, it is the shape of the information. The documentation describes the objective function contract, the study object, and the sampler and pruner interfaces in general terms that apply to any framework. The examples commit to one framework and show the concrete call sequence, including the framework-specific hooks that the general documentation cannot name.

A second alternative is the integration modules themselves. Several scripts here exist to demonstrate optuna.integration, which wraps a framework's own training loop so that pruning and reporting happen without you writing the callback. If an integration module exists for your framework, the example's main value is showing which module to import and where to pass the trial object. If no integration exists, basic/pruning.py is the model to follow, and the work is yours.

The README also points outward, listing external projects that use Optuna, including Hugging Face Trainer's hyperparameter search, Hydra's Optuna Sweeper plugin, Catalyst, CuPy, PyKEEN, and RL Baselines Zoo. Those are not alternatives to this repository so much as evidence that the integration pattern generalizes. When your framework is not in the directory list, checking whether one of those projects already solved your case is faster than writing the callback from the documentation.

Licence and the cost of copying

The repository is MIT licensed, and the LICENSE file sits at the root. That is permissive: you can copy a script into your own project, modify it, and ship it, provided you keep the copyright and permission notice with the copied portions. This is not legal advice, and the practical question is usually smaller than the licence question. Because the examples are short and largely mechanical, many teams rewrite rather than copy, which sidesteps attribution entirely.

The upgrade cost is the real one. Nothing here is versioned as a package, so there is no changelog to read and no release to pin. When Optuna changes an integration module's signature, the affected example changes on main, and your copied version does not. The same applies to the framework side: a PyTorch Lightning or Keras API change can invalidate a script that was correct when you copied it. Budget for re-reading the example when you upgrade either Optuna or the framework, and treat the repository as a reference you revisit rather than a snapshot you keep.

The last push to the repository was on 2026-09-04. That is recent enough that the examples reflect current Optuna, but it says nothing about whether any individual script has been touched since it was added.

Editorial conclusion

Adopt optuna-examples if you are already using Optuna and need a concrete starting point for a specific integration, or if you are evaluating whether Optuna fits a framework in your stack and want to see the integration code first. Do not treat it as a library to depend on: there is no package to install, no versioning, and no API surface, so nothing here belongs in a production dependency list. Before copying anything, check the directory for your framework, run the script as-is to confirm the imports resolve against your installed versions, and read the Kubernetes README if you plan distributed trials, since that is the only subdirectory documented as having its own setup instructions.

Frequently asked questions

Official sources

1. Issues
2. License: MIT
3. optuna/optuna-examples on GitHub
4. README