Open-source project
golang-standards/project-layout avatar
golang-standards/project-layout

The Go Project Layout Repository: A Template, Not a Standard

Standard Go Project Layout

56,745 stars5,416 forksMakefileNOASSERTION

At a glance

What is it?
golang-standards/project-layout is a widely referenced set of directory patterns for Go applications. It is not an official standard, and its own README warns against using it for small projects. This review examines what the layout actually provides, how to apply it, and where it can mislead.
Who is it for?
Adopt this layout if you are building a medium to large Go application with multiple binaries, a public API surface, or a team that needs a common directory vocabulary. Skip it for learning projects, proofs of concept, or any codebase where a single main.go file suffices.
Can I use it commercially?
Check first. The repository uses a licence we do not classify automatically, so read its LICENSE file before any commercial use.
Is it still maintained?
Activity is slowing. The repository last received commits 6 months ago.
What is it written in?
Mainly Makefile, according to GitHub's language statistics.

Answers come from the project's GitHub data, last synced on November 15, 2026, and from our analysis. They are not legal advice.

From daily snapshots

Star history

  • golang-standards/project-layout56,745 ★ · +272
Star history
Repository2026-08-182026-11-15
golang-standards/project-layout56.5k56.7k

272 Stars in the last 89 days, measured from the daily GitHub snapshot. Compare with other projects

Editorial analysis

What This Repository Actually Is

The golang-standards/project-layout repository is not a Go module you import. It is a reference template that shows a directory structure for a Go application. The README is explicit: this is NOT an official standard defined by the core Go dev team. It is a collection of common historical and emerging patterns from the Go ecosystem. The repository contains directories like /cmd, /internal, /pkg, and a go.mod file, but each directory is mostly empty or holds a short README explaining its purpose. The primary language is listed as Makefile, which likely reflects the presence of a Makefile in the repo, but the actual content is documentation and directory scaffolding. The license is marked NOASSERTION, meaning GitHub does not identify a standard licence, although the repository contains a LICENSE.md file, which matters if you plan to copy files directly into a commercial project.

The Problem It Solves and Who It Is For

The problem is real. This layout gives a shared vocabulary for common directories: /cmd for main applications, /internal for private code, /pkg for reusable public code, plus directories like /vendor and /api. The intended audience is a team working on a medium to large application, especially one that will be imported by other projects. The README says that when you have an open source project or when other projects import your code, that is when you need private packages and the /internal directory. It also says that if you are learning Go or building a PoC, this layout is overkill, and a single main.go file and go.mod are enough. That warning is the most useful sentence in the entire repository.

How the Layout Works: /cmd, /internal, and /pkg

The core mechanism is directory naming conventions that map to Go's visibility rules. The /cmd directory holds main applications, and each subdirectory should match the executable name, for example /cmd/myapp. The README advises keeping the main function small, importing code from /internal and /pkg. The /internal directory is special: the Go compiler itself enforces that packages under /internal cannot be imported by code outside the parent directory tree. This is not a convention; it is a language feature since Go 1.4. The /pkg directory is for code that you intend to be reusable and importable by other projects. The README says to be explicit about your intentions because others will reuse your code if they can. The distinction is straightforward: if you want others to import it, put it in /pkg. If you do not, put it in /internal. The layout also supports multiple /internal directories at any level of the tree, not just the top level. That flexibility is useful for large monorepos.

Getting It Running: Commands and Configuration

There is no installation step. You clone the repository and copy what you need. The README says: Clone the repository, keep what you need and delete everything else. The go.mod file in the repo assumes your project is hosted on GitHub, but that is not a requirement. The module path can be anything, though the first component should contain a dot. The README warns that older Go versions may fail builds if the module path lacks a dot, referencing Go issues 37554 and 32819. For a new project, the practical steps are: create a directory, copy the relevant subdirectories, and edit go.mod to set your module path. The README also recommends running gofmt and staticcheck for naming and style. It explicitly says that golint is deprecated and not maintained, and points to staticcheck as the maintained alternative. There are no other commands to run; the repository is a static template.

