Monorepo Vs Polyrepo: How To Choose The Right Setup
by GainHQ Editorial Team | Aug 4, 2026 | Software Development Insights | Editorial policy
Table of Contents
A monorepo is a single version-control repository that holds several distinct projects, such as web and mobile apps, back-end services and shared libraries, with clear relationships between them. A polyrepo setup gives each project its own repository. Monorepos make sharing code and changing many projects at once easier, but they need good build tooling to stay fast. Polyrepos keep each project's build and access rules simple, but make shared changes and keeping dependencies in line harder.
Below: what a monorepo is in practice, how it differs from a polyrepo, what Google's well-known monorepo actually looks like, the tooling you need, and how to choose.
What is a monorepo?
A monorepo ("monolithic repository") is one repository that stores the code for many projects together, with one shared history. Nx, which builds monorepo tooling, defines it as "a single repository containing multiple distinct projects, with well-defined relationships between them" (Nx). The important words are distinct and well-defined: each project can still be built, tested and deployed on its own.
A small product company's monorepo might look like this (illustrative):
company-repo/
├── apps/
│ ├── web/ # customer web app
│ ├── admin/ # internal admin panel
│ └── mobile/ # React Native app
├── services/
│ ├── billing/ # billing API
│ └── notifications/ # email and push service
└── packages/
├── ui/ # shared design system
├── auth/ # shared login logic
└── config/ # shared lint and TypeScript config
In a polyrepo setup, each of those eight folders would be its own repository, and ui, auth and config would be published as versioned packages for the others to install.
Is a monorepo the same as a monolith?
No. A monolith is an application architecture: one application deployed as a single unit. A monorepo is a way of storing code. A monorepo can hold a monolith, dozens of independently deployed microservices, or both. Nx makes the same distinction: projects in a monorepo stay separate and can be deployed on their own (Nx).
What is a polyrepo?
A polyrepo (also called multi-repo) setup gives each project, service or library its own repository, with its own history, pipeline and access rules. Teams share code by publishing packages to a registry and depending on specific versions. It is the default way many organisations grow, because each new project simply gets a new repository.
Does Google use a monorepo?
Yes, and it is the best-documented large example. In "Why Google Stores Billions of Lines of Code in a Single Repository" (Potvin and Levenberg, Communications of the ACM, 2016; Google Research listing), two Google engineers describe the repository as of January 2015:
| Measure (January 2015) | Figure |
|---|---|
| Files | About 1 billion |
| Source code | About 2 billion lines in 9 million unique source files |
| History | About 35 million commits |
| Size | 86 TB |
| Developers using it | More than 25,000 |
| Human changes per workday | About 16,000 |
| Automated changes per workday | About 24,000 (60% of the roughly 40,000 daily total, our calculation) |
Google runs this on custom infrastructure: a version-control system called Piper, cloud workspaces called CitC, and trunk-based development, where most engineers work at the head of a single copy of the code with very few long-lived branches. Treat it as proof that monorepos can scale, not as a template. The figures are more than ten years old, and most teams will never need, or be able to build, Google's tooling.
Monorepo vs polyrepo: key differences
The main differences show up in code sharing, dependencies, changes across projects, builds and access control.
| Area | Monorepo | Polyrepo |
|---|---|---|
| Code sharing | Import directly from shared folders; no publishing step | Publish and version packages; consumers upgrade on their own schedule |
| Dependencies | Usually one version of each third-party library for everything | Each repo chooses its own versions; drift is common |
| Cross-project changes | One commit and one review can change an API and every caller | Several pull requests across repos, merged in the right order |
| Builds and CI | Needs tooling to build and test only what a change affects | Each pipeline is small and simple |
| Access control | Coarser by default; ownership enforced with tools such as CODEOWNERS | Natural per-repo permissions |
| Releases | Projects can still release independently, but all build against the latest shared code | Fully independent release cycles |
| Visibility | Everyone can see and search all code | Code is spread out; cross-repo impact is harder to see |
Monorepo pros and cons
Monorepos trade simpler collaboration for heavier tooling.
| Pros | Cons |
|---|---|
| Shared code without publishing or versioning | CI gets slow without "affected-only" builds and caching |
| Atomic changes across many projects | Large repos can slow clones and everyday Git commands |
| One set of lint, test and dependency rules | A bad change to shared code can break many projects |
| Easier large-scale refactoring | Fine-grained access control takes extra setup |
| One place to search and onboard | Needs clear ownership rules to avoid a free-for-all |
Polyrepo pros and cons
Polyrepos trade simpler repositories for more coordination.
| Pros | Cons |
|---|---|
| Clear ownership and per-repo permissions | Cross-repo changes need coordinated pull requests and releases |
| Small, fast, simple pipelines | Shared code must be packaged and versioned |
| Teams choose their own tools and release pace | Dependency versions drift apart |
| Easy to open-source or hand over one project | Duplicated configuration and CI across repos |
| A problem in one repo stays in that repo | Harder to see the impact of a change across the system |
What tooling a monorepo needs
A monorepo stays fast when the tooling builds and tests only what changed, reuses results already computed, and lets developers check out only the parts they need. Plain Git can hold a monorepo, but these features come from build tools.
| Tool | What it is | Key features (from official docs) |
|---|---|---|
| Nx | Monorepo build system, strongest in JavaScript and TypeScript, with plugins for others | Affected detection (run tasks only for projects impacted by a change), local and remote caching, distributed task execution via Nx Cloud |
| Turborepo | Build system for JavaScript and TypeScript monorepos | Works from existing package.json scripts plus one turbo.json; caching; Remote Cache; runs tasks in parallel "across all available cores" |
| Bazel | Multi-language build and test tool | Many languages, extensible to others; builds with "100k+ source files"; hermetic builds through sandboxing; remote caching shared across developers and CI |
| Git sparse-checkout | Built into Git | Check out only selected directories ("cone mode"). Git still labels the command experimental |
| Git partial clone | Built into Git | Avoid downloading unneeded objects up front, cutting clone time and disk use on very large repos |
| CODEOWNERS (GitHub) | Ownership file | Owners are automatically asked to review changes to their folders; can be required before merging |
As a rule of thumb, JavaScript and TypeScript teams usually start with Nx or Turborepo. Teams with several languages or very large codebases look at Bazel. Track build and CI times as part of your engineering KPIs, so you notice when the repository needs better tooling.
Which should you choose?
Choose a monorepo when your projects share a lot of code and change together. Choose a polyrepo when projects are independent, owned by separate teams, or need strict access separation.
| Situation | Usually better | Why |
|---|---|---|
| Startup with one product (web, API, mobile) | Monorepo | Shared types and UI; one change updates every client |
| Several products sharing a design system and auth | Monorepo | Shared packages change often; atomic updates help |
| Microservices owned by separate, autonomous teams | Either | Monorepo for shared contracts; polyrepo for independence |
| Open-source library with outside contributors | Polyrepo | Simple to clone, contribute to and release |
| Contractors or partners who must see only part of the code | Polyrepo | Per-repo permissions are simpler and safer |
| Many languages and a very large codebase | Monorepo only with serious build tooling | Without affected builds and caching, CI slows down |
Monorepo vs microservices is not an either/or choice. Microservices describe how your application is split and deployed. A monorepo describes where the code is stored. Many teams keep microservices in a monorepo so that shared contracts and libraries change together. Our guide to scalable software architecture covers the application side of that decision.
How to move from polyrepo to monorepo
Move in stages, starting with the projects that share the most code.

