Linux / Comando printenv: consultar variáveis de ambiente

printenv mostra os valores das variáveis de ambiente recebidas pelo programa. Com nomes de variáveis, imprime somente seus valores; sem nomes, lista o ambiente inteiro no formato nome=valor. Não altera variáveis nem executa outro programa.

Uma variável de ambiente é um par nome/valor passado a um programa pelo processo que o iniciou. Use printenv para conferir esse conteúdo e env para preparar um ambiente diferente antes de executar um comando. Os exemplos abaixo pressupõem GNU Coreutils e Bash; confirme a implementação com printenv --version e type -a printenv.

O que é o comando printenv?

Um programa recebe um conjunto de variáveis de ambiente de seu processo pai. O printenv envia todo o conjunto ou o valor de um nome específico do ambiente que recebeu para a saída padrão.

Uma variável privada do shell, o interpretador de comandos, não entra automaticamente no ambiente de programas externos. No Bash, export a marca para ser transmitida nas execuções seguintes. Isso explica por que printf pode mostrar uma variável que printenv não recebeu.

Sintaxe básica

printenv [opções] [variável...]

A sinopse usa colchetes para partes opcionais; substitua os nomes indicados. Sem nome de variável, os comandos abaixo mostram o ambiente recebido. sort apenas ordena as linhas: não transforma dados com quebras de linha internas em um formato seguro para análise.

printenv
printenv | sort

O ambiente completo pode conter tokens de autenticação e dados de acesso a serviços. Não publique a saída inteira em logs, capturas ou pedidos de suporte. Prefira consultar somente nomes necessários e use valores fictícios ao testar exemplos que listam tudo.

Consultar variáveis específicas

printenv HOME
printenv PATH
printenv LANG

Com um nome, a saída contém apenas o valor, sem o prefixo nome=. HOME normalmente indica o diretório pessoal, PATH os diretórios de busca de executáveis e LANG uma configuração de localidade. A presença e o conteúdo dessas variáveis dependem do processo; um nome ausente não produz valor. Também é possível consultar vários nomes de uma vez.

printenv HOME SHELL USER

Os valores encontrados saem na ordem dos nomes solicitados. Um nome ausente é omitido, sem linha de preenchimento, e um valor existente pode conter quebras de linha. Portanto, não associe cegamente “uma linha por variável” em relatórios ou scripts. Para identificar o nome e tratar erros, consulte cada variável separadamente.

Verificar existência pelo status de saída

No GNU printenv, o status 0 indica que todos os nomes solicitados foram encontrados; 1, que ao menos um estava ausente; 2, erro de escrita. Uma consulta a vários nomes pode imprimir valores encontrados e ainda retornar 1. O exemplo abaixo consulta um único nome, descarta o valor e distingue ausência de outras falhas, sem alterar o shell chamador.

(
  if printenv APP_ENV >/dev/null; then
    printf '%s\n' 'APP_ENV está no ambiente'
  else
    task_status=$?
    if [ "$task_status" -eq 1 ]; then
      printf '%s\n' 'APP_ENV não está no ambiente'
    else
      printf 'Falha ao consultar APP_ENV (status=%s)\n' "$task_status" >&2
    fi
    exit "$task_status"
  fi
)

Um valor vazio ainda conta como variável existente. Com APP_ENV presente, inclusive vazia, o bloco imprime a primeira mensagem e termina com 0. Se estiver ausente, imprime a segunda e termina com 1. Falhas de consulta preservam seu status e produzem um diagnóstico; não são tratadas como prova de ausência.

Comparar variável privada e exportada

Execute cada bloco em Bash no modo normal, sem habilitar set -a nem set -e para este teste. Os parênteses criam um subshell e unset garante que APP_MODE não mantenha uma marca de exportação anterior. No primeiro bloco, printf mostra development, mas printenv não imprime nada e retorna 1. Ao sair, o estado de APP_MODE no shell chamador fica preservado.

(
  unset APP_MODE
  APP_MODE=development
  printf '%s\n' "$APP_MODE"
  printenv APP_MODE
)

(
  unset APP_MODE
  APP_MODE=development
  export APP_MODE
  printenv APP_MODE
)

O segundo bloco repete a preparação e adiciona export: agora printenv mostra development e retorna 0. Uma atribuição simples não remove a marca de uma variável que já estava exportada; por isso a preparação explícita é importante para reproduzir a comparação.

Ver os diretórios de PATH em linhas separadas

Em sistemas Linux e shells Unix, PATH é uma lista de diretórios separados por dois-pontos. O comando abaixo usa tr para trocar os separadores por quebras de linha e facilitar a leitura; não modifica PATH.

printenv PATH | tr ':' '\n'

Entradas vazias podem representar o diretório atual. Procure separadores no início, no fim ou repetidos no valor original e evite depender deles ao executar programas de diretórios não confiáveis. A visualização não é uma representação sem perdas de caminhos que contenham quebras de linha. Em um pipeline, o status final normalmente vem do último comando; confira printenv PATH separadamente se precisar diagnosticar sua falha.

Separar itens com NUL: -0

printenv -0
printenv --null

-0, ou --null, termina cada item com um byte nulo (NUL), em vez de uma quebra de linha. Sem nomes, cada item é nome=valor; com nomes, cada item é somente um valor encontrado. O separador continua inequívoco quando um valor contém quebras de linha, mas só funciona se o programa consumidor também aceitar NUL.

