ml-compiler-opt: the training half of MLGO, where learning replaces LLVM's hand written heuristics
Infrastructure for Machine Learning Guided Optimization (MLGO) in LLVM.
At a glance
- What is it?
- Google's ml-compiler-opt holds the training infrastructure for MLGO, a framework that replaces human crafted optimisation heuristics in LLVM with learned models. The compiler side already lives in LLVM, so what is here is data collection, training and the tooling around it, and the README is candid that local training is the only supported mode and wants a 96 thread workstation.
- Who is it for?
- ml-compiler-opt fits a compiler team that has decided to train policies for specific LLVM passes and has the hardware to do it, because the training side is the part that has to be built. It does not fit a team that wants a pretrained model today, since the releases are occasional and the model format follows LLVM's compatibility rules.
- Can I use it commercially?
- Yes. Apache-2.0 is a permissive licence: you can use, modify and sell software built on it, as long as you keep its copyright and licence notices.
- Is it still maintained?
- Yes. The repository last received commits 1 day ago.
- What is it written in?
- Mainly Python, according to GitHub's language statistics.
Answers come from the project's GitHub data, last synced on October 22, 2026, and from our analysis. They are not legal advice.
Editorial analysis
The framework replaces heuristics, and the compiler side is already upstream
ml-compiler-opt is the infrastructure for MLGO, a Machine Learning Guided Compiler Optimizations Framework, and the framing in the README is specific: MLGO integrates machine learning techniques systematically in LLVM, replacing human-crafted optimization heuristics in LLVM with machine learned models.
Two optimizations are supported, and both were specified as LLVM RFCs. The first is inlining-for-size, and the second is register-allocation-for-performance, with the RFC documents linked from the README for each.
The most important structural fact is in the next paragraph of the README: the compiler components are both available in the main LLVM repository, and this repository contains the training infrastructure and related tools for MLGO. So the split is clean. The pass implementations, the model loading in the compiler and the flags that accept a model live upstream in LLVM, and what is here is the part that produces the model.
That matters for how you adopt it. There is no fork of the compiler to maintain, and the trained artefact is consumed by an unmodified LLVM build, which is what makes the pretrained model releases usable as they are.
The audience is therefore compiler engineers and researchers, not application developers. The README points at a paper, MLGO: a Machine Learning Guided Compiler Optimizations Framework, on arXiv, and at a contributions document, and it offers two end-to-end demos: one for training your own inlining-for-size policy from scratch with Policy Gradient, and one for a regalloc-for-performance policy.
The algorithms section adds a second constraint. The project uses two different machine learning algorithms, Policy Gradient and Evolution Strategies, to train policies, but this repository currently supports only Policy Gradient training, with the release of Evolution Strategies training on the roadmap.
Models are versioned against the compiler, and LLVM loads them by path
The pretrained model mechanism is where this project meets the compiler, and the versioning rule is worth understanding because it dictates when a model goes stale.
Models are occasionally released, and the README says they may be used as-is with LLVM. They are released as GitHub releases and named task-major-version.minor-version, with the major version corresponding to breaking changes on the LLVM or compiler side and the minor version corresponding to model updates that are independent of the compiler.
The compiler side of that contract is a single CMake flag. When building LLVM there is -DLLVM_INLINER_MODEL_PATH, which you may set to the path to your inlining model, and if the path is set to download then cmake will download the most recent compatible model from GitHub to use. The README shows both forms:
# Model is in /tmp/model, i.e. there is a file /tmp/model/saved_model.pb along
# with the rest of the tensorflow saved_model files produced from training.
-DLLVM_INLINER_MODEL_PATH=/tmp/model
# Download the most recent compatible model
-DLLVM_INLINER_MODEL_PATH=downloadThe comment tells you the shape of the artefact: a TensorFlow saved_model directory, with saved_model.pb in it. A model is therefore not a single file, and the flag takes a directory.
The version naming also shows that releases here are not tool releases in the usual sense. The tagged versions in this repository are model releases such as inlining-Oz-v1.2 and regalloc-evict-v1.1, whose names encode the task and the semantic version, not a version of the training code. Anyone upgrading an LLVM build needs to check the major version against the compiler they are using, which is the whole point of the scheme.
Training means Ubuntu, a specific Python, and a very large machine
The prerequisites section is where this project stops being casual, and the numbers are the story.
The assumptions for the system are a recent Ubuntu distribution, for example 22.04, and Python 3.10.x or 3.11.x. Then comes the line that decides whether this is feasible for you: for local training, which is currently the only supported mode, the README recommends a high-performance workstation, for example one with 96 hardware threads.
That is a large machine for a compile-time optimisation experiment, and the reason is visible in how the method works. A policy is trained against a corpus of real compiler decisions, and the training loop is a reinforcement learning run rather than a single pass over data. Local training being the only supported mode also means there is no hosted or distributed option described in the README, so the hardware requirement sits with whoever trains.
Training assumes a clang build with ML development-mode, and the README points at the LLVM CMake documentation and at the buildbot_init.sh script in the buildbot/ directory for how to produce such a build.
The end-to-end demo gives the scale of the corpus. The demo uses Fuchsia as the codebase from which a corpus is extracted and a model is trained, and the inlining demo walks from scratch through the whole loop. There is also a guide for how to add a feature and a document describing the extensibility model, which is where you would look before proposing a new task.
versioned_pipenv pins two Python versions with two lock files
The dependency story is unusual enough to be worth reading carefully, because the tooling is part of the reproducibility story.
Pipenv is the base requirement, installed with pip3 install pipenv. The actual dependencies come from a wrapper in the repository, and the command is:
./versioned_pipenv sync --system --categories "packages dev-packages ci"The wrapper exists because the project supports two Python versions at once, and the repository carries two lock files for them, Pipfile.lock.3.10 and Pipfile.lock.3.11, next to the Pipfile. Running the wrapper with no arguments picks the lock file that matches the interpreter in use, which is why the README insists that the command only works from the root of the repository, since it needs Pipfile.lock in the working directory at the time of execution.
The categories option controls what gets installed. The command as given installs everything including the development packages and the packages only needed in CI, and the README notes that you can omit them from the categories option if you do not need those.
One detail in the Dockerfile shows the same thing written slightly differently, with commas rather than spaces between the category names, and it also clears the environment afterwards:
RUN pip install pipenv && ./versioned_pipenv sync --system --categories "packages,dev-packages,ci" && ./versioned_pipenv --clearRunning the tests additionally needs virtualenv, installed with sudo apt-get install virtualenv, and the same tensorflow package is required for building the release mode of LLVM itself.
Warnings are errors here, and the allow list is a tracking list
The pyproject.toml contains one of the more disciplined warning configurations you will see in a research repository, and the comments explain why.
The pytest section starts with two rules stated as comments: always create a tracking issue when allow-listing warnings, and do not disable warnings-as-error, because warnings of today are tomorrow's evolvability blocker. The filterwarnings list is set to error, with a long allow list beneath it, and every entry carries a comment naming the issue number or explaining that the warning comes from a third party.
[tool.pytest.ini_options]
# DO always create a tracking issue when allow-listing warnings
# DO NOT disable warnings-as-error: warnings of today are tomorrow's evolvability blocker.
filterwarnings = [
# Treat warnings as errors
"error",The allow list includes the imp module deprecation, the np.bool alias deprecation, an encoding warning from a TensorFlow Agents policy type, the distutils deprecation slated for removal in Python 3.12, and several TensorFlow and IPython internal warnings. Each has an issue number attached, which is the mechanism that makes the policy enforceable: a warning is not silenced, it is filed.
The Ruff configuration is set the same way, with a line length of 103, a target of py310, a curated selection of rule families, and an explicit ignore list. The mccabe maximum complexity is set to 18, which is a deliberately high ceiling and therefore a statement about the code rather than an accident.
Where ml-compiler-opt is the wrong tool
The first wrong fit is a team that wants a faster compiler now rather than a trained policy later. The output of this project is a model, and a model has to be trained on a corpus by somebody with the hardware to do it. The releases are occasional, so a team hoping to pick up a recent inlining-for-size model and point an LLVM build at it may wait a long time for the next one.
The second is a team without a 96 thread workstation and no appetite to buy one. Local training is the only supported mode described in the README, so there is no smaller path offered, and the cost of the hardware is a real barrier for a university group or a small team.
The third is a plan to use Evolution Strategies. The README says the project uses two algorithms but currently supports only Policy Gradient training, with Evolution Strategies on the roadmap, so choosing it on the strength of the two-algorithm claim would be a mistake.
The fourth is a task that LLVM does not already have a hook for. Because the compiler components live in the main LLVM repository, a new machine learned optimisation needs a pass in LLVM first, and the extensibility model document and the guide for adding a feature are where you would find out how much of that is on the training side and how much is upstream.
The licence is Apache 2.0 with the LICENSE file at the root, and the repository carries check-license.sh with a license-header.txt, so header checks are automated. The last push to the repository was on 2026-10-14 with the repository not archived, and the model releases in the list are Inlining-Oz-v1.2 from 2025-04-08, regalloc-evict-v1.1 from 2024-12-18 and regalloc-evict-v1.0 from 2022-02-09, which is the clearest single indicator of the project's pace.
Editorial conclusion
ml-compiler-opt fits a compiler team that has decided to train policies for specific LLVM passes and has the hardware to do it, because the training side is the part that has to be built. It does not fit a team that wants a pretrained model today, since the releases are occasional and the model format follows LLVM's compatibility rules. Before starting, read the inlining demo end to end, because it is the only description of the corpus extraction and training loop that the repository ships.
Frequently asked questions
What is ml-compiler-opt?
It is the infrastructure for MLGO, a Machine Learning Guided Compiler Optimizations Framework that replaces human-crafted optimization heuristics in LLVM with machine learned models. This repository holds the training infrastructure and tools, while the compiler components themselves live in the main LLVM repository.
Which LLVM optimizations does MLGO support?
Two: inlining-for-size and register-allocation-for-performance, each specified in an LLVM RFC that the readme links. The compiler side of both is in LLVM itself, and the training side is in this repository.
What hardware does training need?
The readme recommends a high-performance workstation with around 96 hardware threads for local training, which it describes as currently the only supported mode. It also assumes a recent Ubuntu distribution, Python 3.10.x or 3.11.x, and a clang build with ML development-mode.
How do I use a pretrained model with LLVM?
Build LLVM with the -DLLVM_INLINER_MODEL_PATH flag set to the path of a TensorFlow saved_model directory, or set it to download so cmake fetches the most recent compatible model from GitHub. Model releases are named task-major.minor, where the major version tracks breaking compiler changes.
Which machine learning algorithms does MLGO train with?
The project uses Policy Gradient and Evolution Strategies, but the readme says this repository currently supports only Policy Gradient training, with Evolution Strategies training on the roadmap.
Official sources
Add this badge to your README
If you maintain this project, the badge below links readers to this analysis and shows its maintenance status from the daily GitHub snapshot. Paste the markdown into your README; add ?metric=license or ?metric=stars to the image URL for a different field.
[](https://hysenlabs.com/projects/google-ml-compiler-opt)Was this useful?