Como usar variáveis de ambiente com python-dotenv em Python

João Barros 08 de July de 2026 4 min de leitura

Guardar palavras-passe, chaves de API ou strings de ligação diretamente no código é um dos erros mais comuns — e mais perigosos — em projetos de dados. As variáveis de ambiente resolvem o problema: mantêm a configuração fora do código, evitam expor segredos e facilitam usar valores diferentes no teu portátil e no servidor. Em Python, a maneira mais simples de trabalhar com variáveis de ambiente é com a biblioteca python-dotenv e um ficheiro .env.

Pré-requisitos

Python 3.8 ou superior (confirma com python --version).
Um editor de código, como o Visual Studio Code.
Saber usar o terminal para instalar pacotes com pip.
De preferência, um ambiente virtual criado para o projeto.

Passo 1: Instalar o python-dotenv

A biblioteca python-dotenv lê ficheiros .env e disponibiliza esses valores ao teu programa. É leve, não tem dependências externas e instala-se com um único comando no terminal:

pip install python-dotenv

Se trabalhas dentro de um ambiente virtual, ativa-o antes de instalar para manter o pacote isolado do resto do sistema.

Passo 2: Criar o ficheiro .env

Na raiz do projeto, cria um ficheiro chamado .env — apenas o ponto seguido do nome, sem qualquer extensão. Dentro dele, escreve uma variável por linha, no formato NOME=valor, sem espaços à volta do sinal de igual:

DB_HOST=localhost
DB_USER=analytics
DB_PASSWORD=super-secreta-123
API_KEY=sk-exemplo-abcdef

Por convenção, os nomes escrevem-se em maiúsculas. Não são precisas aspas: tudo o que está à direita do sinal de igual é interpretado como texto.

Passo 3: Proteger o ficheiro .env

Um segredo só está seguro se nunca sair do teu computador. Se usas Git, adiciona o .env ao ficheiro .gitignore para garantir que ele nunca é enviado para o repositório:

echo ".env" >> .gitignore

Costuma ser útil criar também um ficheiro .env.example com os nomes das variáveis mas sem os valores reais. Assim, quem clonar o projeto sabe exatamente que configuração precisa de preencher.

Passo 4: Carregar as variáveis em Python

Com o ficheiro pronto, chega a parte do código. A função load_dotenv() procura um ficheiro .env na pasta atual e coloca cada valor no ambiente do processo. A partir daí, os.getenv() devolve o valor de cada variável pelo nome:

import os
from dotenv import load_dotenv

load_dotenv()

db_host = os.getenv("DB_HOST")
db_user = os.getenv("DB_USER")
api_key = os.getenv("API_KEY")

print(db_host, db_user)

Repara que não existe uma única palavra-passe escrita no código: todos os valores sensíveis vivem no ficheiro .env. Um pormenor importante: por omissão, o load_dotenv() não substitui variáveis que já estejam definidas no sistema. Isto é propositado, para que a configuração do servidor tenha sempre prioridade sobre o ficheiro local.

Passo 5: Valores por omissão e evitar erros

Quando uma variável não existe, o os.getenv() devolve None, o que costuma provocar um erro mais à frente no programa. Para prevenir isso, indica um valor por omissão como segundo argumento:

port = os.getenv("DB_PORT", "5432")

Se a variável for obrigatória, o melhor é validá-la logo no arranque e falhar com uma mensagem clara, em vez de deixar o erro aparecer mais tarde:

api_key = os.getenv("API_KEY")
if not api_key:
    raise RuntimeError("API_KEY not found")

Verificar o resultado

Guarda o código num ficheiro, por exemplo config_teste.py, e corre-o no terminal:

python config_teste.py

Se vires impressos o host e o utilizador corretos, a leitura funcionou. Podes ainda confirmar que o ficheiro foi mesmo encontrado, porque o load_dotenv() devolve True quando carrega um .env com sucesso e False caso contrário. Se as variáveis vierem a None, o problema mais comum é o ficheiro .env não estar na mesma pasta a partir da qual executas o script — corrige o caminho ou passa a localização exata a load_dotenv().

Conclusão

Em cinco passos separaste a configuração do código e deixaste de ter segredos escritos nos teus scripts — uma base essencial para projetos de dados seguros e fáceis de mover entre ambientes. O passo seguinte é usar estas variáveis numa ligação real, como a uma base de dados SQL Server ou a uma API. Qual vai ser o primeiro segredo que tiras do teu código: a password da base de dados ou a chave de API?