Variáveis de ambiente do Python (Env Vars): Uma introdução

Este artigo foi atualizado em 15 de abril de 2026.

Os desenvolvedores de Python frequentemente lidam com dados que não querem que ninguém mais veja, como chaves de API, segredos de API, nomes de bancos de dados etc.

Uma das formas pelas quais os programadores armazenam esses segredos é nas variáveis de ambiente. Neste artigo, você aprenderá tudo o que precisa saber sobre o uso de variáveis de ambiente em Python. Mostraremos como definir variáveis de ambiente em Python, como obtê-las e as diferentes maneiras de manter todos os seus segredos protegidos. Concluiremos com um exemplo prático de como as utilizamos aqui na Vonage.

Prefere assistir em vez de ler? Confira a versão Video deste tutorial:

O que são variáveis de ambiente?

Variáveis de ambiente (frequentemente chamadas de “env vars”) são variáveis armazenadas fora do seu programa que podem afetar a forma como ele é executado. Por exemplo, você pode definir variáveis de ambiente que contenham a chave e o segredo de uma API. Seu programa poderá então usar essas variáveis ao se conectar à API.

Armazenar seus segredos no ambiente, em vez de no código-fonte, traz algumas vantagens:

• Segurança: As variáveis de ambiente ajudam a proteger dados confidenciais, como chaves de API e senhas. Por exemplo, talvez você não queira que quem baixar seu código-fonte tenha acesso a uma chave de API que você está usando.

• Gerenciamento de configuração: Com as variáveis de ambiente, é fácil armazenar e gerenciar as configurações.

• Portabilidade: É possível adaptar applications a diferentes ambientes sem alterações no código. Por exemplo, se o seu código se comportar de maneira diferente em sistemas operacionais distintos, você pode usar uma variável de ambiente para gerenciar isso.

• Testes e depuração: Os desenvolvedores podem simplificar os testes e a depuração ajustando as variáveis de ambiente, em vez de alterar o código.

Em essência, as variáveis de ambiente permitem que você altere o comportamento do seu programa sem alterar o próprio programa.

É possível armazenar variáveis de ambiente no seu sistema operacional, mas os outros métodos que abordaremos são mais comuns em situações reais; por exemplo, ao enviar mensagens de imagem RCS com Python.

Pré-requisitos

Para acompanhar o código abaixo, você precisará do seguinte:

• Python instalado no seu computador

• Um editor de texto como Visual Studio Code

Como usar variáveis de ambiente em Python

É possível obter e definir variáveis de ambiente no Python usando o módulo os módulo.

Como obter as variáveis de ambiente do Python

Para acessar o os módulo, vamos criar um arquivo Python a partir da linha de comando:

touch env-testing.py

Você pode visualizar todas as variáveis de ambiente em seu programa salvando o código a seguir em um arquivo Python e, em seguida, executando esse programa Python:

Agora abra o env-testing.py arquivo com seu editor de texto e adicione o seguinte código:

import os

os.environ

print(f"All of this operating system's environment variables: === > {os.environ}")

E execute este código na linha de comando:

python3 env-testing.py

Seu interpretador de Python deve exibir todas as variáveis de ambiente do seu sistema operacional.

É possível acessar as diferentes variáveis de ambiente os.environ como se fosse um dicionário do Python. O código abaixo mostra duas maneiras de obter variáveis de ambiente com o Python:

import os

os.environ['USER']
os.environ.get('USER')

Ambos os.environ['USER'] e os.environ.get('USER') obter a USER variável de ambiente do seu sistema operacional. No entanto, quando você usa a primeira maneira, o Python gera uma exceção se não encontrar a variável.

Você pode testar isso adicionando uma variável que não existe ao seu env-testing.py arquivo e executando o código para ver o que acontece. Usando o código abaixo, tente primeiro executá-lo exatamente como está escrito:

test_variable = os.environ['NO_VARIABLE']
# test_variable = os.environ.get('NO_VARIABLE', None)

print(f"Attempting to print nonexistent variable: ===> {test_variable}")

Você deveria comprar um KeyError: 'NO_VARIABLE'.

Agora, coloque entre comentários test_variable = os.environ['NO_VARIABLE'] e descomente test_variable = os.environ.get('NO_VARIABLE', None). Ao executar o código novamente, você deverá ver None impresso.

Uma boa prática é usar os.environ['MY_ENVIRONMENT_VARIABLE'] se a variável de ambiente for necessária para que sua aplicação em Python seja executada e os.environ.get('MY_ENVIRONMENT_VARIABLE') se for opcional.

