optuna/optuna-examples: What the Example Repository Actually Covers

A Script Collection, Not a Package You Install

The repository exists to answer a narrow question: given that Optuna is already the chosen optimizer, what does the code look like when it is wired into LightGBM, PyTorch Lightning, XGBoost, Keras, or a Dask cluster. The README describes itself as a page that contains a list of example codes written with Optuna. There is no package on PyPI, no importable module, and no CLI. You clone it and read files. That framing matters because it sets the correct expectation. The audience is engineers who have already committed to Optuna and now need the integration boilerplate, which is the part that is tedious to write and easy to get subtly wrong. Anyone still comparing optimizers will find nothing here, because the repository never argues for Optuna over an alternative. It starts from the assumption that the choice is made.

How the Examples Are Organized and What Each File Demonstrates

The layout is one directory per integration target: basic, multi_objective, sklearn, pytorch, lightgbm, xgboost, keras, tensorflow, catboost, fastai, dask, ray, kubernetes, hydra, aim, terminator, samplers, faq, visualization, hiplot, and rl. The README's simplest codeblock shows the full shape of an Optuna study: define an objective that takes a trial, call trial.suggest_float to draw a parameter, return a scalar, then call optuna.create_study and study.optimize with n_trials and timeout. The comment in that snippet states that optimization finishes after evaluating 1000 times or 3 seconds, which is the clearest statement of the two stopping conditions in the material. Everything else in the repository is a variation on that loop. The pruning directory is the most informative section, because pruning is where integrations differ. A plain scikit-learn example calls trial.report and checks trial.should_prune inside the training loop, while the XGBoost, LightGBM, CatBoost, Keras, PyTorch, and TensorFlow entries use what the README calls integration modules, which move that bookkeeping into a callback or a wrapper. The distinction is practical: manual pruning means editing your training loop, an integration module means passing a callback.

Getting a Script Running: Commands and Configuration Keys

The README gives no installation section, so the only defensible instruction is the general one: clone the repository, install Optuna, and install the library the specific example targets. A typical invocation would be python basic/quadratic.py, since each file is a standalone script with an if __name__ == "__main__" block, as shown in the simplest codeblock. The configuration surface visible in the material is the Optuna API itself rather than repository-level config. From the README snippet: optuna.create_study() with no arguments creates an in-memory study, trial.suggest_float("x", -100, 100) defines a search space, and study.optimize(objective, n_trials=1000, timeout=3) sets both a trial budget and a wall-clock budget. The FAQ examples extend this in three named directions: sklearn_additional_args.py shows passing arguments besides trial into the objective, enqueue_trial.py shows manually providing trials through a sampler, and max_trials_callback.py shows a callback that controls the termination criterion instead of relying on n_trials or timeout. The dashboard note points at dashboard/run_server_simple.py for a quick start with in-memory storage. For anything distributed, the README points at dask/dask_simple.py, kubernetes/README.md, and ray/ray_joblib.py, and those files carry their own setup instructions that the top-level README does not reproduce.

Where the Examples Stop Being Enough

The honest limitation is that these are examples, and examples optimize for readability over production concerns. The simplest codeblock uses in-memory storage, which means the study disappears when the process exits. Nothing in the README explains how to move to a persistent backend, and the distributed examples are the only place where multi-process coordination is addressed at all. A second limitation is version drift. The repository covers a large matrix of third-party libraries, and each integration is pinned to whatever API those libraries exposed when the file was written. PyTorch Lightning, FastAI, Keras, and TensorFlow have all changed their training loop interfaces over time, and the repository has no release history in the supplied material, so there is no changelog to consult when an example fails against a newer library version. Third, the examples are deliberately small. The quadratic function in basic/quadratic.py converges in a space where the answer is obvious, which makes it a poor test of whether a sampler configuration will work on a real objective with a hundred parameters. If your problem is high-dimensional and noisy, copying the sampler settings from a toy example will not tell you anything useful.

The Alternative: The Optuna API and Its Documentation

The realistic alternative is not a different optimizer. It is writing directly against the Optuna API using the official documentation and FAQ, which the README itself links to when it says the FAQ might be helpful for implementing what you want. The difference in approach is that the documentation explains the concepts, samplers, pruners, storages, and study lifecycle, while this repository shows one concrete instantiation of each. That matters when your setup does not match any example. The repository covers Hugging Face Transformers, Stable-Baselines3, and Hydra, but it does not cover every framework, and the README's own tip section exists precisely because readers arrive with use cases that are not listed. A second alternative for the hyperparameter search use case specifically is to use the tuning interface already inside a library, such as the Hugging Face Trainer hyperparameter search that the README lists under external projects. That route requires no Optuna study to be written by hand, at the cost of accepting whatever search algorithm that library implements.

Maintenance Cost and the MIT Licence

The repository is MIT licensed, which permits reuse and modification with the licence and copyright notice retained. This is not legal advice, and the practical implication is simply that copying a file into your own project is permitted under the stated terms. The maintenance cost is asymmetric. Reading an example costs minutes. Keeping a copied example working costs whatever the upstream library charges, because the example depends on that library's API, not on Optuna's. The Optuna side is comparatively stable, since the trial.suggest_* and study.optimize surface shown in the README is the core interface. The integration side is where breakage will come from. The absence of retrieved releases in the supplied material means there is no versioned snapshot to pin against, so treat each file as a reference implementation to adapt rather than a dependency to track.

Who Should Use This and What to Check First

Use it if you have picked Optuna and need to see how pruning is wired into XGBoost cross-validation, how a study is distributed across a Dask or Ray cluster, or how a Hydra config maps onto an objective. The pruning directory alone justifies a look, because the difference between manual trial.report calls and an integration module callback is the kind of detail that is annoying to derive from first principles. Skip it if you are evaluating optimizers, if you need a supported library rather than a reference, or if your framework is not in the list. Before adapting any file, open it and read two things: the imports, which tell you the exact library versions the example was written against, and the storage argument passed to create_study, which determines whether your results survive the process. Those two lines decide more about whether the example transfers to your environment than the objective function does.

Editorial conclusion

Adopt this repository if you already use Optuna and need a working starting point for a specific integration such as PyTorch Lightning DDP, XGBoost pruning, or Dask. Do not adopt it if you have not chosen an optimizer yet, because the repository assumes Optuna and only shows how to wire it into other tools. Before copying anything, check the imports and the study storage configuration in the file you pick, since those two lines decide whether the script runs locally or needs a database.

Official sources

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