Go Toolchain no Linux: Instalação e Troca de Versão
Instale o Go a partir de arquivos tarball oficiais ou da sua distribuição, e então deixe GOTOOLCHAIN e go.mod manterem cada módulo na versão de compilador que ele requer.
Busque em todas as páginas da documentação
Instale o Go a partir de arquivos tarball oficiais ou da sua distribuição, e então deixe GOTOOLCHAIN e go.mod manterem cada módulo na versão de compilador que ele requer.
Go no Linux é um único arquivo compactado expandido em /usr/local/go ou $HOME/go.
Fluxos de trabalho modernos utilizam o gerenciador de toolchain embutido (GOTOOLCHAIN=auto) em vez de alternadores de versão de terceiros, embora g e asdf permaneçam úteis quando você gerencia muitos projetos legados.
Esta página cobre caminhos de instalação, configuração do PATH, troca de versão e como imagens de CI devem fixar os mesmos semânticas que seu laptop usa.
Cartão de receita de referência rápida - pronto para copiar e colar.
# Instalação oficial (ajuste a arquitetura: linux-amd64, linux-arm64)
VER=1.26.0
curl -fsSL "https://go.dev/dl/go${VER}.linux-amd64.tar.gz" -o /tmp/go.tgz
sudo rm -rf /usr/local/go && sudo tar -C /usr/local -xzf /tmp/go.tgz
echo 'export PATH=/usr/local/go/bin:$PATH' >> ~/.bashrc
source ~/.bashrc
go version
# Deixe o go.mod controlar a versão do compilador (Go 1.21+)
export GOTOOLCHAIN=auto
go env GOTOOLCHAIN
# Instale uma ferramenta CLI de um módulo
go install golang.org/x/tools/gopls@latestQuando usar isso:
go.mod requer uma linha go mais nova do que o arquivo tarball do sistema fornece.go install no PATH sem um gerenciador de pacotes separado.#!/usr/bin/env bash
set -euo pipefail
# 1) Instale Go 1.26.x em /usr/local/go
INSTALL_VER="${GO_INSTALL_VERSION:-1.26.0}"
ARCH="${GO_INSTALL_ARCH:-linux-amd64}"
TARBALL="go${INSTALL_VER}.${ARCH}.tar.gz"
curl -fsSL "https://go.dev/dl/${TARBALL}" -o "/tmp/${TARBALL}"
sudo rm -rf /usr/local/go
sudo tar -C /usr/local -xzf "/tmp/${TARBALL}"
# 2) PATH para shells interativos e não-login
grep -q '/usr/local/go/bin' ~/.profile 2>/dev/null || \
echo 'export PATH=/usr/local/go/bin:$PATH' >> ~/.profile
export PATH=/usr/local/go/bin:$PATH
export GOTOOLCHAIN=auto
export GOPATH="${HOME}/go"
export PATH="${GOPATH}/bin:${PATH}"
# 3) Módulo de exemplo que requer Go 1.26
WORKDIR="${HOME}/toolchain-demo"
rm -rf "$WORKDIR"
mkdir -p "$WORKDIR"
cd "$WORKDIR"
go mod init example.com/toolchain-demo
printf 'go 1.26\n' >> go.mod
cat > main.go <<'EOF'
package main
import "fmt"
func main() {
fmt.Println("built with", "go tool version check")
}
EOF
go run .
go install golang.org/x/tools/cmd/goimports@latest
which goimports
go env GOVERSION GOTOOLCHAIN GOPATHO que isso demonstra:
GOTOOLCHAIN=auto para que o go possa baixar uma toolchain mais nova quando go.mod a exigir.GOPATH/bin no PATH para ferramentas instaladas via go install.go exercita a resolução de versão.go, gofmt e a biblioteca padrão sob GOROOT (padrão /usr/local/go).go env GOROOT e go env GOPATH separam a toolchain do seu cache de módulos e binários instalados.GOTOOLCHAIN controla se o go pode baixar outra toolchain: auto (padrão em lançamentos recentes), local (nunca baixar) ou uma versão explícita como go1.26.0.go em go.mod define a versão mínima de linguagem/toolchain; com auto, o comando pode buscar uma toolchain correspondente em $(go env GOTOOLCHAINPATH) ou no cache de módulos.go install pkg@version constrói um comando em GOPATH/bin (ou GOBIN quando definido) sem poluir o go.mod do módulo atual.| Método | Prós | Contras |
|---|---|---|
Arquivo tarball go.dev para /usr/local/go | Corresponde à documentação oficial, fácil em CI | Atualizações manuais |
Pacote da distribuição (apt install golang-go) | Rápido em laptops | Frequentemente desatualizado em relação ao Go mais recente |
GOTOOLCHAIN=auto | Mantém os módulos na versão exigida | Precisa de rede na primeira compilação |
Gerenciador de versão (g, asdf) | Troca rápida entre repositórios legados | Ferramentas extras para manter |
| Variável / arquivo | Efeito |
|---|---|
go 1.26 em go.mod | Declara a toolchain mínima; habilita recursos de linguagem daquela versão |
GOTOOLCHAIN=auto | Baixa a toolchain mais nova se o go do sistema for muito antigo |
GOTOOLCHAIN=local | Falha em vez de baixar (CI sem rede) |
toolchain go1.26.0 em go.mod | Fixa a toolchain exata para compilações reproduzíveis |
# Inspeciona a toolchain efetiva
go env GOVERSION GOTOOLCHAIN GOROOT GOPATH GOMODCACHE
# Fixa no go.mod para reprodutibilidade da equipe
go mod edit -go=1.26
go mod edit -toolchain=go1.26.0
# CI: falha rápido quando downloads de rede são proibidos
export GOTOOLCHAIN=local
go build ./...go desatualizado da distribuição - apt install golang-go pode fornecer Go 1.18 enquanto seu módulo precisa de 1.26. Correção: use o arquivo tarball oficial ou habilite GOTOOLCHAIN=auto com rede de saída.go - Conchas de CI não-login pulam o .bashrc. Correção: exporte PATH=/usr/local/go/bin:$PATH no script do job antes de qualquer invocação de go.go install não encontrado - GOPATH/bin ausente do PATH. Correção: export PATH="$(go env GOPATH)/bin:$PATH" no perfil e na CI.GOTOOLCHAIN=local em CI desatualizado - Compilações falham com incompatibilidade de toolchain em vez de se auto-curarem. Correção: inclua o arquivo tarball necessário na imagem ou permita auto./usr/bin/go ofusca /usr/local/go/bin/go. Correção: which -a go e reordene o PATH para que a instalação pretendida vença.go install - Escrevendo em /go/bin em um GOPATH de propriedade do root. Correção: defina GOPATH=$HOME/go para contas de desenvolvedor ou use um usuário de CI dedicado.| Alternativa | Use Quando | Não Use Quando |
|---|---|---|
| Arquivo tarball oficial | Você quer paridade com a documentação go.dev e imagens de CI | Você precisa de patches de segurança automáticos de um mantenedor de distribuição |
| Pacotes da distribuição | Configuração rápida de laptop com uso casual de Go | Você lança módulos na diretiva go mais recente semanalmente |
g / asdf / gvm | Muitos repositórios legados fixados em diferentes versões menores | Uma única linha de toolchain go.mod já padroniza a equipe |
| Nix / Devbox | Ambientes de desenvolvimento reproduzíveis em toda a equipe | Operadores esperam apenas habilidades de apt e tarball em servidores |
| Toolchain apenas em contêiner | Compilações nunca rodam no host | Você ainda executa go test localmente sem Docker |
/usr/local/go corresponde à documentação oficial e a muitas imagens de CI.
$HOME/go funciona sem sudo em máquinas compartilhadas.
Mantenha GOPATH separado (também comumente $HOME/go) - não confunda GOPATH com GOROOT.
Quando o binário go em execução é mais antigo do que go.mod exige, o go baixa a versão correspondente da toolchain e a armazena no cache da toolchain.
Compilações subsequentes reutilizam essa cópia.
go install module@version compila a partir do código fonte com suas configurações de proxy de módulo.
Pacotes da distribuição podem estar desatualizados e separar o gopls do compilador Go que você espera.
Instale o novo arquivo tarball sobre /usr/local/go após remover a árvore antiga.
Execute go version e um rápido go test ./... em um módulo representativo.
Sim.
Instale um go do sistema e confie em GOTOOLCHAIN=auto, ou mantenha diretórios separados (/usr/local/go1.25, /usr/local/go1.26) e troque o PATH em direnv.
No mínimo: PATH com GOROOT/bin e GOPATH/bin, política GOTOOLCHAIN (auto ou local), e GOPROXY se você usar um espelho.
Faça cache de GOMODCACHE entre jobs quando o runner permitir.
Baixe os builds linux-arm64 de go.dev/dl para servidores AArch64 e VMs Linux Apple Silicon.
Verifique com uname -m (aarch64 vs x86_64).
Ele fixa o compilador exato para compilações reproduzíveis, semelhante a arquivos de bloqueio para dependências.
Combine com GOTOOLCHAIN=local em pipelines de lançamento que não devem baixar durante a compilação.
Apenas superficialmente.
Gerenciadores de versão Node trocam runtimes por sessão de shell; GOTOOLCHAIN do Go é embutido no comando go e controlado por go.mod.
Ser propriedade do root com binários legíveis por todos é o típico.
Desenvolvedores escrevem módulos em $HOME, não dentro de GOROOT.
Defina GOPROXY=https://proxy.example.com,direct e GOSUMDB de acordo com a política de segurança antes do primeiro go mod download.
go env -w persiste as configurações em GOENV.
VMs de produção frequentemente executam apenas binários estáticos pré-compilados.
Instale a toolchain completa em agentes de compilação e máquinas de desenvolvedor, não em imagens de runtime mínimas.
Versões da Pilha: Esta página foi escrita para Go 1.26.x (padrão Green Tea GC, go fix modernizadores - verifique o patch na compilação), chi (mais recente - verifique na compilação), gin (mais recente - verifique na compilação), echo (mais recente - verifique na compilação), google.golang.org/grpc (mais recente - verifique na compilação), sigs.k8s.io/controller-runtime (mais recente - verifique na compilação), kubebuilder (mais recente - verifique na compilação), tinygo (mais recente - verifique os alvos de placa na compilação), wazero (mais recente - verifique na compilação) e golangci-lint (mais recente - verifique o conjunto de linters na compilação).
Revisado por Chris St. John·Última atualização: 19 de jul. de 2026