The release of Go 1.24 introduces the tool directive for Go modules. This simplifies the process of managing tools, such as linters or generators that are widely used in many Go projects but are not directly used in the codebase. In this blog post, we will explore what the tool directive is, why it matters, and how to use it effectively.

What Is the tool Directive?

The tool directive allows Gophers to specify dependencies for tools used in your Go project without adding those tools as regular dependencies. This is particularly useful for tools like golangci-lint, mockgen, or other command-line utilities that support your development workflow but don’t appear in your import graph.

Previously, developers had to manage such tools using workarounds, such as adding them to a tools.go or a gen.go file or manually installing them outside of Go modules. The tool directive removes this friction by providing a dedicated way to declare these dependencies.

---

Why Use the tool Directive?

Using the new tool directive offers several benefits:

1. Separation of Concerns: Tools are clearly distinguished from code dependencies, reducing confusion.
2. Version Management: You can lock specific versions of tools, ensuring consistent behavior across environments.
3. Simplified Workflow: The Go tooling can install and manage tools automatically based on the tool directive, removing the need for custom scripts or manual installation.

---

How to Add Tools to Your Module

Here’s how you can add a tool dependency using the tool directive:

Step 1: Update Your go.mod File

In your go.mod file, use the tool directive to declare the tools your project requires. For example:

module example.com/myproject

go 1.24

tool github.com/golang/mock/mockgen v1.6.0

In this example:

• github.com/golang/mock/mockgen is the path to the tool.
• v1.6.0 is the version of the tool you want to use.

Step 2: Install the Tools

After declaring tools, you can install them using the go install command:

go install github.com/golang/mock/mockgen@v1.6.0

Alternatively, you can use the new go tools install command, which installs all tools declared in the tool directives of your module:

go tools install

This command reads the tool directives from the go.mod file and installs the specified versions of all tools.

Step 3: Use the Tools

Once installed, the tools are available in your GOBIN directory (or your system’s PATH if GOBIN is not set). You can now use them as you normally would. For instance:

mockgen -source=internal/service.go -destination=internal/mocks/service_mock.go -package=mocks

---

Best Practices for Using the tool Directive

1. Pin Tool Versions: Always specify a version for your tools to ensure consistency.
2. Document Tool Usage: Include instructions in your project’s README or CONTRIBUTING file on how to install and use the tools.
3. Leverage go tools install: Simplify setup for contributors by using this command to install all tools in one step.

---

Reminder..

The tool directive is only available in Go 1.24 and later. Ensure that your contributors use this version or greater.