Go 1.26-1.27: Compatibilidade e manutenção

Visão geral

O que muda para quem trabalha com módulos? O Go 1.26.0 mudou a versão mínima escrita pelo go mod init, mas a mudança foi revertida no Go 1.26.1. O Go 1.27 melhorou a organização dos requisitos no go.mod e passou a conferir a compatibilidade das APIs com a versão declarada pelo módulo durante os testes.

Versão	Lançamento	Destaques para este material
1.26	Fevereiro de 2026	Mudança no `go mod init`, revertida em 1.26.1
1.27	Agosto de 2026	Organização de `require`, checagem `stdversion` e documentação por versão

Os exemplos desta página foram conferidos com Go 1.27.1.

Go 1.26: versão mínima de módulos novos

No Go 1.26.0, o go mod init passou a criar módulos com go 1.25.0.

A intenção era facilitar a compatibilidade com as versões ainda suportadas do Go. Para escolher outro mínimo, o comando pode ser seguido de go get go@versão.

Essa mudança não alterava a diretiva go dos módulos existentes. Ela foi revertida no Go 1.26.1: o comando voltou a escrever a versão do toolchain executado. Em uma verificação com Go 1.26.7, por exemplo, o arquivo recebeu go 1.26.7. O Go 1.27 mantém esse comportamento.

Go 1.27: o que muda nos módulos

Qual versão o `go mod init` escreve?

Com Go 1.27.1, um módulo novo começa assim:

$ go mod init example.com/hello
go: creating new go.mod: module example.com/hello
$ cat go.mod
module example.com/hello

go 1.27.1

O comando usa a versão do toolchain que está sendo executado. go work init também parte dessa versão e leva em conta os requisitos dos módulos incluídos.

`go mod tidy` organiza os blocos `require`

Se o módulo declara go 1.27 ou superior, o go mod tidy reúne os requisitos em até dois blocos: um para dependências diretas e outro para indiretas.

Por exemplo, um arquivo que acumulou vários blocos:

require (
    github.com/google/go-cmp v0.7.0
)

require (
    golang.org/x/text v0.23.0
)

Passa a ter um único bloco de dependências diretas, se o código importa pacotes dos dois módulos:

require (
    github.com/google/go-cmp v0.7.0
    golang.org/x/text v0.23.0
)

# Conferir o que o tidy mudaria, sem editar os arquivos
go mod tidy -diff

# Aplicar e revisar
go mod tidy
git diff -- go.mod go.sum

O -diff já existe desde Go 1.23 e retorna um status diferente de zero quando há diferenças. A novidade do Go 1.27 é a consolidação dos blocos. Comentários são preservados, mas podem mudar de posição. Um módulo que ainda declara go 1.26 mantém o comportamento anterior.

`go test` confere a versão das APIs

O go test agora inclui o analisador stdversion entre as verificações de go vet executadas por padrão.

Imagine que seu go.mod declara go 1.26.0, mas o código usa strings.CutLast, adicionado no Go 1.27. Mesmo executando os testes com Go 1.27.1, a verificação aponta:

strings.CutLast requires go1.27 or later (file is go1.26)

Você pode usar uma API disponível na versão mínima do projeto ou aumentar o requisito, se isso fizer sentido para quem usa o módulo:

go get go@1.27.0
go test ./...

Build tags também entram nessa análise. A checagem ajuda a encontrar incompatibilidades com a biblioteca padrão, mas continue testando com a versão mínima que o projeto promete suportar.

Documentação de uma versão específica

Agora dá para consultar um pacote com @versão, sem trocar a dependência do projeto:

go doc github.com/google/go-cmp/cmp@v0.7.0 Equal

O comando pode baixar o módulo para o cache, mas não altera o go.mod do projeto. Isso ajuda a conferir a API de uma dependência antes de decidir pela atualização.

Diretivas `godebug` antigas

O Go 1.27 reconhece configurações GODEBUG removidas quando aparecem em diretivas godebug ou comentários //go:debug, desde que o valor seja o comportamento definitivo.

Por exemplo, asynctimerchan=0 continua sendo aceito. Já asynctimerchan=1, que tentava restaurar o comportamento antigo dos canais de timers, causa erro nesses locais.

Se o projeto usa essas configurações, confira os valores antes de atualizar. Veja também a documentação de GODEBUG.

Fim do download direto via Bazaar

O comando go deixou de buscar módulos diretamente em repositórios Bazaar (bzr). Isso afeta dependências que ainda precisam desse acesso. É necessário disponibilizá-las por um VCS suportado ou por um proxy de módulos que consiga servi-las.

Veja como controlar os VCS permitidos em Security Features.

Atualizando um projeto

Primeiro, teste o código com o novo toolchain:

GOTOOLCHAIN=go1.27.1 go test ./...

Se o projeto vai passar a exigir Go 1.27, atualize o requisito e confira os arquivos:

go get go@1.27.0
go mod tidy
go test ./...
git diff -- go.mod go.sum

Em um workspace, você pode usar go test work para testar os pacotes de todos os módulos. Antes de publicar um módulo, entre no diretório dele e teste também com GOWORK=off go test ./....