---
title: "Go Modules na Prática: Guia Completo"
url: "https://golang.com.br/aprenda/go-modules-na-pratica/"
markdown_url: "https://golang.com.br/aprenda/go-modules-na-pratica.MD"
description: "Tutorial prático de Go Modules: go mod init, go mod tidy, go.sum, replace, workspace e mono-repos. Exemplos reais para gerenciar dependências em Go."
date: "2026-01-30"
author: "golang.com.br"
---

# Go Modules na Prática: Guia Completo

Tutorial prático de Go Modules: go mod init, go mod tidy, go.sum, replace, workspace e mono-repos. Exemplos reais para gerenciar dependências em Go.


Go Modules é o sistema oficial de gerenciamento de dependências do Go desde a versão 1.11. Neste guia prático, você vai aprender tudo que precisa para dominar Go Modules no dia a dia.

## O Que São Go Modules?

Go Modules é um sistema que:
- Gerencia dependências do seu projeto
- Controla versões de pacotes
- Garante builds reproduzíveis
- Elimina a necessidade do GOPATH

Cada projeto Go moderno é um "módulo" — uma coleção de pacotes Go versionados juntos.

## Criando Seu Primeiro Módulo

### Iniciando um Novo Projeto

```bash
# Crie uma pasta para seu projeto
mkdir meu-projeto
cd meu-projeto

# Inicialize o módulo
go mod init github.com/seuusuario/meu-projeto
```

Isso cria um arquivo `go.mod`:

```go
module github.com/seuusuario/meu-projeto

go 1.25
```

### Estrutura do go.mod

O arquivo `go.mod` contém:
- **module**: caminho do módulo (geralmente URL do repositório)
- **go**: versão mínima do Go necessária
- **require**: dependências diretas
- **indirect**: dependências indiretas (dependências das suas dependências)

## Adicionando Dependências

### Método 1: Import e go mod tidy

Simplesmente importe o pacote no seu código:

```go
package main

import (
    "fmt"
    "github.com/gin-gonic/gin"
)

func main() {
    r := gin.Default()
    r.GET("/", func(c *gin.Context) {
        c.JSON(200, gin.H{"message": "Olá!"})
    })
    r.Run()
}
```

Depois execute:

```bash
go mod tidy
```

O Go automaticamente:
1. Baixa a dependência
2. Adiciona ao `go.mod`
3. Cria/atualiza o `go.sum`

### Método 2: go get

```bash
# Adiciona a versão mais recente
go get github.com/gin-gonic/gin

# Adiciona uma versão específica
go get github.com/gin-gonic/gin@v1.9.1

# Adiciona a última versão de uma major
go get github.com/gin-gonic/gin@v1
```

## Entendendo Versões

### Versionamento Semântico

