Monorepo vs Polyrepo
One repository for everything versus one repository per project
A monorepo stores all projects, libraries, and services in a single version-controlled repository. A polyrepo (multi-repo) gives each project or service its own repository. Monorepos enable atomic cross-project changes, shared tooling, and unified versioning. Polyrepos provide clear ownership boundaries, independent release cycles, and simpler per-project CI/CD. Google, Meta, and Microsoft use monorepos; most open-source projects and many startups use polyrepos.
Monorepo
A monorepo (monolithic repository) is a version control strategy where all of an organization's code lives in a single repository. This includes multiple applications, shared libraries, configuration, infrastructure code, and documentation. Companies like Google (with billions of lines of code in a single repo), Meta, Microsoft (Windows), Twitter, and Uber use monorepos at massive scale. Monorepo tooling has matured significantly. Build systems like Bazel, Nx, Turborepo, and Rush provide incremental builds (only rebuilding what changed), dependency graph analysis, remote caching (sharing build artifacts across developers), and task parallelization. These tools make monorepos practical even at scale by ensuring that building the entire repo from scratch is never required. The monorepo's key advantages are atomic changes (a single commit can update a library and all its consumers), code sharing (shared utilities, types, and configurations live in one place), consistent tooling (one linter config, one CI setup, one set of conventions), and simplified dependency management (internal packages always use the latest version). The challenges are repository size (Git can struggle with very large repos without optimizations), CI/CD complexity (determining what to test after a change), and access control (harder to restrict visibility of code within a single repo).
Polyrepo
A polyrepo (multi-repo or many-repo) strategy gives each project, service, or library its own dedicated repository. This is the default approach for most organizations: each microservice, frontend app, or shared library lives in a separate Git repository with its own CI/CD pipeline, release cycle, and ownership. Polyrepos align naturally with team boundaries and organizational structures. Each team owns their repository completely, sets their own coding standards, chooses their dependencies, and releases independently. Access control is straightforward: repository permissions map directly to team boundaries. CI/CD is simpler per-repo because the pipeline only needs to handle one project. The polyrepo approach works well with package managers (npm, pip, Maven) that publish and version shared libraries as packages consumed by other repos. This creates a clear contract between producers and consumers of shared code. The challenges are cross-project changes (updating a shared library requires a release, then updates in every consuming repo), dependency management (different repos may use different versions of shared libraries), tooling duplication (each repo needs its own linter config, CI setup, and build scripts), and discovery (finding relevant code across many repos requires good documentation and search tools).
Key Differences
- **Structure**: Monorepo puts all code in one repository. Polyrepo gives each project its own repository. - **Cross-project changes**: Monorepos enable atomic commits across projects. Polyrepos require separate PRs and coordinated releases. - **Code sharing**: Monorepos share code via direct imports. Polyrepos share code via published packages with explicit versioning. - **CI/CD**: Monorepos need smart build systems to determine what to test. Polyrepos have simpler per-repo pipelines. - **Tooling consistency**: Monorepos enforce one set of tools and configs. Polyrepos allow per-repo customization. - **Access control**: Polyrepos use repository-level permissions (simple). Monorepos need file/directory-level permissions (complex). - **Repository size**: Monorepos grow large, requiring Git optimizations (sparse checkout, shallow clone). Polyrepos stay small individually. - **Dependency versioning**: Monorepos keep internal dependencies at HEAD. Polyrepos pin specific versions of shared packages.
When to Use Each
**Use a monorepo** when your projects share significant code, when cross-project changes are frequent, when you want unified tooling and standards, or when your team size justifies investing in monorepo build tools (Bazel, Nx, Turborepo). Monorepos work best for tightly coupled systems and organizations that value consistency. **Use a polyrepo** when teams are highly autonomous, when projects have distinct release cycles, when access control per project is important, when the projects share little code, or when the overhead of monorepo tooling is not justified. Polyrepos are the natural default and work well for most organizations.
Analogy
A monorepo is like a single large office building where all departments share the same address, lobby, utilities, and building management. Moving furniture between floors (sharing code) is easy, but the building needs good elevator systems (build tools) to avoid congestion. A polyrepo is like a business park with separate buildings for each team: each building is independently managed, but moving equipment between buildings requires a delivery truck (package publishing and versioning).