Importação de pacotes locais em Go: guia passo a passo com código

Por que a importação de pacotes locais em Go gera tantas dúvidas?

Se você já tentou organizar código Go em arquivos e pastas separados, certamente já se deparou com um erro como could not import "myproject/utils". Este é um dos problemas mais comuns entre desenvolvedores Go iniciantes. No Stack Overflow, a pergunta "How to import local packages in go?" acumulou milhares de visualizações — e não é à toa.

Diferente do Python, onde basta colocar o arquivo ao lado e escrever import mymodule, o Go exige uma estrutura clara e a configuração correta de módulos. Mas, uma vez dominado esse mecanismo, você perceberá o quão elegante ele é. Vamos entender de uma vez por todas.

Breve teoria: como o Go entende pacotes

Antes de escrever código, lembre-se de três princípios-chave:

\n
• Go é uma linguagem com estrutura modular rígida. Cada diretório é um pacote (package).
\n
• O nome do pacote não precisa coincidir com o nome da pasta, mas é altamente recomendado fazê-lo para legibilidade.
\n
• A importação de pacotes locais desde 2019 é feita através de módulos (Go modules). Esqueça o GOPATH — use go mod.
\n

Agora vamos à prática.

Passo 1: Criando um projeto com módulo

Abra o terminal e crie uma nova pasta para o seu projeto:

mkdir go-local-imports\ncd go-local-imports\n

Agora inicialize o módulo. O nome do módulo pode ser qualquer um, mas é lógico usar um caminho que seja único (por exemplo, um link para o repositório):

go mod init github.com/seu-usuario/go-local-imports\n

Após este comando, o arquivo go.mod aparecerá na pasta. Será ele quem gerenciará as dependências — tanto locais quanto externas.

Passo 2: Criando um pacote local

Vamos criar a pasta utils dentro do projeto. Dentro dela, o arquivo math.go:

mkdir utils\ncd utils\ntouch math.go\n

Abra utils/math.go e escreva:

package utils\n\n// Add retorna a soma de dois números inteiros\nfunc Add(a, b int) int {\n    return a + b\n}\n

Observe: a função Add foi escrita com letra maiúscula. Em Go, isso significa que ela é exportada (pública). Se escrever add — ela será privada e inacessível de outros pacotes.

Passo 3: Importando e usando o pacote local

Volte para a pasta raiz do projeto e crie main.go:

cd ..\ntouch main.go\n

Conteúdo de main.go:

package main\n\nimport (\n    "fmt"\n    "github.com/seu-usuario/go-local-imports/utils"\n)\n\nfunc main() {\n    result := utils.Add(3, 5)\n    fmt.Println("Soma:", result)\n}\n

Agora execute o programa:

go run main.go\n

Você deve ver:

Soma: 8\n

Tudo funcionando! Mas se você recebeu um erro — leia a próxima seção.

Erros típicos e suas soluções

Erro 1: "package is not in GOROOT"

Você vê algo como:

package myproject/utils is not in GOROOT (/usr/local/go/src/myproject/utils)

Causa: Você está tentando importar um pacote sem módulo. O Go o procura na biblioteca padrão, e não no seu projeto.

Solução: Certifique-se de que existe um go.mod na raiz do projeto. Se não houver, execute go mod init nome-do-modulo.

Erro 2: "undefined: utils.Add"

Causa: A função foi escrita com letra minúscula (privada), ou você importou o pacote mas não está usando o nome dele.

Solução: Verifique se todas as funções necessárias estão exportadas (com letra maiúscula), e se você está se referindo a elas