Go Modules usa [Semantic Versioning](https://semver.org/):

```
v1.2.3
│ │ │
│ │ └── Patch: correções de bugs
│ └──── Minor: novas features (compatível)
└────── Major: breaking changes (incompatível)
```

### Versões Especiais

```bash
# Última versão estável
go get github.com/pkg/errors@latest

# Commit específico
go get github.com/pkg/errors@abc1234

# Branch específica
go get github.com/pkg/errors@master

# Versão v2+ (caminho diferente!)
go get github.com/pkg/errors/v2
```

### Regra do v2+

Quando um módulo lança v2.0.0 ou maior, o caminho do import muda:

```go
// v1.x
import "github.com/exemplo/pacote"

// v2.x
import "github.com/exemplo/pacote/v2"
```

Isso permite que v1 e v2 coexistam no mesmo projeto.

## Comandos Essenciais

### go mod tidy

```bash
go mod tidy
```

O comando mais usado! Ele:
- Adiciona dependências faltando
- Remove dependências não usadas
- Atualiza `go.mod` e `go.sum`

**Execute sempre após modificar imports.**

### go mod download

```bash
go mod download
```

Baixa todas as dependências para o cache local. Útil para:
- CI/CD (pré-baixar deps)
- Trabalhar offline

### go mod verify

```bash
go mod verify
```

Verifica se as dependências no cache correspondem aos hashes em `go.sum`. Detecta:
- Arquivos corrompidos
- Modificações maliciosas

### go mod graph

```bash
go mod graph
```

Mostra a árvore de dependências. Útil para debugar conflitos de versão.

### go mod why

```bash
go mod why github.com/pkg/errors
```

Explica por que uma dependência existe. Mostra o caminho de import.

### go mod vendor

```bash
go mod vendor
```

Copia todas as dependências para uma pasta `vendor/`. Útil para:
- Builds offline
- Auditoria de código
- Ambientes restritos

## O Arquivo go.sum

O `go.sum` contém hashes criptográficos de cada dependência:

```
github.com/gin-gonic/gin v1.9.1 h1:4idEAncQnU5cB7BeOkPtxjfCSye0AAm1R0RVIqJ+Jmg=
github.com/gin-gonic/gin v1.9.1/go.mod h1:hPrL...
```

**Importante:**
- Sempre commite `go.sum` no git
- Nunca edite manualmente
- Garante que todos usem exatamente as mesmas dependências

## Atualizando Dependências

### Atualizar Uma Dependência

```bash
# Atualiza para a última versão minor/patch
go get -u github.com/gin-gonic/gin

# Atualiza apenas patches
go get -u=patch github.com/gin-gonic/gin

# Atualiza para versão específica
go get github.com/gin-gonic/gin@v1.10.0
```

### Atualizar Todas as Dependências

```bash
# Atualiza todas (minor/patch)
go get -u ./...

# Atualiza todas (apenas patches)
go get -u=patch ./...
```

### Verificar Atualizações Disponíveis

```bash
go list -m -u all
```

## Trabalhando com Módulos Privados

### Configurando GOPRIVATE

Para módulos em repositórios privados:

```bash
# Variável de ambiente
export GOPRIVATE=github.com/minhaempresa/*

# Ou múltiplos padrões
export GOPRIVATE=github.com/minhaempresa/*,gitlab.com/interno/*
```

Isso faz o Go:
- Não usar o proxy público
- Não verificar no checksum database

### Autenticação

Para repos privados no GitHub:

```bash
# Configurar git para usar token
git config --global url."https://SEU_TOKEN@github.com/".insteadOf "https://github.com/"
```

Ou use SSH:

```bash
git config --global url."git@github.com:".insteadOf "https://github.com/"
```

## Replace e Exclude

### Replace: Substituir Dependências

```go
// go.mod
module meu-projeto

go 1.25

require github.com/pacote/original v1.0.0

// Usar fork local durante desenvolvimento
replace github.com/pacote/original => ../meu-fork

// Ou usar outro repo
replace github.com/pacote/original => github.com/meu/fork v1.0.1
```

**Casos de uso:**
- Desenvolvimento local de dependências
- Usar forks com fixes
- Substituir por versão compatível

### Exclude: Bloquear Versões

```go
// go.mod
module meu-projeto

exclude github.com/pacote/bugado v1.2.3
```

Força o Go a escolher outra versão.

## Workspaces (Go 1.18+)

Para trabalhar com múltiplos módulos relacionados:

```bash
# Estrutura
projeto/
├── go.work
├── modulo-a/
│   └── go.mod
└── modulo-b/
    └── go.mod

# Criar workspace
go work init ./modulo-a ./modulo-b
```

Arquivo `go.work`:

```go
go 1.25

use (
    ./modulo-a
    ./modulo-b
)
```

Isso permite desenvolver módulos interdependentes sem `replace`.

**Importante:** Não commite `go.work` — é para desenvolvimento local.

## Dicas e Boas Práticas

### 1. Sempre Execute go mod tidy

Antes de commitar, sempre:

```bash
go mod tidy
git add go.mod go.sum
git commit -m "atualiza dependências"
```

### 2. Prefira Versões Estáveis

```bash
# Bom
go get github.com/pkg/errors@v0.9.1

# Evite (instável)
go get github.com/pkg/errors@master
```

### 3. Atualize Regularmente

Dependências desatualizadas acumulam vulnerabilidades. Agende atualizações mensais:

```bash
go get -u ./...
go mod tidy
go test ./...
```

### 4. Use go mod verify em CI

```yaml
# .github/workflows/ci.yml
- name: Verify dependencies
  run: go mod verify
```

### 5. Documente Replaces

Se usar `replace`, comente o motivo:

```go
// go.mod

// Temporário: aguardando merge do PR #123
replace github.com/lib/bugada => github.com/meu/fix v0.0.0-20240101
```

## Troubleshooting

### "module not found"

```bash
# Limpar cache
go clean -modcache

# Tentar novamente
go mod tidy
```

### Conflito de versões

```bash
# Ver árvore de dependências
go mod graph | grep pacote-problema

# Forçar versão específica
go get pacote-problema@v1.2.3
```

### Checksum mismatch

```bash
# Verificar
go mod verify

# Se falhar, limpar e rebaixar
go clean -modcache
go mod download
```

## Conclusão

Go Modules simplifica drasticamente o gerenciamento de dependências em Go. Os comandos mais importantes para o dia a dia são:

1. `go mod init` — criar módulo
2. `go mod tidy` — sincronizar dependências
3. `go get` — adicionar/atualizar dependências

Com essas ferramentas, você tem controle total sobre as versões do seu projeto e builds 100% reproduzíveis.

---

*Próximo passo: Aprenda sobre [Testes em Go](/aprenda/testes-go/) para garantir a qualidade do seu código.*