Building Triton from source: the pinned LLVM hash, the build environment variables, and a test recipe that is not turnkey

LLVM has no stable API, so `llvm_hash` decides your build

Triton uses LLVM to generate code for GPUs and CPUs, and the build pins LLVM to one commit. The reason is stated plainly: LLVM does not have a stable API, so the Triton build will not work at an arbitrary LLVM version. Normally the build downloads a prebuilt LLVM, which is why most people never meet the constraint, but when you go looking for your own the version is written down in `cmake/llvm-info.json` as `llvm_hash`, with `49af6502c6dcb4a7f7520178bd14df396f78240c` given as an example value that means the tree builds against LLVM 49af6502. `make dev-install-llvm` is the supported shortcut. The manual route asks you to check out LLVM at that revision, optionally modify it, and build it with `-DLLVM_ENABLE_PROJECTS="mlir;llvm;lld;clang"` and `-DLLVM_TARGETS_TO_BUILD="host;NVPTX;AMDGPU"`, then point `LLVM_BUILD_DIR`, `LLVM_INCLUDE_DIRS`, `LLVM_LIBRARY_DIR`, and `LLVM_SYSPATH` at your build before running `pip install -e .`. The step list includes the line Grab a snack, this will take a while. The consequence for a reader is narrow but firm: a system LLVM is not a supported input here.

`--no-build-isolation` keeps pip from invalidating the ninja cache

Three environment variables decide how painful a source build is, and one of them has a counter-intuitive reason. Passing `--no-build-isolation` to `pip install` makes nop builds faster, and without it every invocation of `pip install` uses a different symlink to cmake, which forces ninja to rebuild most of the `.a` files. That is a rebuild of the C++ side rather than a packaging nicety, so it is the difference between a short incremental build and a full one on every reinstall. `MAX_JOBS` is the lever when the build runs out of memory, and it is passed to the `pip install -e .` command to limit the number of jobs. `TRITON_BUILD_WITH_CLANG_LLD=true` switches to clang and lld, with lld in particular named as the reason builds get faster, and `TRITON_BUILD_WITH_CCACHE=true` turns on ccache. None of these appear in the install line, which is why a source install advertised as two commands is in practice two commands plus a set of environment variables you are expected to know about.

`TRITON_HOME` relocates the cache and the build downloads

`TRITON_HOME` decides where a Triton checkout keeps its state. Set it to a path and the `.triton` directory moves there, and that single directory holds two different things: Triton's cache, and the downloads stored during the build. The default is the user's home directory, and the README says it can be changed at any time. That flexibility is useful for anyone with more than one checkout or a home directory on a small volume. The cost of pointing it somewhere new is that those downloads live in the same place, so an empty path means the build fetches its prebuilt dependencies again rather than reusing what an earlier build left behind. It is also the knob to reach for when you want two source trees to stop sharing one cache, which matters if you are comparing behaviour across a working tree and a release.

The Makefile says it is not the build system, so `make dev-install` comes first

The Makefile opens with a disclaimer that shapes how you use it: this is not the build system, just a helper to run common development commands, and you must first initialize the build system with `make dev-install`. Everything else in the file depends on that, because `BUILD_DIR` is not a path constant but the output of running python with `PYTHONPATH` pointed at the repo's `python` directory and importing `get_cmake_dir` from `build_helpers`. Run a target before that directory exists and the shell call has nothing to report. The targets are thin wrappers around ninja and pytest, with `all` calling ninja in the build directory, `triton-opt` building that one binary, `test-lit` and `test-cpp` mapping to `check-triton-lit-tests` and `check-triton-unit-tests`, and the Python suites driven through `triton._test_runner` with `NUM_PROCS` and `NUM_GPUS` as overridable variables. The suite list is long, covering unit, plugins, gluon, warmup, gsan and regression. Release cadence sits apart from all of it, with v3.7.1 on 2026-06-18, v3.8.0 on 2026-08-28, v3.9.0 on 2026-10-27, and the last push to the default branch dated 2026-11-02.

There is no turnkey way to run the test suite

The README opens its test section by admitting that there currently isn't a turnkey way to run all the Triton tests, and the recipe it gives is short:

