FLAML: Microsoft's Lightweight AutoML and Hyperparameter Tuning Library

What FLAML Solves and Who It Is For

FLAML automates two related jobs: choosing a model for tabular data, and tuning hyperparameters for a model you already have. The README describes it as a lightweight Python library for efficient automation of machine learning and AI operations, and the emphasis on lightweight is the part that matters. The core dependency list in pyproject.toml is a single entry, NumPy>=1.17. Everything else is optional. That design choice separates FLAML from AutoML systems that pull in a large stack before you can run anything.

The intended user is a Python developer or data scientist who already has X_train and y_train in memory and wants a better baseline without hand-tuning. The README's first example is three lines: construct AutoML, call fit, pass a task string. It is aimed at people who know scikit-learn's estimator interface and want AutoML to behave like one more estimator in that world.

The second audience is people tuning something that is not a scikit-learn model at all. The tune module takes a custom evaluation function, a config dictionary, and a time budget. That covers inference hyperparameters for foundation models, MLOps configurations, pipelines, and software configurations, according to the README's description of the tuning scope. If your search space is heterogeneous and your evaluations cost wildly different amounts of time, that is the case FLAML was built around.

How the Search Works Under the Hood

FLAML is powered by research from Microsoft Research and collaborators at Penn State University, Stevens Institute of Technology, the University of Washington, and the University of Waterloo, per the README. The mechanism that comes through in the documentation is cost-aware search. The tune.run signature in the README takes config, low_cost_partial_config, and time_budget_s. The low_cost_partial_config argument is the tell: it lets you declare which configuration values are cheap to evaluate, so the search can start from a low-cost point and expand, rather than sampling the full space uniformly.

The README states the library handles large search spaces with heterogeneous evaluation cost plus complex constraints, guidance, and early stopping. That is the architecture in one sentence. A search space where every evaluation costs the same is not the target case, and a tuner that assumes uniform cost will waste budget on it.

For the task-oriented path, FLAML picks learners and their hyperparameters together. The estimator_list argument restricts which learners are considered. Passing estimator_list=["lgbm"] tells FLAML to tune LightGBM alone rather than search across the default set. The learner names are the project's own, so the exact string has to come from the documentation rather than from guesswork.

There is a third mode worth knowing about. Zero-shot AutoML, exposed through flaml.default, lets you use the training API of lightgbm or xgboost directly while FLAML sets hyperparameters from the training data. The README example imports LGBMRegressor from flaml.default and calls fit the same way you would with lightgbm.LGBMRegressor. No search loop runs at that point. The configuration is chosen from the data, not from a tuning run.

Installing FLAML and Running a First Classification Fit

The README states the latest version requires Python >= 3.10 and < 3.14, and warns that other Python versions may work for core components but do not guarantee full model support. Check your interpreter before anything else.

The base install pulls only minimal dependencies. The automl module needs more, and the README gives the extra explicitly.

pip install flaml
pip install "flaml[automl]"

The second command installs the dependencies for the task-oriented AutoML module. pyproject.toml lists them as lightgbm>=2.3.1, xgboost>=0.90,<3.0.0, scipy>=1.4.1, pandas>=1.1.4, and scikit-learn>=1.0.0. Note the xgboost upper bound of 3.0.0. If your environment already pins a newer xgboost, that constraint will conflict and pip will tell you so rather than resolving silently.

With the extras installed, the README's quickstart is three lines. The task string selects the problem type.

from flaml import AutoML

automl = AutoML()
automl.fit(X_train, y_train, task="classification")

After fit returns, the object holds the selected estimator and its configuration. The README does not print a summary table in this snippet, so inspect automl.best_estimator and the fitted model attributes yourself. To narrow the search, pass the estimator list.

from flaml import AutoML

automl = AutoML()
automl.fit(X_train, y_train, task="classification", estimator_list=["lgbm"])

This restricts tuning to LightGBM. It is the right move when you have already decided on a learner family and want FLAML for the hyperparameters only. If you need the generic path instead, tune.run takes an evaluation function, a config dictionary, a low_cost_partial_config, and time_budget_s in seconds, as shown in the README.

