Using GoLand's Integrated Go Modules Support

Quick answer: enable module-aware mode and use the Go Modules UI

When a go.mod file is present in the project root, GoLand automatically switches to module-aware mode. This gives you import-path resolution relative to the module root, context-aware code completion, and run/debug configurations that execute go run or go test with GO111MODULE=on. The built-in Go Modules UI (Settings → Go → Go Modules) lets you add, update, or replace dependencies without editing go.mod manually.

How it works: a worked example

Follow these steps to see the feature in action. All commands are run inside the project directory; no special permissions are required beyond normal file access.

1. Create a new Go module

   mkdir examplemod && cd examplemod
   go mod init example.com/examplemod
   

2. Add a simple source file

   cat > main.go <<'EOF'
   package main
   
   import (
   	"fmt"
   	"github.com/stretchr/testify/assert"
   )
   
   func main() {
   	fmt.Println("Hello, GoLand modules!")
   	assert.True(true, "assertion should pass")
   }
   EOF
   

3. Open the project in GoLand

   GoLand will show a banner at the top of the editor: "Go Modules detected. Enable module-aware mode." Click Enable or let it happen automatically.

4. Use the Go Modules UI to add a dependency
   1. Open Settings → Go → Go Modules (or press Ctrl+Alt+S → Go → Go Modules).
   2. Click the + button, enter github.com/stretchr/testify, choose the latest version, and press OK.
   3. GoLand will update go.mod and go.sum behind the scenes.
5. Verify import resolution

   Return to main.go. The import github.com/stretchr/testify/assert should be highlighted without errors, and invoking Ctrl+Space after the import shows completions from the testify package.

6. Run a test in module mode
   1. Create a test file:

   cat > main_test.go <<'EOF'
   package main
   
   import "testing"
   
   func TestHello(t *testing.T) {
   	if true != true {
   		t.Fail()
   	}
   }
   EOF
   

   2. Right-click the function name in the gutter and select Run 'TestHello' (or create a Run/Debug configuration targeting ./...).
   3. In the Run window you should see output similar to:

   === RUN   TestHello
   --- PASS: TestHello (0.00s)
   PASS
   ok	example.com/examplemod	0.001s
   module mode: on
   

7. Check the dependency graph
   1. Open View → Tool Windows → Go Modules.
   2. Click the Show dependency graph icon.
   3. By default only direct dependencies appear; toggle Show indirect dependencies to see the full graph.

Limits and common mistakes

• Go version requirement: GoLand's module-aware features rely on Go 1.16+ (the first release with full module support). If your GOROOT points to an older version, the IDE will fall back to GOPATH mode and you will see unresolved import errors. Verify with go version in the terminal embedded in GoLand.
• Cache refresh latency: After editing go.mod manually or via the UI, the dependency graph may not update instantly. The IDE shows a notification suggesting Invalidate Caches / Restart or Reload Project. Using either command forces GoLand to re-read the module metadata.
• Indirect dependencies hidden: The graph view omits indirect dependencies unless you enable the corresponding option. Forgetting this can lead to the impression that a module is unused when it is actually transitively required.
• Replace directives need a tidy: Adding a replace directive through the UI does not automatically run go mod tidy. If you see version mismatches, open a terminal in GoLand and run go mod tidy to synchronize go.mod and go.sum.
• Run/Debug configuration scope: A configuration that targets a specific package (e.g., ./cmd/myapp) still respects module mode, but if you mistakenly set the working directory to a subfolder without a go.mod, GoLand will execute the command in GOPATH mode. Ensure the Working directory points to the project root or a directory that contains a go.mod.

Practical way to confirm everything works

After completing the steps above, you can run a quick verification script:

# Inside the project root
go list -m all   # lists module and dependencies; should show github.com/stretchr/testify
GoLand: run any test; look for "module mode: on" in the output

If the list includes the expected module and the test runs with module mode enabled, the IDE's Go Modules integration is functioning correctly.