Golang para Iniciantes: Instalação e Primeiro Programa

Resposta rápida: para começar com Go (Golang), instale a linguagem pelo site oficial, confirme a instalação com go version, crie uma pasta para o projeto, rode go mod init exemplo/ola e salve um arquivo main.go. Depois execute go run .. Você não precisa configurar GOPATH, instalar framework nem escolher uma estrutura complexa de pastas para escrever o primeiro programa.

Este é o primeiro artigo da série Golang para Iniciantes. O objetivo é sair de uma máquina sem Go para um projeto que compila, executa e possui um módulo válido. Ao final, você também entenderá o que fazem go run, go build, go fmt, go test e go mod tidy.

O nome oficial da linguagem é Go. “Golang” é apenas um apelido muito usado em pesquisas e vagas. Se você quer primeiro conhecer a história e os usos da linguagem, leia o que é Go (Golang).

O que você precisa para começar

O ambiente básico é pequeno:

A biblioteca padrão já inclui ferramentas para terminal, arquivos, JSON, HTTP, testes e concorrência. Para este tutorial, basta o toolchain oficial e um editor.

Como instalar Go no Windows, macOS e Linux

A fonte oficial para downloads é go.dev/dl. A versão usada pelo site em agosto de 2026 é Go 1.26.6, mas você deve instalar a versão estável que aparecer como recomendada na página quando estiver seguindo o tutorial.

Evite copiar de um post antigo um endereço de arquivo com versão fixa. O número, a arquitetura e até o pacote adequado podem mudar. Baixe o instalador correspondente ao seu sistema e confirme a versão depois.

Instalar Go no Windows

O caminho mais previsível para iniciantes é o instalador MSI oficial:

1. abra go.dev/dl;
2. baixe o arquivo para Windows;
3. execute o instalador e mantenha as opções padrão;
4. feche e abra o PowerShell novamente;
5. rode go version.

Se você usa WinGet, também pode instalar pelo terminal:

winget install GoLang.Go

Abra um novo PowerShell depois da instalação. Se o comando não for reconhecido, confira se o diretório de binários do Go foi adicionado ao PATH e reinicie o terminal antes de alterar variáveis manualmente.

Instalar Go no macOS

Com Homebrew:

brew install go
go version

Sem Homebrew, use o pacote para macOS disponível em go.dev/dl. Em Macs com Apple Silicon, escolha a arquitetura ARM64; em máquinas Intel, escolha AMD64. A página oficial apresenta a opção correspondente.

Instalar Go no Linux

Sua distribuição pode oferecer um pacote pronto:

# Ubuntu ou Debian
sudo apt update
sudo apt install golang-go

# Fedora
sudo dnf install golang

# Arch Linux
sudo pacman -S go

O pacote da distribuição pode ficar atrás da versão estável oficial. Isso não impede os primeiros exercícios, mas pode fazer diferença ao usar recursos recentes. Para instalar a versão publicada pelo projeto Go, siga as instruções de Linux em go.dev/doc/install, que incluem remover uma instalação manual anterior, extrair o arquivo em /usr/local e adicionar /usr/local/go/bin ao PATH.

Não extraia uma versão nova por cima de uma pasta antiga. Misturar arquivos de releases diferentes pode produzir uma instalação inconsistente.

Como verificar se Go foi instalado corretamente

Abra um terminal novo e execute:

go version

A resposta terá este formato:

go version go1.26.6 linux/amd64

Os detalhes variam:

• go1.26.6 é a versão instalada;
• linux, darwin ou windows identifica o sistema;
• amd64 ou arm64 identifica a arquitetura.

Veja também as configurações principais do toolchain:

go env GOROOT
go env GOPATH
go env GOMODCACHE

GOROOT aponta para a instalação da linguagem. GOPATH é uma área usada pelo toolchain para cache e binários instalados. Seu projeto não precisa ficar dentro do GOPATH. Com módulos, você pode criar código em qualquer pasta normal de trabalho.

Seu primeiro projeto Go, passo a passo

Crie uma pasta e entre nela:

mkdir ola-go
cd ola-go

Inicialize um módulo:

go mod init exemplo/ola-go

O comando cria go.mod:

module exemplo/ola-go

go 1.26

O caminho exemplo/ola-go funciona para aprendizado local. Em um projeto publicado, normalmente seria o endereço do repositório, como github.com/usuario/ola-go.

Agora crie main.go:

package main

import "fmt"

func main() {
	fmt.Println("Olá, Go!")
}

Execute o projeto inteiro:

go run .

Saída:

Olá, Go!

Prefira go run . a go run main.go. O ponto significa “execute o pacote desta pasta” e continua funcionando quando o programa passa a ter vários arquivos .go no mesmo pacote.

Entendendo o primeiro programa

package main

Todo arquivo Go pertence a um pacote. Um pacote chamado main, contendo uma função main, representa um programa executável.

package main

Bibliotecas normalmente usam outro nome de pacote e não possuem o ponto de entrada main.

import "fmt"

O pacote fmt pertence à biblioteca padrão e oferece funções de formatação e impressão:

import "fmt"

Go rejeita imports não utilizados. Isso evita acumular dependências sem função no arquivo.

func main()

func declara uma função. Quando você executa o programa, o runtime chama main:

func main() {
	fmt.Println("Olá, Go!")
}

fmt.Println imprime os valores e adiciona uma quebra de linha. O nome começa com maiúscula porque é exportado pelo pacote fmt.

go run, go build e o binário

Durante o aprendizado, go run . é conveniente porque compila e executa em um comando. Para gerar um arquivo executável, use:

go build

No Linux ou macOS, execute o binário com:

./ola-go

No Windows PowerShell:

.\ola-go.exe

A diferença prática é:

Um binário Go costuma ser distribuído sem exigir que a pessoa usuária instale o toolchain. Dependências e detalhes de compilação podem mudar esse comportamento, mas o modelo de entrega simples é uma das razões para a adoção de Go em CLIs, APIs e infraestrutura.

Formatação: deixe o gofmt decidir

Go possui um formato padrão. Em vez de discutir espaços, tabs ou posição de chaves, rode:

go fmt ./...

No projeto atual, ./... significa todos os pacotes abaixo da pasta. Editores com suporte a Go normalmente formatam ao salvar.

Experimente bagunçar os espaços:

package main
import "fmt"
func main(){fmt.Println("Olá, Go!")}

Depois execute go fmt ./.... O arquivo volta ao formato convencional. Essa uniformidade facilita leitura, revisão de código e colaboração.

Adicione uma função e um teste

Vamos transformar a mensagem em uma função para testar o primeiro comportamento.

Atualize main.go:

package main

import "fmt"

func saudacao(nome string) string {
	return fmt.Sprintf("Olá, %s!", nome)
}

func main() {
	fmt.Println(saudacao("Gopher"))
}

Crie main_test.go na mesma pasta:

package main

import "testing"

func TestSaudacao(t *testing.T) {
	recebido := saudacao("Ana")
	esperado := "Olá, Ana!"

	if recebido != esperado {
		t.Fatalf("recebido %q; esperado %q", recebido, esperado)
	}
}

Rode:

go test ./...

Saída esperada:

ok  	exemplo/ola-go

O arquivo termina em _test.go, e a função de teste começa com Test. O pacote testing já faz parte da biblioteca padrão. Quando quiser aprofundar, leia o guia de testes em Go.

Comandos Go que você usará no início

Não rode go get -u ./... sem entender o impacto. Atualizações em massa podem mudar várias dependências ao mesmo tempo. Para começar, deixe go mod tidy organizar imports realmente usados e versionamento indireto.

O guia de documentação Go em português explica como combinar go doc, go help, pkg.go.dev e a referência oficial.

Qual editor usar para programar em Go

VS Code

Instale a extensão Go, publicada pelo Go Team at Google. Ao abrir um arquivo .go, aceite a instalação das ferramentas sugeridas, especialmente gopls. O servidor de linguagem oferece autocomplete, navegação, diagnósticos, renomeação e documentação no editor.

Você não precisa instalar manualmente uma lista antiga de ferramentas. A extensão gerencia o conjunto compatível e informa quando uma atualização é necessária.

GoLand