Where FLAML Is the Wrong Choice

The first limitation is scope. FLAML's built-in learners target tabular problems. The topics list covers classification, regression, and timeseries forecasting, and the README's examples use LightGBM, XGBoost, and Random Forest. If your data is images, audio, or raw text, there is no default learner for it in the quickstart path. You would be writing a custom learner or a custom evaluation function, at which point you are using FLAML as a generic tuner and could equally use one built for that purpose.

The second limitation is reproducibility. The README shows no seed parameter in any of the quickstart examples, and it does not document how a search run is serialized or replayed. If your workflow requires an exact rerun of a tuning session for an audit, the documentation does not establish that FLAML gives you one. Treat that as an open question to resolve against the documentation before you commit.

The third is the xgboost pin. The automl extra caps xgboost below 3.0.0. That is a real constraint in a shared environment, and it is the kind of thing that surfaces during dependency resolution rather than at runtime.

Finally, the README notes that AutoGen has moved to a dedicated repository and that FLAML no longer includes the autogen module. Anyone arriving with an older tutorial that imports autogen from FLAML will find that path gone. Use AutoGen directly.

FLAML Compared with AutoGluon and Optuna

The two comparisons people search for are flaml vs autogluon and flaml vs optuna, and the difference is mostly about what each tool considers its job.

AutoGluon is a full AutoML framework built around stacking and ensembling multiple models. FLAML's task-oriented path selects among learners and tunes them under a time budget, and its README frames the goal as finding quality models with low computational resources. The distinction is ensembling depth versus search economy. If you want the best possible score and can spend the compute, an ensemble-first framework has more room to work. If you want a good model quickly and cheaply, FLAML's cost-aware search is the narrower bet.

Optuna is a hyperparameter optimization framework. It does not choose a model for you in the way FLAML's AutoML class does. FLAML's tune module overlaps with Optuna directly, and the README's low_cost_partial_config is the feature Optuna does not have in the same form: a declared cheap starting point for the search. If your evaluations have wildly different costs, that argument matters. If they do not, the two are closer than the search volume around them suggests.

The honest summary is that FLAML is not a drop-in replacement for either. It is a smaller library that does less, installs faster, and expects you to bring the data and the problem framing.

Maintenance, Licence and Upgrade Cost

The repository is not archived, and the last push was on 2026-09-09. Recent releases are v2.6.0 on 2026-04-28, v2.5.0 on 2026-01-21, and v2.4.1 on 2026-01-13. That is a steady cadence rather than a burst, and the README credits the Microsoft Fabric product team for Python 3.11+ support, new estimators, and MLflow integration.

The licence is MIT, declared in both LICENSE and the pyproject.toml license field. MIT is permissive, so the practical implication is that you can use, modify, and redistribute the library, including in commercial products, provided the copyright notice and licence text are preserved. That is a summary of the licence terms, not legal advice; check the LICENSE file and your own legal process.

The upgrade cost concentrates in two places. The Python version window is >=3.10 and <3.14, so a move to 3.14 will require waiting for a release that widens it. The xgboost upper bound of <3.0.0 in the automl extra will block an environment that has already moved past that. Both are visible in pyproject.toml, so a dependency check before upgrading costs little.

One structural note: the repository's own Dockerfile installs the package with pip install -e .[test,notebook], which is the development and notebook set rather than the automl set. If you copy that line expecting the AutoML extras, you will not get them.

Editorial conclusion

FLAML fits teams that already work in Python and scikit-learn and want a low-cost way to search over learners and hyperparameters without running a separate service. It is the wrong tool if you need a managed pipeline with built-in experiment tracking, or if your data is a graph or text corpus where the built-in estimator list has nothing to offer. Before adopting it, verify that your Python version falls inside the >=3.10 and <3.14 range stated in the README, and check whether the extra dependencies for the automl module (lightgbm, xgboost, scipy, pandas, scikit-learn) are acceptable in your environment.

Frequently asked questions

Official sources

1. License: MIT
2. microsoft/FLAML on GitHub
3. Project website
4. README
5. Releases