The LLVM project is 26 directories wearing a four-component README

The README names four of the twenty-six directories in the tree

The component list runs to LLVM itself, Clang, libc++, and LLD, and then stops at 'and more'. The root directory holds twenty-six project directories. Among the unmentioned ones: `mlir/`, `lldb/`, `polly/`, `openmp/`, `flang/`, `flang-rt/`, `clang-tools-extra/`, `compiler-rt/`, `bolt/`, `offload/`, `orc-rt/`, `llvm-libgcc/`, and the runtime family `libc/`, `libclc/`, `libcxxabi/`, `libsycl/`, and `libunwind/`.

That gap is the first thing to internalise if you are sending a patch here. MLIR in particular is a large body of work with its own documentation and its own upstream, and the README gives a reader no way to know it is in scope for this repository rather than a neighbouring one. The same applies to LLDB and to Polly.

What the README does explain well is the layering. LLVM is the core: the tools, libraries, and headers that process intermediate representations and convert them into object files, with an assembler, a disassembler, a bitcode analyzer, and a bitcode optimizer among them. Clang is a frontend that compiles C, C++, Objective-C, and Objective-C++ into LLVM bitcode, and from there into object files. That sentence is the whole architecture in one line, and it is the line to come back to.

The root pyproject.toml names the project LLVM and then refuses to package it

The most specific fact about this repository is in a file the README never mentions. The root `pyproject.toml` declares a project, gives it a dynamic version, and then says the package is false:

[project]
name = "LLVM"
dynamic = ["version"]
requires-python = ">=3.8"

With `[tool.uv] package = false`, that project block exists to configure tooling, not to be published. A reader who tries to install the root of llvm-project with a Python package manager is working from a manifest that has already declared itself unpackable.

The version line is the sharper oddity. It is not read from a release tag or a version file that belongs to the compiler:

[tool.hatch.version]
source = "code"
path = "llvm/utils/lit/lit/__init__.py"
expression = "__version__"

The project's Python-visible version is `__version__` from lit's `__init__.py`, and lit is LLVM's test harness. So the string a tool would read out of this manifest is the test harness's version, which is a fact worth knowing before you wire that manifest into a release-tracking script.

Python in LLVM has one dev dependency and a 3.8 floor

Look at the dependency groups in the root `pyproject.toml` and the whole Python surface shrinks to one line: a dev group containing `psutil>=7.2.2`. That is consistent with the role Python plays here, which is test infrastructure and documentation tooling rather than product code. lit lives at `llvm/utils/lit/lit/`, and the type checker is configured for exactly two Python trees:

[tool.pyright]
executionEnvironments = [
  { root = "lldb/packages/Python", pythonVersion = "3.8" },
  { root = "utils/docs", pythonVersion = "3.8" },
]

Both environments are pinned to 3.8, matching the `>=3.8` floor in the project block. A contributor whose toolchain is a current Python will find the type checker checking against an interpreter that has been end of life for a while, which is a deliberate constraint for compatibility with what the project supports and is still worth knowing before you file a typing-related patch.

The formatting configuration says something similar. `[tool.black]` sets `extend-exclude` to a single entry, `third-party/`. Everything else in the tree is fair game for a black run, and the C++ side has its own separate configuration in `.clang-format`. Two formatters, one per language, and a single excluded directory.

Three 23.1 patch tags in four weeks, all prefixed llvmorg-

The release naming is the practical detail for anyone pinning a build. Tags are `llvmorg-` followed by the version: `llvmorg-23.1.0` on 2026-08-25, `llvmorg-23.1.1` on 2026-09-08, and `llvmorg-23.1.2` on 2026-09-22. Three patches of the 23.1 line inside four weeks, and the last push to the repository was on 2026-09-29.

Two things follow. If you fetch by tag you need the `llvmorg-` prefix rather than a bare version string, and if you pin, you are pinning a patch release on a branch that is still receiving patches, not a frozen major. The 23.1 line is the one to watch; the repository's default branch is `main`, so the default branch is not the branch the release tags track.