- Map dependencies. List which repos depend on which shared packages and APIs. Start with a tightly linked group.
- Choose the build tool first. Set up affected builds and caching before moving many projects, or CI times will jump.
- Decide on history. Keep each repo's Git history if you need it for audits or debugging. Otherwise start fresh and archive the old repos as read-only.
- Migrate in waves. Move two or three projects, fix the pipeline, then continue. Keep the old repos frozen until the new setup is proven.
- Set ownership and rules. Add CODEOWNERS, branch protection and shared lint and test settings from day one.
Plan the move like any engineering change within your software development life cycle, with a rollback point, and schedule it across sprints during sprint planning, not as a weekend project.
Do AI coding assistants work better in a monorepo?
Monorepo tool vendors argue that they do. Nx says AI coding agents work better in monorepos because related code, context and feedback loops are in one place (Nx). The reasoning is plausible, since an assistant can only use the code it can see. However, we found no independent study that measures the effect, so treat it as a minor factor next to team structure and build tooling.
How GainHQ can help
GainHQ is a custom software development agency with more than 15 years of experience building software, more than 13 products delivered and a team of over 30 people. We also build and run our own products, Payrun and Gain.io. If you are setting up a new codebase or restructuring an existing one, see our services.
Frequently asked questions
What is a monorepo in simple terms?
A monorepo is one code repository that holds several separate projects, such as a web app, a mobile app, back-end services and shared libraries. Each project can still be built and deployed on its own, but they share one history and can share code directly.
What is a polyrepo?
A polyrepo, or multi-repo, setup gives each project or service its own repository. Teams share code by publishing versioned packages. It offers clear ownership and simple pipelines, at the cost of coordinating changes across repositories.
Is a monorepo the same as a monolith?
No. A monolith is an application deployed as a single unit. A monorepo is a way of storing code. A monorepo can contain a monolith, many independently deployed services, or both.
Does Google use a monorepo?
Yes. A 2016 Communications of the ACM article by Google engineers describes a single repository that, in January 2015, held about 2 billion lines of code in 9 million source files, used by more than 25,000 developers on custom tooling.
What are the disadvantages of a monorepo?
Without the right tooling, CI slows down because too much is rebuilt. Very large repositories can slow Git operations, a bad shared change can break many projects, and fine-grained access control needs extra setup.
Can microservices live in a monorepo?
Yes. Microservices describe how an application is split and deployed. A monorepo describes where the code lives. Many teams keep separately deployed services in one repository so that shared contracts and libraries change together.
What tools do you need for a monorepo?
Most teams use a build tool that runs tasks only for affected projects and caches results, such as Nx or Turborepo for JavaScript and TypeScript, or Bazel for multi-language codebases. Add CODEOWNERS for ownership, and Git sparse-checkout or partial clone for very large repositories.
When should I choose a polyrepo over a monorepo?
Choose a polyrepo when projects share little code, are owned by independent teams with their own release cycles, need strict access separation, or will be open-sourced or handed over separately.