# One-time setup.  Note this will reinstall local Triton because torch
# overwrites it with the public version.
$ make dev-install

# To run all tests (requires a GPU)
$ make test

# Or, to run tests without a gpu
$ make test-nogpu

Two details inside that block decide whether you are testing your checkout or the pip package. The setup note says `make dev-install` will reinstall local Triton because torch overwrites it with the public version, so an environment with torch installed can replace a local editable build with the released wheel, and a test run afterwards measures something other than your tree. The second detail is the split between the two commands: `make test` requires a GPU and `make test-nogpu` is the fallback. If your work touches anything GPU resident, the fallback is not a substitute, and for running without a GPU at all the README points at the Triton interpreter, which runs the third party Triton puzzles.

IntelliSense needs `compile_commands.json` pasted into VSCode by hand

The README gives a fallback for when VSCode IntelliSense does not work on the C++ code. The build system creates a `compile_commands.json` file under the Triton repo directory, and the README says that file is what VSCode IntelliSense and clangd use. Finding it takes a local build with `pip install -e .` and then `find ./build -name 'compile_commands.json' | xargs readlink -f`, which returns a path shaped like `/Users/{username}/triton/build/cmake.macosx-11.1-arm64-cpython-3.12/compile_commands.json`, so the location moves with your platform, your architecture, and your interpreter version. The C/C++ extension then has to be installed, the command palette opened with `Shift + Command + P` on Mac or `Shift + Ctrl + P` on Windows and Linux, `C/C++: Edit Configurations (UI)` run, and the path pasted into the Compile Commands textbox under Advanced Settings. These steps are only needed if IntelliSense does not work, and they are per machine.

Three formatters disagree about the column limit

`pyproject.toml` configures three formatters at once and they do not agree. The yapf section uses `based_on_style = pep8` with a `column_limit` of 120, the autopep8 section sets `max_line_length = 88` and ignores `E501,E701,E731,W690,W503`, and the ruff section sets `line-length = 120` with a lint ignore list of `E501`, `E701`, `E731`, `E741` plus a per file ignore of `F401` for `__init__.py`. A comment above the autopep8 block says the project is incrementally switching from autopep8 to ruff, which explains the overlap without removing the conflict. Type checking is narrower still: mypy is pointed at the repo's `python` directory through `mypy_path` and given a file list of seven paths, including `python/triton/knobs.py`, `python/triton/runtime/build.py`, `python/triton/runtime/driver.py`, and three unit tests, with `/build/` excluded and `follow_imports` set to silent. The consequence is that formatting here is a per contributor decision and the type gate covers a small, named corner of the codebase.

The build pins nanobind exactly and caps cmake below 4.0

The build environment is pinned tighter than the install line suggests. The build system requires `setuptools>=40.8.0`, `cmake>=3.20,<4.0`, `ninja>=1.11.1`, and `nanobind==2.10.2`, with setuptools as the backend, so the cmake upper bound is a real constraint and nanobind is an exact pin rather than a floor. The Python side is bound to nanobind through `setup.py`, which also has to answer a question about where it is running: the `is_git_repo` function shells out to `git rev-parse --show-toplevel` and compares the answer with the file's own resolved parent, so a git checkout and a copied source tree are not the same input to the build. The same file imports `check_env_flag`, `find_therock_rocm_include_dir`, `get_base_dir`, and `get_cmake_dir` from `python.build_helpers`, and models a backend as a record with a name, a source directory, a language directory, an optional tools directory, and a flag for whether the backend is external. If a build fails, those two files are where the answers are.

Editorial conclusion

Triton fits the reader who wants to write custom deep-learning primitives and is willing to live inside a CMake and ninja build; the pip wheel path for CPython 3.10-3.14 costs you nothing extra. Before building from source, check four things: cmake is below 4.0 and nanobind 2.10.2 is what the build asks for, the `llvm_hash` in `cmake/llvm-info.json` is the only LLVM revision that will be accepted, and your machine has memory headroom or you will set `MAX_JOBS`. Do not plan on running the whole suite without a GPU. And if you publish work built on it, the README asks you to cite the MAPL2019 paper.

Frequently asked questions

Official sources

1. Official documentation
2. Official README
3. Project repository
4. Release notes