That gap between `main` and the release branch is the normal arrangement for a project of this size, and it is also the thing most likely to surprise someone who clones the default branch, builds it, and then compares behaviour against a packaged toolchain. They are not the same code, and the release tag is the only place the two are reconciled.

The README contains no build command at all

There is nothing to copy. The Getting the Source Code and Building LLVM section consists of a sentence pointing at a documentation page, `https://llvm.org/docs/GettingStarted.html`, and a second sentence pointing at the contributing guide. No clone command, no configure step, no build command, no prerequisites list.

For a project whose entire output is a compiler, that is a deliberate division of labour, and it is a defensible one, because the build story is long and version-dependent and a README would only freeze one configuration of it. It also means this page cannot get you a working compiler, and an engineer evaluating the project has to leave the repository before they can evaluate anything.

What the repository does offer in place of instructions is structure. `cmake/` and `.ci/` are at the root for the build system and the continuous integration, `utils/` holds the shared tooling, `cross-project-tests/` holds the suite that tests sub-projects against each other, and `third-party/` holds the vendored dependencies that the Python formatter explicitly declines to touch. The contributor path is the other half: Discourse, Discord, office hours, and regular sync-ups, with a code of conduct covering all of them.

.git-blame-ignore-revs sits next to .clang-format for a reason

Two root files explain a lot about how the project is worked on. `.clang-format` and `.clang-tidy` mean the project enforces its own style with its own tools, and `.clang-format-ignore` carves out the exceptions. `.git-blame-ignore-revs` is the file that tells Git to skip specific commits when attributing a line, which exists because mass-reformatting commits otherwise make `git blame` useless across large stretches of the tree.

If you are about to blame a line to find out who wrote it, check that file first. The answer you get may deliberately omit the commits that touched every line in the file, and knowing which commits are on that list is faster than wondering why the history looks wrong.

`.mailmap` sits alongside it, doing the other half of the job, normalising author identity so that the same person under several addresses and spellings is one name in the log. `SECURITY.md`, `CODE_OF_CONDUCT.md`, and a `CONTRIBUTING.md` complete the set, which means the repository has both an in-tree contributing document and the off-site guide the README links to. Two entry points for the same job, and the README sends you to the website rather than the file next to it.

GCC ships as one toolchain; LLVM ships as parts you recombine

The comparison worth making is structural rather than a matter of generated code quality, because the repository itself supports the structural half cleanly. GCC is conventionally understood as a single integrated toolchain, where the compiler, assembler, and linker come from one project and share one internal design. LLVM is the opposite arrangement, and the README states the arrangement directly: an intermediate representation with libraries that process it, frontends that produce it, and consumers that turn it into object files.

That difference shows up in what you can do. A frontend that emits LLVM bitcode does not need to know what will consume it, so an alternative frontend, a different linker, and a different standard library can be substituted independently. The same modularity is why Clang exists as a separate component from LLVM in the first place, and why the repository can hold twenty-six of them without the tree becoming one program.

The cost is that the interfaces between the parts are yours to hold. There is no single binary, no single configure step, and no single version number, and the version string in the root manifest comes from the test harness. If you need one tool that does one job, this repository is the wrong shape of answer. If you need to build a compiler, or a language that is not C, this layering is the reason it is possible at all.

Editorial conclusion

The llvm-project repository is the right place to look if you are building a compiler, patching Clang or lld, or reading how a large toolchain organizes itself, and the wrong place to learn how to build it, since the README hands that to a documentation page and stops there. The tree is also much broader than the prose: MLIR, LLDB, Polly, OpenMP, Flang, compiler-rt, BOLT, libc, and the libunwind, libcxxabi, and libsycl family all sit at the root. Verify three things before committing time to it. That the sub-project you want to change is actually in this repository rather than a sibling one. That your Python is 3.8 or newer if you are touching lit or the documentation tooling, since that is the declared floor. And that git blame is not misleading you, because `.git-blame-ignore-revs` exists specifically to hide mass-reformatting commits.

Frequently asked questions

Official sources

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