TL;DR
- Go does not allow circular imports between packages. The compiler stops the build with "import cycle not allowed".
- In repowise's index of 195 public repos with 1,000+ GitHub stars (November 2026), all 51 Python repos have circular import chains between files, and only 12 of 22 Go repos do.
- The median Go repo has 0.6% of its production files inside a circular group, against 16.4% for Python.
- To fix the Go error, pass the callee less, move shared types into a leaf package, or let the consumer define an interface.
If you have written Go for more than a week, you have seen this:
package example.com/blog/comments
imports example.com/blog/posts from comments.go
imports example.com/blog/comments from posts.go: import cycle not allowed
Most developers meet it as an annoyance. Looking at import graphs from 195 popular open-source repositories, I think it is one of the most useful errors any compiler gives you, because the numbers for Go look nothing like the numbers for every other language in the set.
How common are import cycles in Go compared with Python?
I looked at file-to-file imports in production code (tests, generated code and vendored code excluded) across 195 public repositories with 1,000+ GitHub stars. A "circular import group" here is a set of two or more files that can all reach each other through imports.
| Primary language | Repos | Repos with at least one circular group | Median share of files inside a group |
|---|---|---|---|
| Python | 51 | 100% | 16.4% |
| Rust | 15 | 93% | 22.2% |
| TypeScript | 52 | 92% | 6.4% |
| Go | 22 | 55% (12 of 22) | 0.6% |
Across all 195 repos, the median is 9.2% of production files inside a circular group.
The groups are small: across all 22 Go repos the median largest group is 2 files, and even among the 12 that have one it is 5. Where do they come from, if the compiler forbids cycles? The graph covers every production file in the repo, not only Go, so a Go project's web frontend or tooling scripts are in it too. Several of the best-known Go projects in the set have none at all among their production files:
-
gohugoio/hugo(524 production files) -
temporalio/temporal(1,502 production files) -
binwiederhier/ntfy(199 production files) -
gin-gonic/gin(57 production files)
I re-ran gin myself to check, on a fresh clone at commit 0f09c3a, and got the same answer: zero file-level cycles.
Why does Go have so few import cycles?
In Python, TypeScript and Rust, a cycle between two files is legal. Python and JavaScript runtimes load the cycle and fail only if a name is read before its module has finished running. Rust modules inside one crate can refer to each other freely. So cycles pile up quietly, and the median Python repo has one in six files inside one.
Go makes a different trade. The unit of compilation is the package, a package is a directory, and the import graph between packages must be a DAG. Files inside one package do not import each other at all, they share a namespace. So the only cycle you can create is between packages, and the compiler refuses it.
That one rule pushes every Go codebase toward the same shape: low-level packages that import nothing from the project, and higher-level packages that import them. You can see it in gin. This prints every import from one gin package to another (I swapped the module path for gin to keep it short):
go list -f '{{.ImportPath}}: {{join .Imports " "}}' ./... \
| sed 's#github.com/gin-gonic/gin#gin#g' | tr ' ' '\n' \
| awk '/:$/{p=$0; next} /^gin/{print p, $0}'
gin: gin/binding
gin: gin/codec/json
gin: gin/internal/bytesconv
gin: gin/internal/fs
gin: gin/render
gin/binding: gin/codec/json
gin/binding: gin/internal/bytesconv
gin/ginS: gin
gin/render: gin/codec/json
gin/render: gin/internal/bytesconv
gin/render: gin/internal/fs
Every arrow points down. internal/bytesconv, internal/fs and codec/json import nothing from gin. binding and render sit on top of them, the root gin package uses all of them, and ginS (the singleton helper) is the only thing that imports the root. The compiler makes every other shape fail to build.
How do you fix "import cycle not allowed" in Go?
Here is the smallest version of the cycle from the top of the post. posts wants to list a post's comments, and comments wants to take a Post:
// posts/posts.go
package posts
import "example.com/blog/comments"
type Post struct {
ID int
Title string
}
func (p Post) Comments() []comments.Comment { return comments.ForPost(p) }
// comments/comments.go
package comments
import "example.com/blog/posts"
type Comment struct {
PostID int
Body string
}
func ForPost(p posts.Post) []Comment { return nil }
go build ./... prints the error above. Three fixes, each tested with Go 1.26.
1. Pass what the callee needs, not the whole type
comments only needs the post's ID. Take an int and the import disappears:
// comments/comments.go
package comments
type Comment struct {
PostID int
Body string
}
func ForPost(postID int) []Comment { return nil }
$ go build ./... && go list -f '{{.ImportPath}}: {{join .Imports " "}}' ./...
example.com/blog/comments:
example.com/blog/posts: example.com/blog/comments
This is the fix to try first. Most cycles come from passing a big struct where one field would do.
2. Move the shared types into a leaf package
When both sides really need the same types, put them in a package that imports nothing from the project:
// model/model.go
package model
type Post struct {
ID int
Title string
}
type Comment struct {
PostID int
Body string
}
$ go build ./... && go list -f '{{.ImportPath}}: {{join .Imports " "}}' ./...
example.com/blog/comments: example.com/blog/model
example.com/blog/model:
example.com/blog/posts: example.com/blog/comments example.com/blog/model
This is the shape of gin's internal/bytesconv and codec/json. The risk is a model or types package that grows into a dumping ground, so keep it to types that really are shared.
3. Let the consumer define an interface
If comments needs behaviour from a post, declare the behaviour it needs in comments and let posts.Post satisfy it without either side naming the other's types:
// comments/comments.go
package comments
type Commentable interface{ CommentKey() int }
type Comment struct {
PostID int
Body string
}
func ForPost(c Commentable) []Comment { return nil }
// posts/posts.go
package posts
import "example.com/blog/comments"
type Post struct {
ID int
Title string
}
func (p Post) CommentKey() int { return p.ID }
func (p Post) Comments() []comments.Comment { return comments.ForPost(p) }
$ go build ./... && go list -f '{{.ImportPath}}: {{join .Imports " "}}' ./...
example.com/blog/comments:
example.com/blog/posts: example.com/blog/comments
Go interfaces are satisfied implicitly, so comments never imports posts. This is the standard Go answer when the dependency is about behaviour, and it also makes comments easy to test with a fake.
What other languages can take from this
You cannot add Go's rule to Python or TypeScript, but you can get most of the effect with a lint rule that fails the build on new cycles and the same three fixes: pass less, move shared types down, depend on an interface. The full walkthrough for finding cycles in TypeScript, Python and Go monorepos, including the folder-level and module-level cycles Go still allows, is in this guide.
To see the layering of a larger Go codebase, the hugo architecture view shows its packages and the import edges between them.
If you have broken up a large Go package to get rid of a cycle, which of the three fixes did you end up using?
How I got these numbers
The cohort is 195 of the most-starred public repositories indexed on repowise (1,000+ GitHub stars each, 253,688 production source files, November 2026). "Primary language" is GitHub's label for the repo, and the file counts include every production source file in the repo, so a Go project with a web frontend has its frontend files in the graph too. Each repo is measured at its own latest index, between May and November 2026. The gin check was repowise init --yes --no-prose --no-editor-setup on a fresh clone, then a strongly connected components pass over the stored file import graph. The Go snippets were built with go version go1.26.4 windows/amd64.
FAQ
What does "import cycle not allowed" mean in Go?
It means two or more packages import each other, directly or through a chain, and Go requires the import graph between packages to have no cycles. The error lists the chain of imports so you can see which edge to break.
How do I fix "import cycle not allowed" in tests?
Usually the test file is in package foo and imports a package that itself imports foo. Move the test to an external test package by declaring package foo_test in the same directory. It is compiled as a separate package, imports foo like any other caller, and the cycle goes away.
Does Go allow circular imports?
Not between packages: the compiler refuses to build them. Files inside one package never import each other, because they share a namespace, so the package is the only level where a cycle could form.
Top comments (0)