The Unofficial Go Project Layout Guide That Everyone Uses
If you've spent more than five minutes in the Go community, you've probably seen someone ask "how do I structure my Go project?" and get pointed to the same GitHub repo. That repo is golang-standards/project-layout, and while it's not an official standard, it's the closest thing Go has to a community consensus on how to organize your code.
It's not a framework, not a library, and definitely not an official Go team release. It's just a well-documented repository that shows one way to lay out a Go project. And yet, thousands of developers treat it as gospel.
What It Does
This repository is essentially a reference template for Go project structure. It shows you how to organize your files and directories when building a Go application. The layout covers common patterns you'll see in production Go projects — things like where to put your cmd binaries, internal packages, API definitions, configuration files, and third-party code.
The repo doesn't force you to use any particular tool or framework. It just says "here's how many experienced Go developers organize their projects, and here's why each directory exists."
Why It's Cool
The real value here isn't the directory structure itself. It's the reasoning behind each folder. The repo explains what goes in internal/ (private packages not importable outside your project), what pkg/ is for (code you intend to share with others), and why cmd/ holds your application entry points.
Another smart touch: it covers different project types. Whether you're building a CLI tool, a web service, or a library, the layout adapts. There's guidance on where to put generated code, configuration files, and even proto definitions for gRPC services.
The community documentation is also surprisingly good. Each directory has a README that explains its purpose, so you're never left guessing. This is the kind of repo that saves junior developers from messy chaos and saves senior developers from having to explain the same patterns over and over.
How to Try It
You don't install anything. Just visit the repo, read the layout, and apply it to your next Go project. The most common approach is to clone the repo as a reference:
git clone https://github.com/golang-standards/project-layout.git
Then open the README.md and start building your project directory by directory. There's no setup, no dependencies, no build steps. It's documentation, not a tool.
If you want to see real-world examples, the repo links to several popular Go projects that follow similar layouts — things like Kubernetes, Docker, and CockroachDB. You can browse those to see the pattern in action.
Final Thoughts
This repo isn't going to write your code for you, and it won't magically make your project clean. But if you're starting a new Go project or trying to bring order to an existing one, this layout is a solid starting point. It's been battle-tested across thousands of repositories, and it works well for both small side projects and large production systems.
The best part? It's just a suggestion. You can take what works, ignore what doesn't, and never have to argue about where to put your main.go again.
Found this useful? Follow @githubprojects for more developer-friendly project highlights.