---
id: optuna
version: "4.9.0"
license: unclear
license_treatment: permissive
maintenance: active
---

# optuna — A hyperparameter optimization framework

License: permissive · Maintenance: active · Downloads: 17.4M/mo

## What it is and what it does

Optuna is a framework for automating hyperparameter optimization in machine learning. It uses a define-by-run API where you write an objective function that suggests hyperparameter values and returns a metric to minimize or maximize; Optuna then orchestrates multiple trials to find the best configuration. The framework supports dynamic search spaces (conditionals and loops), efficient sampling algorithms including pruning of unpromising trials, and easy parallelization across workers.

The package is designed for practitioners who need to tune models systematically without manually scripting grid or random search. It integrates with popular ML libraries (scikit-learn, PyTorch, TensorFlow, XGBoost, LightGBM, and others) and provides visualization tools to inspect optimization history. Storage is pluggable (SQLite, PostgreSQL, etc. via SQLAlchemy), making it suitable for both single-machine experiments and distributed optimization studies.

Use it for:

- Tune scikit-learn model hyperparameters (e.g., SVM regularization, random forest depth) by defining an objective function that trains and evaluates the model.
- Optimize neural network architectures and training hyperparameters in PyTorch or TensorFlow with pruning to stop unpromising trials early.
- Run multi-objective optimization to balance competing goals (e.g., model accuracy vs. inference latency) across multiple workers.
- Store and visualize optimization histories in a persistent database for reproducibility and post-hoc analysis via the Optuna Dashboard.
- Implement constrained optimization where hyperparameter choices depend on earlier trial results using conditional suggest calls.

## Worth the install?

AI-flagged interpretation of the facts above — verify before relying.

Optuna is a hyperparameter optimization framework that automates the search for optimal hyperparameter values in machine learning models using a define-by-run API and state-of-the-art sampling algorithms.

Yes. Optuna is a mature, actively maintained framework (Production/Stable, 14662 stars, recent releases) with low install friction, no known vulnerabilities, and permissive MIT licensing. It is well-suited for anyone doing systematic hyperparameter tuning in machine learning and offers a more flexible, Pythonic alternative to grid or random search.

## Install

pip install optuna
uv add optuna
poetry add optuna

## Installing optuna

Before you install: Low install friction with a pure-Python wheel and seven common runtime dependencies (alembic, colorlog, numpy, packaging, sqlalchemy, tqdm, PyYAML). Actively maintained with a recent release 74 days ago and 14662 repository stars.

License in practice: Licensed under MIT (permissive), allowing unrestricted use, modification, and distribution in both open-source and commercial projects.

Quickstart:

pip install optuna

import optuna

def objective(trial):
    x = trial.suggest_float('x', -10, 10)
    return x**2

study = optuna.create_study()
study.optimize(objective, n_trials=100)

Requires Python 3.9 or newer.

Verify before relying:

- Whether the package's distributed optimization scales to 'tens or hundreds of workers' as claimed without additional infrastructure setup.
- Performance characteristics and convergence speed compared to other hyperparameter optimization frameworks in typical ML workflows.

## Package facts

- License: not declared (permissive)
- Python support: supports_current
- Install friction: low
- Maintenance: active
- Downloads: 17.4M/month (top 5,000 on PyPI)
- Known vulnerabilities: none known

## Tags

hyperparameter optimization, automated tuning machine learning, bayesian optimization framework, hyperparameter search, neural architecture search, parameter tuning automation, optimization study framework, hyperparameter-tuning, machine-learning-optimization, distributed-computing

[View on SkillFed](https://skillfed.io/packages/optuna) · [View on PyPI](https://pypi.org/project/optuna/)