Set Up a Custom Import Path for Your Go Module in 30 Seconds

What Is a Vanity URL?

A Vanity URL gives your Go module an import path you own, instead of one tied to GitHub or GitLab.

// ❌ Long and platform-dependent
import "github.com/your-org/your-project"

// ✅ Short, branded, platform-independent
import "go.yourcompany.com/your-project"

The actual code can live on any Git server — GitHub, GitLab, Gitea, self-hosted. When you switch repositories, the import path stays the same.

This tutorial gets you there in 30 seconds.

Step 1: Install gvu (10 seconds)

Linux / macOS:

curl -fsSL gomodvanityurls.com/install.sh | bash

Windows (PowerShell):

powershell -ExecutionPolicy ByPass -c "irm https://gomodvanityurls.com/install.ps1 | iex"

Verify the installation:

$ gvu --version
gvu version 0.1.5 (built: 2026-07-09T10:00:00Z)

Step 2: Add Your First Vanity URL (20 seconds)

Say you have a GitHub repo at https://github.com/yourorg/awesome-lib and you want to import it as gomod.io/yourname/awesome-lib.

$ gvu add gomod.io/yourname/awesome-lib https://github.com/yourorg/awesome-lib.git

✔ Route created successfully!
═══════════════════════════════════════════════════════════
┃ Route ID:     m_abc123
┃ Vanity Path:  gomod.io/yourname/awesome-lib
┃ Target Repo:  https://github.com/yourorg/awesome-lib.git
┃ Quota:        1 / 5 used (4 slots remaining)
═══════════════════════════════════════════════════════════

Done. An anonymous account is created automatically — no signup, no email, no credit card.

Free users get 5 routes. Need more? Bind your email to upgrade to Verified for 10 routes + 1 custom domain:

$ gvu auth bind

Step 3: Verify It Works

In any Go project:

$ go get gomod.io/yourname/awesome-lib
go: downloading gomod.io/yourname/awesome-lib v0.1.0
go: added gomod.io/yourname/awesome-lib v0.1.0

Use it in code:

package main

import (
    "fmt"
    "gomod.io/yourname/awesome-lib"
)

func main() {
    fmt.Println(lib.Hello())
}

Works perfectly.

Advanced 1: Use Your Own Domain

gomod.io is a free shared domain — great for personal projects and quick experiments. For a more professional brand, use your own domain:

# 1. Add a DNS CNAME record
#    go.yourcompany.com → gomodvanityurls.com

# 2. Add the route
$ gvu add go.yourcompany.com/auth https://github.com/yourorg/auth-service.git

HTTPS certificates are provisioned automatically. No manual configuration needed.

Note: Custom domains require a Verified (email-bound) or Pro plan.

Advanced 2: Wildcard Routing (Pro Feature)

Got a GitHub org with 50 repos and don’t want to add routes one by one? One wildcard rule covers them all:

$ gvu add 'go.yourcompany.com/dept/*' 'https://github.com/yourorg/*.git'

This rule auto-matches:

New repos are covered automatically — no changes needed.

Advanced 3: Automatic Major Version Support

Go modules at v2+ require a /v2 suffix in the import path. gvu handles this automatically:

# You only add the base route
$ gvu add gomod.io/mylib https://github.com/yourorg/mylib.git

# v2, v3, v10... all supported automatically
import "gomod.io/mylib"      # v0.x / v1.x
import "gomod.io/mylib/v2"   # v2.x
import "gomod.io/mylib/v3"   # v3.x

No need to create separate routes for each major version.

Command Quick Reference

Next Steps

• 📖 Full documentation — install options, custom domains, troubleshooting
• 💬 GitHub Issues — report bugs and request features
• 🗣️ Community — join the discussion

Your import path should be yours to control.