Monorepo vs Polyrepo: Pros, Cons and Trade-offs
A monorepo keeps many projects in one version-controlled repository, while a polyrepo gives each project its own. Here are the trade-offs for change and builds.
A monorepo keeps the code for many projects in one version-controlled repository, while a polyrepo gives each project or library its own repository. A monorepo lets one commit change a shared library and every project that uses it, and it keeps dependency versions consistent. It needs heavier tooling and careful access control. A polyrepo keeps each project simple and independent, but changes that span projects must be coordinated across several repositories.
What is a repository?
A repository is a store of files together with their history, usually managed with Git. Every change is recorded as a commit with an author, a message and a link to the commit before it. Teams use repositories to review changes, roll back mistakes and see who changed what.
The choice between monorepo and polyrepo is about how many repositories a company or team creates, not about the code itself. Either layout can hold the same software.
How does each layout work?
In a monorepo, one repository holds many packages, applications and libraries. A build tool records which parts depend on which, so it can build and test only what a change affects. It usually decides what to rebuild by comparing content hashes of each input, so unchanged projects are skipped. In a polyrepo, each project lives in its own repository. Projects share code by publishing versioned packages to a registry such as npm or PyPI, and each consumer pins the version it uses.
The table compares the two layouts on the points that usually matter most.
| Concern | Monorepo | Polyrepo |
|---|---|---|
| Cross-project change | One commit can update a library and every caller | Changes go out as several linked reviews |
| Dependency versions | Usually one version of each shared library | Each project can pin its own version |
| Build and test | Needs tooling that builds only what a change affects | Each repository has a simpler pipeline |
| Access control | Set by directory, with extra tooling | Set by repository |
| Clone size | Large, so partial checkouts are common | Small |
Why do large companies choose monorepos?
Google has described keeping most of its code in one repository, and Meta also runs a very large monorepo. Companies at that scale have built tools for it. Google's build system Bazel is open source, and other tools such as Nx and Pants serve smaller monorepos.
The benefits are concrete. An engineer can rename a function in a shared library and fix all its callers in one reviewed change. Everyone reads and searches the same code, and the whole company can share one set of build and test conventions. The costs are equally concrete: huge clones, slow repository operations, and the risk that one mistake affects many teams. Git's partial clone and sparse checkout features reduce the first two problems, and selective testing reduces the third.
When is a polyrepo the better choice?
A polyrepo suits small teams with independent release cycles, and it suits projects owned by different organisations, such as open-source libraries that others depend on. Each repository can have its own permissions, history and release process, which makes ownership obvious.
The main cost is version drift. Two services may depend on different versions of the same library, and an upgrade can be postponed for months. Build and release tooling is also repeated in every repository, so each one needs its own setup and maintenance.
Is one layout clearly better?
No. The choice depends on how often projects change together, how many teams share code, and how much tooling the organisation can maintain. Many teams use a hybrid, keeping closely related projects in one repository and independent ones in their own. The container approach is one common way to make builds reproducible across either layout, because it packages each project with the environment it needs.
Teams that switch from one layout to the other often find the move harder than the first choice. History, permissions, build pipelines and package versions all have to be carried across.
The real question is where the friction should sit. A monorepo moves friction into tooling and builds, while a polyrepo moves it into coordination between teams.
Tags
git programming software engineering version control
Related articles
- Git Version Control
- Type Theory in Programming Languages
- Big-Endian vs Little-Endian: Byte Order Explained
- Garbage Collection
- RESTful APIs