Go Toolchain en Linux: Instalación y Cambio de Versión
Instala Go desde archivos tarball oficiales o tu distribución, y luego deja que GOTOOLCHAIN y go.mod mantengan cada módulo en la versión de compilador que requiere.
//
Busca en todas las páginas de la documentación
Instala Go desde archivos tarball oficiales o tu distribución, y luego deja que GOTOOLCHAIN y go.mod mantengan cada módulo en la versión de compilador que requiere.
Go en Linux es un único archivo comprimido que se expande en /usr/local/go o $HOME/go.
Los flujos de trabajo modernos se apoyan en el gestor de toolchain integrado (GOTOOLCHAIN=auto) en lugar de selectores de versión de terceros, aunque g y asdf siguen siendo útiles cuando se manejan muchos proyectos heredados.
Esta página cubre las rutas de instalación, la configuración de PATH, el cambio de versión y cómo las imágenes de CI deben fijar la misma semántica que usa tu portátil.
Tarjeta de referencia rápida - lista para copiar y pegar.
# Instalación oficial (ajusta la arquitectura: 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
# Deja que go.mod controle la versión del compilador (Go 1.21+)
export GOTOOLCHAIN=auto
go env GOTOOLCHAIN
# Instala una herramienta CLI desde un módulo
go install golang.org/x/tools/gopls@latestCuándo usar esto:
go.mod requiere una línea go más nueva que la que proporciona el archivo tarball del sistema.go install en PATH sin un gestor de paquetes separado.#!/usr/bin/env bash
set -euo pipefail
# 1) Instala Go 1.26.x en /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 interactivos y no de inicio de sesión
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 ejemplo que requiere 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 GOPATHLo que esto demuestra:
GOTOOLCHAIN=auto para que go pueda descargar un toolchain más nuevo cuando go.mod lo exija.GOPATH/bin en PATH para herramientas instaladas a través de go install.go ejercita la resolución de versiones.go, gofmt y la biblioteca estándar bajo GOROOT (por defecto /usr/local/go).go env GOROOT y go env GOPATH separan el toolchain de tu caché de módulos y binarios instalados.GOTOOLCHAIN controla si go puede descargar otro toolchain: auto (por defecto en versiones recientes), local (nunca descargar), o una versión explícita como go1.26.0.go en go.mod establece la versión mínima del lenguaje/toolchain; con auto, el comando puede obtener un toolchain coincidente en $(go env GOTOOLCHAINPATH) o en la caché de módulos.go install pkg@version compila un comando en GOPATH/bin (o GOBIN cuando está configurado) sin contaminar el go.mod del módulo actual.| Método | Pros | Contras |
|---|---|---|
Archivo tarball de go.dev en /usr/local/go | Coincide con la documentación oficial y muchas imágenes de CI | Actualizaciones manuales |
Paquete de distribución (apt install golang-go) | Rápido en portátiles | A menudo se queda atrás de la última versión de Go |
GOTOOLCHAIN=auto | Mantiene los módulos en la versión requerida | Necesita red en la primera compilación |
Gestor de versiones (g, asdf) | Cambio rápido entre repositorios heredados | Herramientas adicionales para mantener |
| Variable / archivo | Efecto |
|---|---|
go 1.26 en go.mod | Declara el toolchain mínimo; habilita características del lenguaje de esa versión |
GOTOOLCHAIN=auto | Descarga un toolchain más nuevo si el go del sistema es demasiado viejo |
GOTOOLCHAIN=local | Falla en lugar de descargar (CI sin conexión) |
toolchain go1.26.0 en go.mod | Fija el toolchain exacto para compilaciones reproducibles |
# Inspecciona el toolchain efectivo
go env GOVERSION GOTOOLCHAIN GOROOT GOPATH GOMODCACHE
# Fija en go.mod para reproducibilidad del equipo
go mod edit -go=1.26
go mod edit -toolchain=go1.26.0
# CI: falla rápido cuando las descargas de red están prohibidas
export GOTOOLCHAIN=local
go build ./...go obsoleto en la distribución - apt install golang-go puede enviar Go 1.18 mientras tu módulo necesita 1.26. Solución: usa el archivo tarball oficial o habilita GOTOOLCHAIN=auto con red saliente.go - Los shells de CI que no son de inicio de sesión omiten .bashrc. Solución: exporta PATH=/usr/local/go/bin:$PATH en el script del trabajo antes de cualquier invocación de go.go install no encontrado - GOPATH/bin ausente de PATH. Solución: export PATH="$(go env GOPATH)/bin:$PATH" en el perfil y en CI.GOTOOLCHAIN=local en CI obsoleto - Las compilaciones fallan con desajuste de toolchain en lugar de autocurarse. Solución: integra el archivo tarball requerido en la imagen o permite auto./usr/bin/go antiguo oculta /usr/local/go/bin/go. Solución: which -a go y reordena PATH para que la instalación deseada tenga prioridad.go install - Escritura en /go/bin en un GOPATH propiedad de root. Solución: establece GOPATH=$HOME/go para cuentas de desarrollador o usa un usuario de CI dedicado.| Alternativa | Usar Cuando | No Usar Cuando |
|---|---|---|
| Archivo tarball oficial | Quieres paridad con la documentación de go.dev y las imágenes de CI | Quieres parches de seguridad automáticos de un mantenedor de distribución |
| Paquetes de distribución | Configuración rápida de portátil con uso casual de Go | Envías módulos con la última directiva go semanalmente |
g / asdf / gvm | Muchos repositorios heredados fijados a diferentes versiones menores | Una única línea de toolchain go.mod ya estandariza al equipo |
| Nix / Devbox | Entornos de desarrollo reproducibles en todo el equipo | Los operadores esperan solo habilidades de apt y archivos tarball en servidores |
| Toolchain solo en contenedor | Las compilaciones nunca se ejecutan en el host | Todavía ejecutas go test localmente sin Docker |
/usr/local/go coincide con la documentación oficial y muchas imágenes de CI.
$HOME/go funciona sin sudo en máquinas compartidas.
Mantén GOPATH separado (también comúnmente $HOME/go) - no confundas GOPATH con GOROOT.
Cuando el binario go en ejecución es más antiguo de lo que requiere go.mod, go descarga la versión de toolchain correspondiente y la almacena en la caché de toolchains.
Las compilaciones posteriores reutilizan esa copia.
go install module@version compila desde el código fuente con tus configuraciones de proxy de módulos.
Los paquetes de distribución pueden tener versiones desactualizadas y separar gopls del compilador de Go que esperas.
Instala el nuevo archivo tarball sobre /usr/local/go después de eliminar el árbol antiguo.
Ejecuta go version y un rápido go test ./... en un módulo representativo.
Sí.
Instala un go del sistema y confía en GOTOOLCHAIN=auto, o mantén directorios separados (/usr/local/go1.25, /usr/local/go1.26) y cambia PATH en direnv.
Como mínimo: PATH con GOROOT/bin y GOPATH/bin, política de GOTOOLCHAIN (auto o local), y GOPROXY si usas un espejo.
Caché GOMODCACHE entre trabajos cuando el ejecutor lo permita.
Descarga las compilaciones linux-arm64 de go.dev/dl para servidores AArch64 y VMs Linux de Apple Silicon.
Verifica con uname -m (aarch64 vs x86_64).
Fija el compilador exacto para compilaciones reproducibles, similar a los archivos de bloqueo para dependencias.
Combínalo con GOTOOLCHAIN=local en pipelines de lanzamiento que no deben descargar durante la compilación.
Solo de forma aproximada.
Los gestores de versiones de Node cambian los tiempos de ejecución por sesión de shell; GOTOOLCHAIN de Go está integrado en el comando go y controlado por go.mod.
Propiedad de root con binarios legibles por todos es lo típico.
Los desarrolladores escriben módulos bajo $HOME, no dentro de GOROOT.
Establece GOPROXY=https://proxy.example.com,direct y GOSUMDB según la política de seguridad antes de la primera go mod download.
go env -w persiste las configuraciones en GOENV.
Las VMs de producción a menudo ejecutan solo binarios estáticos precompilados.
Instala el toolchain completo en los agentes de compilación y máquinas de desarrollo, no en imágenes de tiempo de ejecución mínimas.
Versiones de la Pila: Esta página fue escrita para Go 1.26.x (valor por defecto de GC Green Tea, modernizadores de go fix - verifica el parche en la compilación), chi (última versión - verifica en la compilación), gin (última versión - verifica en la compilación), echo (última versión - verifica en la compilación), google.golang.org/grpc (última versión - verifica en la compilación), sigs.k8s.io/controller-runtime (última versión - verifica en la compilación), kubebuilder (última versión - verifica en la compilación), tinygo (última versión - verifica objetivos de placa en la compilación), wazero (última versión - verifica en la compilación), y golangci-lint (última versión - verifica el conjunto de linters en la compilación).
Revisado por Chris St. John·Última actualización: 19 jul 2026