A Genuine Limitation: It Is a Template, Not a Rulebook

The biggest limitation is that the repository gives you no guidance on what goes inside the directories. The README says it is basic in content and high level, and it does not cover structures like Clean Architecture. That means two teams can both use this layout and end up with completely different internal package structures. The /internal directory can hold a flat list of packages or a deep hierarchy; the README only says you can optionally add a bit of extra structure to separate shared and non-shared internal code. The README acknowledges that none of these patterns are used in every project, so deciding whether to use /pkg is left to you. If you adopt this layout without discussion, you may end up with ceremony that adds no value. The README also warns that for a simple project this layout is overkill, but it does not define what counts as simple.

A Real Alternative: The Official Go Module Layout

The README itself points to the official Go documentation page 'Organizing a Go module' at go.dev/doc/modules/layout. That page is the alternative. The README says that page includes the `internal` and `cmd` directory patterns and other useful information, whereas this repository adds a number of small enhancements and several supporting directories. This repository adds conventions like /api, /web, and /configs, which are useful for web applications but not required by Go.

Maintenance, License, and Upgrade Cost

The repository is not archived, its last push was 2026-04-28, and it has no GitHub releases. The README lists many translations. The upgrade cost is low because there is nothing to upgrade. You copy the template once and then it is your code. The license is marked NOASSERTION, which means GitHub does not identify a standard open source licence, although the repository contains a LICENSE.md file. That is a real concern if you copy the README or directory structure into a project that needs clear licensing. The README itself is a community effort and invites issues for new patterns, so the content can change. The practical maintenance cost is not in tracking this repository, but in deciding how strictly your team follows it. If you adopt /pkg and later decide it was a mistake, moving packages is a mechanical but tedious refactor. The README's advice to delete what you do not need is the best maintenance strategy, but it requires discipline.

Editorial conclusion

Adopt this layout if you are building a medium to large Go application with multiple binaries, a public API surface, or a team that needs a common directory vocabulary. Skip it for learning projects, proofs of concept, or any codebase where a single main.go file suffices. Before adopting, verify that your module path follows the dot-in-first-component rule if you use an older Go version, and confirm that your team agrees on the /internal vs /pkg split, because the README itself says these patterns are not universal. The repository is a template, not a standard, so clone it, strip it down, and treat every directory as optional.

Frequently asked questions

Is the Standard Go Project Layout an official standard?

No, and the document says so in bold near the top. It describes itself as a set of common historical and emerging project layout patterns in the Go ecosystem, notes that some are more popular than others, and points readers to the official Go documentation page on organizing a module instead, which covers the internal and cmd patterns.

Should I use this layout for a small Go project?

The document says not to. It states that if you are learning Go, or building a proof of concept or a simple project for yourself, this layout is an overkill, and that a single main.go file together with go.mod is more than enough. It also advises cloning the repository, keeping what you need and deleting everything else.

What does the /internal directory do in Go?

It holds private application and library code that you do not want other projects importing, and the boundary is enforced by the Go compiler rather than by convention. You can have more than one internal directory at any level of the tree, and splitting shared from non-shared internal code is described as optional rather than required.

Which linter should a Go project use?

The document names gofmt for formatting and says the previous standard linter, golint, is deprecated and not maintained, recommending a maintained linter such as staticcheck. Its linked style references are a mix, and one of them, the package style guideline, resolves to a web archive snapshot rather than the original page.

Official sources

  1. Official README
  2. Project repository
  3. README
  4. Releases
Add this badge to your README

If you maintain this project, the badge below links readers to this analysis and shows its maintenance status from the daily GitHub snapshot. Paste the markdown into your README; add ?metric=license or ?metric=stars to the image URL for a different field.

Add this badge to your README

markdown
[![Hysen Labs](https://hysenlabs.com/badge/golang-standards-project-layout.svg)](https://hysenlabs.com/projects/golang-standards-project-layout)

Star history chart for your README

markdown
[![Star history](https://hysenlabs.com/chart/golang-standards-project-layout.svg)](https://hysenlabs.com/projects/golang-standards-project-layout)

Was this useful?