---
title: "Go Modules: Gerenciando Dependências em Go"
url: "https://golang.com.br/aprenda/go-modules/"
markdown_url: "https://golang.com.br/aprenda/go-modules.MD"
description: "Domine Go Modules: go mod init, go mod tidy, go.sum vs go.mod, versioning semântico e replace. Tudo que você precisa pra gerenciar dependências em Go."
date: "2026-01-30"
author: ""
---

# Go Modules: Gerenciando Dependências em Go

Domine Go Modules: go mod init, go mod tidy, go.sum vs go.mod, versioning semântico e replace. Tudo que você precisa pra gerenciar dependências em Go.


# Go Modules: Gerenciando Dependências

Desde Go 1.11, **Go Modules** é o sistema oficial para gerenciamento de dependências em Go. Antes disso, usávamos GOPATH e ferramentas como `dep` e `glide`, mas hoje Go Modules é a forma padrão e recomendada.

## O Básico

### Criando um Módulo

```bash
# Crie um diretório para seu projeto
mkdir meu-projeto
cd meu-projeto

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

Isso cria um arquivo `go.mod`:

```
module github.com/seuuser/meu-projeto

go 1.23
```

### Adicionando Dependências

```bash
# Adicionar uma dependência específica
go get github.com/gin-gonic/gin@v1.9.1

# Adicionar a versão mais recente
go get github.com/gin-gonic/gin@latest

# Adicionar dependências do código (ao importar)
go mod tidy
```

O `go.mod` é atualizado automaticamente:

```
module github.com/seuuser/meu-projeto

go 1.23

require (
    github.com/gin-gonic/gin v1.9.1
)
```

## Entendendo os Arquivos

### go.mod

Define o módulo e suas dependências:

```
module github.com/seuuser/meu-projeto

go 1.23

require (
    github.com/gin-gonic/gin v1.9.1
    github.com/lib/pq v1.10.9
)

require (
    // Dependências indiretas (das suas dependências)
    github.com/bytedance/sonic v1.10.0 // indirect
)
```

### go.sum

Contém checksums criptográficos de cada dependência:

```
github.com/gin-gonic/gin v1.9.1 h1:4idEAncQnU5c...
github.com/gin-gonic/gin v1.9.1/go.mod h1:RDnlIIZ...
```

**Sempre commite `go.sum`** — ele garante builds reproduzíveis.

## Comandos Essenciais

| Comando | Descrição |
|---------|-----------|
| `go mod init` | Cria novo módulo |
| `go mod tidy` | Sincroniza dependências com o código |
| `go get pkg@version` | Adiciona/atualiza dependência |
| `go mod download` | Baixa dependências para cache |
| `go mod verify` | Verifica integridade das dependências |
| `go mod graph` | Mostra grafo de dependências |
| `go mod why pkg` | Explica por que pkg é dependência |

## Versionamento Semântico

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

- `v1.2.3` — versão estável
- `v0.x.x` — versão de desenvolvimento (pode quebrar)
- `v2.0.0` — breaking change (requer import diferente)

### Import Paths com v2+

Para versões v2 ou superior, o import path muda:

```go
import "github.com/example/pkg"    // v0.x ou v1.x
import "github.com/example/pkg/v2" // v2.x
import "github.com/example/pkg/v3" // v3.x
```

## Trabalhando com Versões

### Atualizando Dependências

```bash
# Atualizar uma dependência específica
go get github.com/gin-gonic/gin@v1.10.0

# Atualizar todas para patch versions
go get -u=patch ./...

# Atualizar todas para minor versions
go get -u ./...
```

### Listando Versões Disponíveis

```bash
go list -m -versions github.com/gin-gonic/gin
# github.com/gin-gonic/gin v1.1.0 v1.1.1 ... v1.9.1 v1.10.0
```

### Downgrade

```bash
go get github.com/gin-gonic/gin@v1.8.0
```

## Módulos Privados

Para repositórios privados:

```bash
# Configurar acesso (adicione ao ~/.bashrc ou ~/.zshrc)
export GOPRIVATE=github.com/minhaempresa/*

# Para GitLab ou Bitbucket
export GOPRIVATE=gitlab.com/minhaempresa/*,bitbucket.org/minhaempresa/*
```

### Usando SSH ao invés de HTTPS

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

## Desenvolvimento Local

### Replace Directive

Para usar uma versão local de uma dependência:

```go
// go.mod
replace github.com/outra/lib => ../minha-lib-local
```

Útil para:
- Debugging de dependências
- Desenvolvimento simultâneo de múltiplos módulos
- Forks temporários

### Workspace (Go 1.18+)

Para projetos com múltiplos módulos:

```bash
# Criar workspace
go work init ./modulo1 ./modulo2

# Adicionar módulo
go work use ./modulo3
```

Isso cria `go.work`:

```
go 1.23

use (
    ./modulo1
    ./modulo2
    ./modulo3
)
```

## Boas Práticas

### 1. Sempre Use go mod tidy

```bash
# Antes de commit
go mod tidy
```

Remove dependências não usadas e adiciona as faltantes.

### 2. Commite go.sum

O `go.sum` garante que todos usem as mesmas versões exatas.

### 3. Atualize Regularmente

```bash
# Verifique vulnerabilidades
go install golang.org/x/vuln/cmd/govulncheck@latest
govulncheck ./...
```

### 4. Use Versões Específicas em Produção

```bash
# Evite @latest em produção
go get github.com/pkg/errors@v0.9.1  # ✓
go get github.com/pkg/errors@latest  # ✗
```

### 5. Minimize Dependências

Menos dependências = menos superfície de ataque e menos problemas de compatibilidade.

## Troubleshooting

### Cache Corrompido

```bash
go clean -modcache
```

### Checksum Mismatch

```bash
# Forçar re-download
go mod download -x
```

### Dependência não Encontrada

```bash
# Verificar proxy
echo $GOPROXY
# Padrão: https://proxy.golang.org,direct
```

## Recursos

- [Go Modules Reference](https://go.dev/ref/mod)
- [Using Go Modules](https://go.dev/blog/using-go-modules)
- [Go Module Mirror](https://proxy.golang.org/)

---

## Veja também

- [Go para Iniciantes](/aprenda/go-para-iniciantes/) — Primeiro programa e instalação
- [API REST com Go](/aprenda/api-rest-go/) — Use modules num projeto real
- [Go com Docker](/aprenda/golang-docker/) — Deploy com multi-stage build
- [Testes em Go](/aprenda/testes-go/) — Teste seu módulo com go test
- [Go Cheatsheet](/cheatsheet/) — Referência rápida de comandos Go

---

*Última atualização: Fevereiro 2026*