O GoLand é uma IDE dedicada ao ecossistema Go. Ele inclui depurador, testes, refatorações, navegação e integração com módulos. É uma opção paga, embora a disponibilidade de modalidades gratuitas ou educacionais deva ser conferida no site da JetBrains.

Vim, Neovim e outros editores

Qualquer editor com integração ao gopls pode oferecer uma boa experiência. O essencial não é a marca do editor, mas conseguir:

• formatar ao salvar;
• enxergar erros do compilador;
• navegar para definições;
• executar testes;
• usar o depurador quando necessário.

Se você quer comparar as duas opções gráficas mais populares para Go, veja GoLand vs VS Code.

Estrutura de pastas: comece simples

Para o primeiro projeto, isto basta:

ola-go/
├── go.mod
├── main.go
└── main_test.go

Não copie uma árvore com cmd, internal, pkg, api, services, repositories e adapters antes de ter código suficiente para justificar as divisões. Go não exige um layout universal.

Quando o projeto crescer, duas pastas têm significado ou uso frequente:

• cmd/: costuma reunir diferentes programas executáveis;
• internal/: possui uma regra aplicada pelo toolchain que restringe imports externos.

A pasta pkg/ é apenas uma convenção, não uma exigência da linguagem. Muitos projetos nunca precisam dela. Para projetos maiores, leia Clean Architecture em Go sem exagero depois de construir algo simples.

Erros comuns na instalação e no primeiro projeto

go: command not found ou “go não é reconhecido”

Feche e abra o terminal. Depois confirme se o diretório de instalação está no PATH.

No Linux ou macOS:

command -v go
echo "$PATH"

No PowerShell:

Get-Command go
$env:Path

Se você instalou manualmente no Linux, confira se /usr/local/go/bin foi adicionado ao arquivo de configuração do shell correto, como ~/.bashrc ou ~/.zshrc.

go: cannot find main module

Entre na pasta do projeto e inicialize o módulo:

go mod init exemplo/ola-go

Não desative módulos com GO111MODULE=off. Esse conselho pertence a fluxos antigos e cria mais problemas em projetos atuais.

package ... is not in std

Confira o import e o diretório em que o comando está sendo executado. Para dependências externas, use o caminho de módulo indicado em pkg.go.dev ou na documentação do projeto e rode go mod tidy depois de importar o pacote no código.

Import declarado e não utilizado

Go não permite imports sem uso. Remova o import ou use o pacote. O erro é intencional e mantém o código limpo.

O código não está formatado

Rode:

go fmt ./...

Se o editor continua criando formatação diferente, habilite gofmt ou a integração oficial de Go ao salvar.

Exercícios para fixar os primeiros passos

Faça estes exercícios na mesma pasta ou crie um módulo para cada um:

1. Saudação por argumento: leia os.Args e cumprimente o nome recebido no terminal.
2. Conversor de temperatura: converta Celsius para Fahrenheit em uma função testável.
3. Contador de caracteres: receba uma string e conte runes em vez de bytes.
4. Calculadora simples: aceite dois números e uma operação.
5. Servidor HTTP local: responda “Olá, Go!” em http://localhost:8080 usando net/http.

Para o quinto exercício, continue no tutorial de API REST com Go. Ele começa pela biblioteca padrão e evolui para rotas, JSON, testes, timeouts e deploy.

Próximo passo na trilha

Agora você já consegue instalar Go, criar um módulo, executar código, gerar um binário e rodar um teste. A sequência recomendada é:

1. Sintaxe Go: variáveis, tipos, funções e structs — próximo artigo desta série;
2. Go para iniciantes — guia prático condensado;
3. Cheatsheet de sintaxe Go — consulta rápida enquanto pratica;
4. Como aprender Go — plano de estudo com projetos;
5. Curso gratuito de Golang — trilha organizada do básico ao backend;
6. Comunidade Go Brasil — grupos, meetup e canais para tirar dúvidas.

Não tente memorizar toda a linguagem antes de criar projetos. Use ciclos curtos: escreva, rode go fmt, execute go test, consulte go doc e melhore uma pequena parte por vez.

Última atualização: agosto de 2026 — instalação sem URLs de release fixas, módulos atuais, gopls, primeiro teste e troubleshooting revisado.