Import cycle not allowed in Go: How to Break the Vicious Circle

Import cycle not allowed: When Go puts up a roadblock for your code

Every Go developer eventually encounters this phrase. The compiler abruptly stops the build, issuing a dry message: import cycle not allowed. It seems the program is logical and the packages are connected "as they should be." But Go thinks otherwise.

This error is not a language whim, but a protection against chaos. Cyclic dependencies turn code into spaghetti, complicate testing, and make the build unpredictable. In this article, we will analyze why import cycle not allowed occurs, and compare three approaches to eliminating it: through interfaces, through a mediator package, and through refactoring. You will learn which method to choose depending on the situation.

Why does Go forbid circular imports?

Unlike languages with dynamic loading (Python, JavaScript), Go is compiled statically. The compiler builds a package dependency graph once. If package A imports package B, and B imports A — a cycle occurs. Go cannot resolve this order, so it aborts the compilation.

A real-world example: the users package works with users, the orders package works with orders. In orders, user information is needed, and in users, a list of orders is needed. Result: import cycle not allowed.

Typical scenario: Two packages that are "too friendly"

Let's consider a classic situation. We have two packages: users and notifier.

Package users (file users.go):

package users\n\nimport "notifier"\n\ntype User struct {\n    Name  string\n    Email string\n}\n\nfunc (u *User) SendWelcome() {\n    notifier.Notify(u.Email, "Welcome!")\n}\n

Package notifier (file notifier.go):

package notifier\n\nimport "users"\n\nfunc Notify(email, msg string) {\n    // send notification\n}\n\nfunc GetUserEmail(user *users.User) string {\n    return user.Email\n}\n

The compiler will output: import cycle not allowed: users -> notifier -> users. Both packages try to import each other. What to do?

Approach 1: Interfaces — "Divide and Conquer"

The most elegant way is to move the dependency to the interface level. Go loves explicit contracts.

Create a contracts package where we define the Notifier interface:

// contracts/contracts.go\npackage contracts\n\ntype Notifier interface {\n    Notify(email, msg string)\n}\n

Now users does not depend on notifier directly:

// users/users.go\npackage users\n\nimport "contracts"\n\ntype User struct {\n    Name  string\n    Email string\n}\n\nfunc (u *User) SendWelcome(n contracts.Notifier) {\n    n.Notify(u.Email, "Welcome!")\n}\n

And notifier implements the interface:

// notifier/notifier.go\npackage notifier\n\ntype EmailNotifier struct{}\n\nfunc (e *EmailNotifier) Notify(email, msg string) {\n    // sending logic\n}\n

Pros:

\n
• Complete absence of circular imports.
\n
• Easy testing: the implementation can be swapped.
\n
• Loose coupling.
\n

Cons:

\n
• Requires an additional package with interfaces.
\n
• Sometimes interfaces are unnecessary for simple projects.
\n

Approach 2: Mediator Package

If interfaces seem excessive, you can create a third package that acts as a "bridge" between the two conflicting packages.

Create a bridge package:

// bridge/bridge.go\npackage bridge\n\nimport (\n    "notifier"\n    "users"\n)\n\nfunc SendWelcomeToUser(user *users.User) {\n