Optuna: A hyperparameter optimization framework

:link: Website | :pagewithcurl: Docs | :gear: Install Guide | :pencil: Tutorial | :bulb: Examples | Twitter | LinkedIn | Medium

Optuna is an automatic hyperparameter optimization software framework, particularly designed for machine learning. It features an imperative, define-by-run style user API. Thanks to our define-by-run API, the code written with Optuna enjoys high modularity, and the user of Optuna can dynamically construct the search spaces for the hyperparameters.

:loudspeaker: News

Help us create the next version of Optuna!

Optuna 5.0 Roadmap published for review. Please take a look at the planned improvements to Optuna, and share your feedback in the github issues. PR contributions also welcome!

Please take a few minutes to fill in this survey, and let us know how you use Optuna now and what improvements you'd like.🤔 All questions are optional. 🙇‍♂️

• Jun 16, 2025: Optuna 4.4.0 has been released! Check out the release blog.
• May 26, 2025: Optuna 5.0 roadmap has been published! See the blog for more details.
• Apr 14, 2025: Optuna 4.3.0 is out! Check out the release note for details.
• Mar 24, 2025: A new article Distributed Optimization in Optuna and gRPC Storage Proxy has been published.
• Mar 11, 2025: A new article [Optuna v4.2] Gaussian Process-Based Sampler Can Now Handle Inequality Constraints has been published.
• Feb 17, 2025: A new article SMAC3 Registered on OptunaHub has been published.

:fire: Key Features

Optuna has modern functionalities as follows:

• Lightweight, versatile, and platform agnostic architecture
  • Handle a wide variety of tasks with a simple installation that has few requirements.
• Pythonic search spaces
  • Define search spaces using familiar Python syntax including conditionals and loops.
• Efficient optimization algorithms
  • Adopt state-of-the-art algorithms for sampling hyperparameters and efficiently pruning unpromising trials.
• Easy parallelization
  • Scale studies to tens or hundreds of workers with little or no changes to the code.
• Quick visualization
  • Inspect optimization histories from a variety of plotting functions.

Basic Concepts

We use the terms study and trial as follows:

• Study: optimization based on an objective function
• Trial: a single execution of the objective function

Please refer to the sample code below. The goal of a study is to find out the optimal set of hyperparameter values (e.g., regressor and svr_c) through multiple trials (e.g., n_trials=100). Optuna is a framework designed for automation and acceleration of optimization studies.

[!NOTE] More examples can be found in optuna/optuna-examples.

The examples cover diverse problem setups such as multi-objective optimization, constrained optimization, pruning, and distributed optimization.

Installation

Optuna is available at the Python Package Index and on Anaconda Cloud.

```bash

PyPI

$ pip install optuna ```

```bash

Anaconda Cloud

$ conda install -c conda-forge optuna ```

[!IMPORTANT] Optuna supports Python 3.8 or newer.

Also, we provide Optuna docker images on DockerHub.

Integrations

Optuna has integration features with various third-party libraries. Integrations can be found in optuna/optuna-integration and the document is available here.

Web Dashboard

Optuna Dashboard is a real-time web dashboard for Optuna. You can check the optimization history, hyperparameter importance, etc. in graphs and tables. You don't need to create a Python script to call Optuna's visualization functions. Feature requests and bug reports are welcome!

optuna-dashboard can be installed via pip:

shell $ pip install optuna-dashboard

[!TIP] Please check out the convenience of Optuna Dashboard using the sample code below.

OptunaHub

OptunaHub is a feature-sharing platform for Optuna. You can use the registered features and publish your packages.

Use registered features

optunahub can be installed via pip:

```shell $ pip install optunahub

Install AutoSampler dependencies (CPU only is sufficient for PyTorch)

$ pip install cmaes scipy torch --extra-index-url https://download.pytorch.org/whl/cpu ```

You can load registered module with optunahub.load_module.

```python import optuna import optunahub

def objective(trial: optuna.Trial) -> float: x = trial.suggestfloat("x", -5, 5) y = trial.suggestfloat("y", -5, 5) return x2 + y2

module = optunahub.loadmodule(package="samplers/autosampler") study = optuna.createstudy(sampler=module.AutoSampler()) study.optimize(objective, ntrials=10)

print(study.besttrial.value, study.besttrial.params) ```

For more details, please refer to the optunahub documentation.

Publish your packages

You can publish your package via optunahub-registry. See the Tutorials for Contributors in OptunaHub.

Communication

• GitHub Discussions for questions.
• GitHub Issues for bug reports and feature requests.

Contribution

Any contributions to Optuna are more than welcome!

If you are new to Optuna, please check the good first issues. They are relatively simple, well-defined, and often good starting points for you to get familiar with the contribution workflow and other developers.

If you already have contributed to Optuna, we recommend the other contribution-welcome issues.

For general guidelines on how to contribute to the project, take a look at CONTRIBUTING.md.

Reference

If you use Optuna in one of your research projects, please cite our KDD paper "Optuna: A Next-generation Hyperparameter Optimization Framework":

License

MIT License (see LICENSE).

Optuna uses the codes from SciPy and fdlibm projects (see LICENSETHIRDPARTY).