Get Started with gvu in 5 Minutes: Turn Vanity Import Paths from Half‑Day Ops to One Command

What is gvu

gvu is a CLI tool that maps a Go module vanity import path (e.g. mycompany.com/go/common) to the actual repository URL (GitHub, GitLab, Bitbucket, Codeberg, or self‑hosted) with a single command, eliminating the need for a govanityurls YAML file or Nginx configuration.

Installation

Linux / macOS

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

Windows (Git Bash, MSYS2, Cygwin, WSL)

The same command works; the script detects Windows and downloads the appropriate .exe.

Windows via Scoop

scoop bucket add gomodvanityurls https://github.com/gomodvanityurls/scoop-bucket
scoop install gvu

Verify installation with gvu --version.

Add your first vanity URL

Using the default domain gomod.io requires no registration or DNS configuration:

$ gvu add gomod.io/private-module https://github.com/yourorg/private-module.git

✔ Route created successfully!
════════════════════════════════════════════════════════===
┃ Route ID:     m_abc123
┃ Vanity Path:  gomod.io/private-module
┃ Target Repo:  https://github.com/yourorg/private-module.git
┃ Quota:        1 / 5 used
════════════════════════════════════════════════════════===

The command automatically creates an anonymous account and detects the hosting platform. SSH URLs are also accepted:

gvu add gomod.io/private-module ssh://[email protected]:yourorg/private-module.git

Configure Go toolchain

export GOPRIVATE=gomod.io

Add the line to ~/.bashrc or ~/.zshrc for persistence.

Use the vanity path in code

In go.mod the module line must use the vanity path:

// Correct
module gomod.io/private-module

// Incorrect – will try to fetch from GitHub directly
module github.com/yourorg/private-module

After changing the path, any team member with access to the underlying repository can import gomod.io/private-module and the Go toolchain resolves it to the real repository. The mapping can be updated later without changing import statements.

Complex repository scenarios

Monorepo : When a repository contains multiple modules, use --subdir (requires Go 1.25+):

gvu add gomod.io/module -a https://github.com/yourorg/monorepo.git --subdir go/module

Custom domain : To use a personal domain such as go.mycompany.com, upgrade to a Verified account, bind an email, and configure a DNS CNAME.

Account and quota

Anonymous accounts (created automatically by gvu add or gvu auth signup) receive five free routes. Binding an email with gvu auth bind [email protected] upgrades to a Verified account with ten routes and custom‑domain support. Check account status with:

gvu auth whoami

Managing routes

# List all routes
gvu list

# Delete a route
gvu remove m_abc123

# Batch delete
gvu remove m_abc123 m_def456 -y

Summary

The steps above install gvu, add a vanity import path, configure the Go toolchain, and manage the route without writing Nginx configs, YAML files, or managing TLS certificates.