Your Go module path is the public identity developers put in their imports, not just an address for the repository you use today. Choose a path you control and expect to keep. If you might move hosts or change accounts, a vanity path on a domain you control can separate that identity from the hosting provider—but only while you maintain the endpoint that tells Go where to find the code.
What a Go module path identifies
The module directive in go.mod declares the module path. A package’s import path is that module path followed by the package’s directory relative to the module root. For example, if the module path is example.com/acme/widget, a package in the parse subdirectory is imported as example.com/acme/widget/parse. The Go Modules Reference describes a module path as both what a module does and where to find it: Go Modules Reference: Module paths.
As an Amazon Associate I earn from qualifying purchases.
Because import statements use this path, it is part of the module’s public API. Choosing a different canonical path later is not merely changing a repository URL: consumers may need to update imports and dependency references. The Go modules migration guidance illustrates the import changes involved: Go modules: major-version updates.
Do these 3 things before closing this tab:
1Fix the driver behind crashes, sound loss and screen glitches2Repair Windows errors before they cause bigger problems3Scan for outdated or missing drivers - takes under a minuteChoose a path with a namespace you can keep
A common module path includes a repository host and account or organization name. That is convenient if you expect to keep control of that namespace. The trade-off is that the host and account become part of every consumer’s import path. If the eventual repository location is uncertain, the go.mod reference recommends using a domain or name under your control as a safe substitute rather than adopting an identity you expect to replace: Go.mod reference.
A vanity import path uses a domain you control as the public path while allowing the source repository to live elsewhere. Go tooling can discover the source location through metadata served at the path’s web endpoint. The Go Modules Reference documents this discovery mechanism: Finding a repository for a module path. Operationally, the benefit lasts only if you retain control of the domain and keep the endpoint and its metadata working. A vanity path shifts the dependency from a hosting namespace to your domain and supporting infrastructure; it does not guarantee continuity.
- Namespace control: Who can maintain the account, organization, or domain that appears in imports?
- Expected changes: Might the project move to a different host or account? If so, decide whether imports should remain unchanged across that move.
- Endpoint upkeep: If using a vanity path, who will keep its domain and Go discovery metadata available and correct?
- Versioning: Does the naming scheme leave room for Go’s required major-version suffix when the module reaches v2 or later?
Plan the path together with major versions
Go’s module path rules constrain the characters and structure of paths. For modules at major version 2 or later, the module path must include the matching major-version suffix, such as /v2; imports use that versioned path as well. The rule is part of the module’s identity, not a cosmetic label to add only to a release announcement. See the Go Modules Reference on major-version suffixes.
For example, a v1 module might use example.com/acme/widget, while its v2 module uses example.com/acme/widget/v2. Consumers of v2 import packages under the latter path. Include this convention in your naming plan before publishing a major version so the versioned path remains consistent with the module’s imports.
Changing paths is a migration, not an alias
If you change a module’s canonical path, the package imports need to match the new path. That can require changes in the module itself and in code that depends on it. Go’s migration guidance shows why a new module path is a compatibility and release-planning decision rather than a repository-only edit: Go modules: major version updates.
Rank #3
A replace directive can help a main module test a fork, alternate version, or local checkout. For instance, it can direct a module dependency to a local directory during development. It does not rewrite imports, create a public alias for the old path, or automatically affect downstream consumers: replacement directives in a dependency’s go.mod are not inherited by modules that use it. The Go Modules Reference on replace directives explains their scope. Use replace for local resolution and testing, not as a permanent path-migration system.
A module proxy changes retrieval, not identity
Go tools can retrieve module data through the configured GOPROXY list or access the version-control system associated with the module path. The documented default uses the public Go module proxy and then direct access; organizations can configure another proxy, and operating one is optional. See Go Modules Reference: Private modules and proxies.
A proxy can change how or where Go fetches module versions, which may matter for dependency control, privacy, resilience, or organizational policy. It does not change the canonical module path or the imports consumers write. A different retrieval route is therefore not a substitute for choosing a stable public identity.
What’s actually slowing this PC down?
Pick the symptom - the matching free tool is one click away.
Quick Recap
Best Value
Product prices and availability are accurate as of the date/time indicated and are subject to change. Any price and availability information displayed on Amazon at the time of purchase will apply.