printenv -0 | while IFS= read -r -d '' item; do
  printf '%q\n' "$item"
done

No Bash, IFS= evita a divisão por espaços, read -r preserva barras invertidas e -d '' lê até NUL. printf %q mostra cada item em uma representação com escape apropriada ao Bash; não mascara segredos. O exemplo lista o ambiente inteiro e deve ser usado somente onde essa exibição for adequada. Em automação, também verifique o status do produtor do pipeline; o término do laço sozinho não comprova que toda a leitura ocorreu sem erro.

Opções suportadas

Essas opções são da implementação GNU. Confira printenv --help e o manual local, pois outras implementações Unix podem oferecer opções diferentes.

Comparar printenv, env e printf

Você também pode ver o valor com echo "$NAME", mas em scripts, printf é mais previsível para evitar diferenças na implementação, como valores que parecem opções ou tratamento de barras invertidas.

Consultar um ambiente temporário

As duas linhas abaixo são independentes. A primeira fornece um valor fictício a um novo processo e imprime staging. A segunda remove HTTP_PROXY apenas da cópia de ambiente recebida por printenv.

env APP_ENV=staging printenv APP_ENV
env -u HTTP_PROXY printenv HTTP_PROXY

A segunda linha não imprime valor e retorna 1, pois o nome foi removido. Isso é esperado e não altera o proxy configurado no shell chamador. Consulte $? imediatamente depois de cada comando, antes que outro comando substitua o status.

A referência de comandos Linux reúne outras ferramentas para examinar o ambiente e os processos.

Por que os valores diferem para cada processo

O ambiente não é uma única tabela para todo o sistema, mas sim dados que cada processo possui. Um novo terminal, sessão SSH, serviço systemd, tarefa cron e contêiner usam diferentes processos pai e configurações de inicialização, portanto, o mesmo nome de variável pode ter um valor diferente ou pode não existir.

Ao diagnosticar problemas, você deve executar printenv no mesmo usuário, serviço e ambiente de contêiner em que o programa real está sendo executado. Não presuma que os valores visíveis no terminal sejam automaticamente passados para o serviço.

Cuidados ao exibir o ambiente

• Não publique a saída completa de printenv em chamados ou chats.
• Em integração contínua (CI), confirme o mascaramento de tokens e senhas antes de registrar diagnósticos.
• Especifique apenas os nomes das variáveis que você precisa para verificar o número mínimo de valores.
• Para verificar se um nome sensível está no ambiente, descarte o valor e examine o status, distinguindo variável ausente de erro de consulta. Isso não comprova que a credencial seja válida.
• Variáveis de ambiente podem ser expostas a ferramentas de depuração ou processos filhos com as mesmas permissões, portanto não devem ser consideradas como um repositório de segredos por si mesmas.

Problemas comuns

A variável foi definida, mas não aparece

Confirme primeiro o nome exato e se a variável está exportada. No Bash, declare -p NOME pode mostrar o atributo -x de exportação, mas também revela o valor; não o registre se for sensível. Depois de export NOME, consulte um novo processo printenv. Verifique também se o programa está rodando no mesmo shell, serviço ou contêiner em que a variável foi definida.

Como distinguir valor vazio de variável ausente?

Uma variável vazia produz uma quebra de linha com status 0; uma variável ausente não produz valor e retorna 1. O exemplo completo abaixo demonstra ambos os casos sem modificar o shell chamador. Confira cada linha status=... imediatamente após a respectiva consulta.

env EMPTY_VALUE= printenv EMPTY_VALUE
printf 'status=%s\n' "$?"
env -u EMPTY_VALUE printenv EMPTY_VALUE
printf 'status=%s\n' "$?"

A variável desaparece após sudo

O comportamento depende da política sudoers. A documentação oficial de diagnóstico do sudo explica que o padrão é executar com um ambiente mínimo e que env_keep controla variáveis preservadas. Peça ao administrador para conferir apenas o que o comando autorizado necessita; não desative a filtragem globalmente como solução genérica.

Perguntas frequentes

O printenv mostra todas as variáveis do shell atual?

Não. O programa vê o ambiente que recebeu, sem acesso direto às variáveis privadas do Bash. Comandos internos como declare permitem inspecionar variáveis e arrays do shell, respeitando o escopo em que existem; também podem revelar valores sensíveis. Uma variável local de função marcada para exportação pode ser transmitida aos processos que a função inicia.

Posso imprimir o nome e o valor de uma variável específica juntos?

printenv NOME imprime só o valor. Para um relatório simples de uma variável cuja existência já foi confirmada, pode-se usar printf 'NOME=%s\n' "$(printenv NOME)". Esse printf não preserva o status da consulta e não serve como teste de existência. A substituição de comando do Bash remove todas as quebras de linha finais; para preservar os dados, processe a saída com NUL em vez dessa forma.

É possível alterar variáveis de ambiente com printenv?

Não. printenv apenas consulta o ambiente. Para alterar o shell atual, use uma atribuição e export; para executar um programa com outro ambiente, use env NOME=VALOR comando.

Documentação oficial

• Manual do GNU Coreutils: invocação de printenv
• Manual do GNU Coreutils: invocação de env
• Manual do Bash: read e printf