Você também pode usar os.getenv() como alternativa a os.environ.get(). Ambos funcionam da mesma maneira e retornam None se a variável não estiver definida, mas os.getenv() pode ser um pouco mais conciso. Por exemplo:

import os
api_key = os.getenv("MY_API_KEY")

Se você escolher os.getenv() ou os.environ.get() depende principalmente da preferência e da legibilidade.

Como definir variáveis de ambiente

Para definir variáveis de ambiente em Python, você pode adicioná-las ao os.environ objeto, da mesma forma que faria com um dicionário. No entanto, apenas strings são permitidas, pois elas são passadas diretamente para o shell no qual o interpretador está sendo executado.

os.environ['USER'] = 'New User'

Para atualizar uma variável de ambiente, basta sobrescrevê-la exatamente da mesma maneira:

os.environ['USER'] = 'Modified User'

Cinco métodos para armazenar variáveis de ambiente em Python

Existem diferentes motivos pelos quais você pode querer armazenar variáveis de ambiente; portanto, também existem diferentes maneiras de armazená-las.

Às vezes, basta configurar algo no seu computador local, enquanto, em outros casos, talvez seja necessário executar seu aplicativo em ambiente de produção — esses casos de uso exigem abordagens diferentes!

A seguir, vamos mostrar cinco maneiras de armazenar variáveis de ambiente no Python:

1. Armazenamento do sistema operacional

2. Armazenamento de arquivos

3. Armazenamento em nuvem

4. Armazenamento do Universal Secret Manager

5. Armazenamento do sistema de CI/CD

Armazene variáveis de ambiente no seu sistema operacional

Às vezes, você não quer criar uma variável de ambiente usando Python se o objetivo for apenas definir algo rapidamente. Felizmente, isso pode ser feito pela linha de comando. Os exemplos que vou apresentar aqui funcionam em sistemas do tipo Unix (Mac, Linux etc.); caso contrário, confira este tutorial sobre variáveis de ambiente do Windows.

No exemplo anterior, USER havia uma variável de ambiente definida pelo seu sistema operacional, representando quem está usando o computador. Embora o sistema operacional crie essa variável automaticamente, você também pode criar suas próprias variáveis de ambiente.

Você pode ver todas as variáveis de ambiente na linha de comando abrindo um terminal e digitando o seguinte (em um sistema do tipo Unix):

Este comando `env` lista todas as variáveis disponíveis no seu shell.

Veja a seguir como criar uma variável de ambiente na linha de comando usando a sintaxe da variável `export`:

Isso cria uma variável chamada VONAGE_API e define seu valor como your_api. Você pode exibir o valor de qualquer variável desta forma:

Ao executar o código acima, você verá your_api como resultado.

Armazenar variáveis de ambiente em arquivos

Quando você cria uma nova variável de ambiente usando o terminal ou a linha de comando, ela existe apenas para aquela sessão. Ao fechar o terminal, a variável de ambiente deixa de existir. Muitas vezes, ao programar, você deseja que suas variáveis de ambiente permaneçam ativas para que possam ser usadas sempre que você executar seu código.

Uma maneira de persistir variáveis de ambiente é por meio de arquivos env; arquivos de texto simples (geralmente chamados de .env) que armazenam pares chave-valor. Isso facilita o compartilhamento de configurações entre ambientes ou membros da equipe.

Vamos criar um projeto de exemplo para demonstrar como usar um .env arquivo para armazenar variáveis de ambiente.

Primeiro, use o terminal para criar uma nova pasta para este tutorial, acesse essa pasta e crie um .env arquivo dentro dela:

Adicione esta linha ao seu .env arquivo:

Agora que estamos dentro de um ambiente virtual do Python, podemos instalar o pacote de que precisamos.

Agora podemos usar o dotenv módulo deste pacote para carregar variáveis de ambiente do .env arquivo para o ambiente ao qual o Python pode acessar com o os módulo. Crie um arquivo Python com o seguinte conteúdo:

from dotenv import load_dotenv
import os

load_dotenv()  # This line brings all environment variables from .env into os.environ
print(os.environ['VONAGE_API'])

A load_dotenv função carrega as variáveis de ambiente do .env arquivo para os.environ, onde podem ser usadas como qualquer outra variável de ambiente definida pelo seu sistema operacional.

Armazenar variáveis de ambiente na nuvem

Ao criar um software para produção, provavelmente você não o executará no seu computador. Em vez disso, é mais provável que você execute seu código em um servidor.

Isso significa que você precisa saber como definir e obter variáveis de ambiente, independentemente de onde seu código seja executado em produção.

Aqui está uma lista de provedores de nuvem e onde você pode obter mais informações sobre como lidar com variáveis de ambiente ao utilizá-los:

