Quick answers to common questions about Gopher, the Go version manager.
A: No! Gopher works alongside your system Go installation. You can easily switch between Gopher-managed versions and your system Go using gopher use system.
A: Gopher installs Go versions in:
~/.gopher/versions/%USERPROFILE%\gopher\versions\All versions are isolated from your system Go installation.
A: Each Go version requires approximately 150-200 MB. Gopher supports auto-cleanup to manage disk space automatically. You can configure the maximum number of versions to keep in your config file.
A: Yes! Set the GOPHER_INSTALL_DIR environment variable or modify the install_dir setting in your configuration file (~/.gopher/config.json).
A:
# 1. Switch back to system Go
gopher use system
# 2. Remove Gopher binary
sudo rm /usr/local/bin/gopher # or wherever it's installed
# 3. Remove Gopher data (optional)
rm -rf ~/.gopher
A: Use any of these commands:
gopher current # Shows active version via Gopher
go version # Shows actual Go version being used
which go # Shows path to active Go binary
A: Use:
gopher list # Interactive pagination (default)
gopher --no-interactive list # Non-interactive list
gopher --json list # JSON output for scripting
A:
gopher list-remote # Interactive pagination (default)
gopher --no-interactive list-remote # Non-interactive list
A: Currently, you need to install them one at a time:
gopher install 1.21.0
gopher install 1.22.0
gopher install 1.23.0
A:
gopher uninstall 1.20.0
Note: You cannot uninstall the currently active version. Switch to another version first.
A: Absolutely! Gopher detects your system Go and allows you to switch between Gopher-managed versions and your system installation:
gopher install 1.21.0
gopher use 1.21.0 # Use Gopher version
gopher use system # Switch back to system Go
A: Gopher searches for Go in:
/opt/homebrew/opt/go on macOS)/usr/local/go, /usr/bin/go)A: No! Gopher never modifies your system Go. It uses symlinks to manage version switching without touching your system installation.
A: Yes! Simply switch versions when working on different projects:
cd ~/project1
gopher use 1.21.0
cd ~/project2
gopher use 1.22.0
Future versions will support automatic project-based version switching.
A: Gopher supports three GOPATH modes:
gopher env set gopath_mode=shared
gopher env set gopath_mode=version-specific
gopher env set gopath_mode=custom
gopher env set custom_gopath=/path/to/workspace
For most users, shared mode is recommended for easier package management.
A:
gopher env list # List all configuration options
gopher env show go1.21.0 # Show environment for specific version
A:
gopher env reset
A: Yes! Gopher automatically sets GOROOT to point to the active Go version’s installation directory.
A: After switching versions, Gopher automatically checks if $GOPATH/bin is in your PATH. This directory contains tools installed via go install.
What it means:
golangci-lint, gofumpt, etc.)To fix:
# Unix/Linux/macOS - Add to shell profile:
echo 'export PATH="$GOPATH/bin:$PATH"' >> ~/.bashrc # or ~/.zshrc
source ~/.bashrc
# Windows PowerShell:
[Environment]::SetEnvironmentVariable("PATH", "$env:GOPATH\bin;" + [Environment]::GetEnvironmentVariable("PATH", "User"), "User")
The warning appears automatically after version switches if GOPATH/bin is missing from PATH.
A: This usually means $GOPATH/bin is not in your PATH. Gopher detects and warns about this automatically after version switches.
Quick check:
# Check if GOPATH/bin is in PATH
echo $PATH | grep $(echo $GOPATH/bin)
# If empty, add it (see warning instructions from Gopher)
export PATH="$GOPATH/bin:$PATH"
Why this happens:
A:
which gopherecho $PATH | grep gopher
A:
gopher currentgo version# Reload shell configuration
source ~/.bashrc # or ~/.zshrc
ls -la $(which go)A:
gopher env set mirror_url=https://golang.google.cn/dl/
A: On Linux/macOS, ensure you have write permissions:
# Check permissions
ls -la ~/.gopher
# Fix if needed
chmod -R u+w ~/.gopher
On Windows, ensure Developer Mode is enabled (see Windows Setup Guide).
A:
gopher --verbose install 1.21.0 # Verbose output
gopher -v list # Short form
For detailed debugging, check Gopher’s log files in ~/.gopher/logs/.
A: Yes, for the best experience. Developer Mode allows Gopher to create symlinks without administrator privileges. See the Windows Setup Guide for instructions.
A: Yes! Gopher fully supports Apple Silicon. It will automatically download ARM64 versions of Go when running on Apple Silicon Macs.
A: Yes! Gopher supports multiple architectures including ARM, ARM64, x86, and x86_64.
A: Yes! Gopher works great in WSL. Follow the Linux installation instructions.
A: Yes! See EXAMPLES.md for Docker integration examples.
A: Absolutely! Gopher provides JSON output for easy scripting:
gopher --json list
gopher --json current
See EXAMPLES.md for detailed CI/CD examples.
A: Gopher uses SHA256 checksums to verify all downloads. The checksums are fetched from the official Go downloads page and verified before installation.
A: Yes! Set in your config file:
{
"auto_cleanup": true,
"max_versions": 5
}
Gopher will automatically keep only the 5 most recent versions.
A: Yes! While Gopher doesn’t automatically detect go.mod versions yet (planned for future release), you can manually switch to the required version:
# Check go.mod for required version
cat go.mod | grep "^go "
# Output: go 1.21
# Install and switch to required version
gopher install 1.21.0
gopher use 1.21.0
A: Go 1.21+ has automatic toolchain management that can download newer Go versions when your go.mod requires them. To prevent this behavior:
Option 1: Set GOTOOLCHAIN=local (Recommended)
# Add to your shell profile (~/.bashrc, ~/.zshrc, etc.)
export GOTOOLCHAIN=local
# Apply immediately
source ~/.bashrc # or ~/.zshrc
This tells Go to only use your locally installed version and never auto-download.
Option 2: Align go.mod with installed Go version
# Check your installed Go version
go version # e.g., go version go1.24.9
# Update go.mod to match
# Change: go 1.25.1
# To: go 1.24.9
Why this happens:
go.mod requires a newer version$GOPATH/pkg/mod/golang.org/toolchain@.../More info: See Go toolchain documentation
A: Use JSON output for easy parsing:
#!/bin/bash
current=$(gopher --json current | jq -r '.version')
echo "Current Go version: $current"
See EXAMPLES.md for more scripting examples.
A: Yes! Gopher v1.0+ supports version aliases:
gopher alias create stable 1.21.0
gopher use stable
See the Roadmap for alias feature details.
Last Updated: 2025-10-13
Version: 1.0
Maintainer: Gopher Development Team