Custom package name for go libraries

- 3 minutes read - 595 words
Tags Tech - Go - IA helped

I recently released a small project called I personally use this repository as a library in one of my other projects. When I do so, my import statement looks like this:

// main.go

I have two issues with this approach:

  • It’s ugly, right ?
  • If I ever change the location of my library, the import statement will break. (You may have already noticed the ‘2’ in the name.)

Most open-source projects rely on GitHub and simply use ‘’ imports. However, as you may know, GitHub is now owned by a company doesn’t care about open-source anymore. To promote the safety of open-source, we should reduce or remove our dependency on GitHub.

Having thousands of imports that specifically target is not ideal for achieving this goal.


We can use our own domain name as long as we have ownership of the hosting at that address.

// main.go


You can use GOPROXY to specify an intermediary between your go get command and the version control system (VCS), such as GitHub. This is a nice way to ensure resiliency to GitHub unavailability, among other things. However, using GOPROXY does not solve the issues of ugliness and specifying the location by name.


In your go.mod file, you can use the replace directive to specify where to fetch a package.

// go.mod
replace v0.3.1 => v0.3.1

This is useful, but not practical to do on every package. Additionally, it is the responsibility of the library user to do so.

Instead of

Alternatively, you can globally change where and how to load library code based on domains. This is often used to fetch libraries using ssh instead of https, allowing the use of credentials. It is as simple as adding this kind of configuration to your ~/.gitconfig file.

[url "ssh://"]
	insteadOf =


[url ""]
	insteadOf =

This is somewhat useful as well, but it requires the library user to perform the task and does not give you, the owner, control. Additionally, you still need to deliver the library.

Custom name

If you think about it, the only thing you can be sure you own is your domain and what’s hosted behind it. Golang allows you to redirect any URL to a proper Golang repository. It is easy and gives you control, not the library user.

For example, I changed my package name from to

// go.mod

Just doing so will work for the project itself. However, anyone who wants to use your library won’t be able to use it with the new name. Worse, they will probably have a nightmare to use it as Golang checks the name of the module in the go.mod file against the import name and fails if they do not match.

To make it work for everyone, you can simply add this to the HTML file at the URL

 <meta name=go-import content=" git">

When doing go get, Golang will check the URL and search for this meta.

Perks of custom name

With the custom name, you now have full power over the naming of your package. You can also change its location if you wish. There is no reference to GitHub, although you can still host it on GitHub. The name uses a domain that you probably own.

You also reduce the imprint of GitHub on projects using your library and can decide to migrate your code wherever you want.

Thank you reading this,
Bisoux 😗

More detailed informations:

Although commenting is not an option on this blog, I am open to discussing this topic further on various social media platforms. You can follow those links to find me
  • Published at
  • Last modified on
  • Available translation : Français
  • Published in : Tech - Go - IA helped
  • Promotions : Mastodon logo Mastodon Twitter logo Twitter
  • Except for quoted materials, which keep their original rights and attributions, post and its content published under the Creative Commons(CC BY-NC-SA 4.0) liscence
  • Found a typo, or something bigger that probably killed a grammar nazy ? suggest a fix via github.
  • You can subscribe via RSS icon RSS to get new articles as son as they are published