• AWS

• Aplicativos do Azure

• Azure Functions

• Google Cloud Functions

• Heroku

• Dockerfile

• Docker Run

Armazenar variáveis de ambiente em sistemas de CI/CD

Se você utiliza sistemas de CI/CD baseados em nuvem, como GitHub Actions, CircleCI, Travis ou Jenkins, também pode armazenar variáveis de ambiente nesses sistemas.

Se você estiver usando o GitHub para o seu projeto, poderá armazenar variáveis de ambiente nas configurações do seu repositório, acessando a aba “Configurações” e definindo chaves de API etc., na seção “Segredos e variáveis”, dentro de “Segurança”.

Aqui, você pode criar um novo segredo de repositório clicando na opção e definindo os valores. Ele estará disponível a partir de agora nas suas execuções do GitHub Actions.

Há muitas informações sobre como configurar variáveis de ambiente com o GitHub Actions, assim como CircleCI, Travis e Jenkins, além de informações sobre outros provedores.

Armazene variáveis de ambiente com um gerenciador universal de segredos

Armazenar seus segredos em um .env arquivo mantém suas variáveis de ambiente, mas apresenta alguns problemas.

Por exemplo, digamos que você faça parte de uma equipe com dez pessoas. Todos estão gerenciando seus segredos em .env arquivos, e um dos segredos muda (digamos que você receba uma nova chave de API). Nesse caso, todas as dez pessoas precisam atualizar seus .env arquivo, o que não é muito eficiente.

Ou, e se você decidir mudar do Heroku para a AWS? Nesse caso, você terá que aprender a lidar com segredos na nova plataforma, o que exige um trabalho extra.

Para resolver esses problemas, alguns programadores utilizam um gerenciador universal de segredos, como o Doppler. Um gerenciador universal de segredos permite que você armazene seus segredos em um único lugar, para que todos da sua equipe possam acessá-los.

Com um gerenciador universal de segredos, seus segredos não dependem do seu computador local nem de um provedor de nuvem; assim, você pode levá-los com você, independentemente de onde executar seu código.

Bônus: Como usar variáveis de ambiente com APIs externas

Às vezes, se você estiver usando um projeto de exemplo ou trechos de código de exemplo de uma API externa, o proprietário ou mantenedor fornece ferramentas para facilitar o uso. Frequentemente, será necessário usar variáveis de ambiente para configurar essas ferramentas da melhor maneira possível.

Aqui na Vonage, utilizamos variáveis de ambiente em nossos exemplos de código em Python para enviar SMS, fazer chamadas telefônicas, enviar códigos de verificação, verificar índices de fraude e muito mais.

Digamos que você queira usar a Number Insight API da Vonage para obter informações sobre alguns números de telefone. Nesse caso, talvez você queira usar um exemplo de código como este para colocar tudo em funcionamento rapidamente em Python.

Para usar este código de exemplo, primeiro crie um Account na Vonage (não se preocupe, é grátis!) para obter uma chave de API e um segredo para autenticar suas chamadas de API.

Em seguida, clone o repositório do GitHub. Depois de fazer isso, crie um novo ambiente virtual Python e instale as dependências necessárias:

Por fim, renomeie o .env.dist arquivo para .env e adicione sua chave e seu segredo da API ao arquivo, além de alterar o valor de INSIGHT_NUMBER para o número que você adquiriu. Você pode encontrar sua chave e seu segredo da API nas seção “Configurações da API” no Painel do Desenvolvedor da Vonage.

Depois de atualizar seu .env arquivo, você estará pronto para executar o código:

Você deve ver informações sobre o número de telefone que inseriu, o que significa que utilizou a Number Insight API da Vonage para consultar o número de telefone a partir de suas variáveis de ambiente, sem precisar editar o arquivo Python propriamente dito! Essa é uma grande vantagem de usar variáveis de ambiente.

Considerações finais

Obter e definir variáveis de ambiente é uma parte essencial da criação de software de produção. Se você concluiu este tutorial, agora já sabe como obter e definir variáveis de ambiente usando Python.

Agora você também conhece as diferentes opções para armazenar seus segredos: configurá-los temporariamente usando o sistema operacional, armazená-los em um arquivo .env, mantê-los na nuvem e usar um gerenciador universal de segredos. O método a ser utilizado dependerá das circunstâncias do projeto em que você estiver trabalhando. Se quiser saber mais, esta postagem sobre o uso de chaves privadas em variáveis de ambiente tem mais informações.

Está programando em outra linguagem além do Python? Confira nossos outros guias sobre como usar variáveis de ambiente.