Configuring GoLand to Use a Specific Go SDK and Enabling Go Modules

Desired Outcome

After following this guide you will have:

• A Go SDK (e.g., Go 1.22) registered in GoLand.
• The project configured to use that SDK and module mode.
• A go.mod file that defines your module path.
• Run/debug configurations that launch the correct main package.

Prerequisites

1. Go 1.22 (or the SDK you wish to use) downloaded and extracted to a clean directory, e.g. /opt/go1.22.
2. Administrative permissions if you install the SDK in a system‑wide location.
3. GoLand 2026.1 or newer (older versions may have different menu labels).

Step 1 – Register the SDK in GoLand

1. Open File → Project Structure (or press Ctrl+Alt+Shift+S on Windows/Linux, ⌘⇧⌥S on macOS).
2. In the left pane select SDKs and click the + button.
3. Choose Go from the list.
4. Navigate to the SDK root directory (e.g. /opt/go1.22) and click OK.
5. Verify the SDK appears with a valid version: the dialog will show Go 1.22.0 and a green check mark.

Tip: Avoid SDK paths that contain spaces or non‑ASCII characters; GoLand parses the path to locate binaries and may misbehave otherwise.

Step 2 – Assign the SDK to Your Project

1. In the same Project Structure dialog, click Project in the left pane.
2. Under Project SDK select the SDK you just added.
3. Optionally set the Project language level to match the SDK (e.g., 1.22).
4. Click Apply and OK to close the dialog.

Step 3 – Enable Go Modules

1. Open Settings/Preferences → Build, Execution, Deployment → Go.
2. Check Go Modules (Module mode).
3. Click Apply and OK.

When module mode is enabled GoLand automatically looks for a go.mod file in the project root. If it finds one, the SDK you assigned earlier will be used to resolve dependencies.

Step 4 – Create or Verify go.mod

Two paths exist:

• Existing module: If go.mod already exists, skip to the next section.
• No module yet: Create one.

To create a new module, open the built‑in terminal (Alt+F12) and run:

cd /path/to/your/project
go mod init github.com/yourorg/yourmodule

Replace github.com/yourorg/yourmodule with the module path you want to use. If you prefer the IDE UI, go to File → New → Go Module and follow the wizard.

Verifying Module Mode

In the terminal run:

go env GO111MODULE

The output should be on or auto when the go.mod file is present. Additionally, run:

go list -m all

to list all dependencies; a clean list indicates module mode is active.

Step 5 – Configure Run/Debug Settings

1. Open Run → Edit Configurations.
2. Click the + button and select Go Build (or Go Application if you want to run a specific binary).
3. Set the Program arguments and Working directory as needed.
4. Under Go tools ensure the Go SDK field points to the SDK you configured earlier.
5. Click Apply and OK.

To run the main package directly, choose Go Application and set the Run/Debug configuration name to the package path, e.g. ./cmd/server.

Step 6 – Expected Checks and Quick Validation

• Open the Project Structure dialog again and confirm the SDK is listed under Project SDK and SDKs.
• Run go version in the terminal; the output should match the SDK you selected (e.g., go version go1.22.0 linux/amd64).
• In the IDE, open the go.mod file and ensure the first line reads module github.com/yourorg/yourmodule.
• Use go list -m all to verify that dependencies are resolved without errors.
• Click the Run button for your configuration; the console should show a successful build and execution message.

Recovery and Troubleshooting

• SDK Path Issues: If GoLand reports “Could not find Go executable”, double‑check the SDK root and ensure go binary exists in bin/ inside the SDK directory.
• Module Mode Not Activated: Verify the go.mod file is in the root of the project and that the file name is exactly go.mod (case‑sensitive). Restart GoLand after creating the file.
• Dependency Problems: Run go mod tidy to reconcile any missing or unused dependencies. After that, rebuild the project.
• Run Configuration Uses Wrong SDK: Open the configuration dialog and confirm the Go SDK field matches the one you registered. If it points to None, set it manually.

Summary

By registering a Go SDK, enabling module mode, initializing or verifying a go.mod file, and configuring run/debug settings, you ensure GoLand uses the exact Go version you intend and that module dependencies are resolved correctly. Regularly check go version and go env GOROOT to confirm the IDE’s SDK matches the runtime environment, and keep your go.mod tidy to avoid import errors when switching SDKs.