O módulo winreg expõe a API do Registro do Windows para Python. Com ele, um programa pode abrir chaves, ler e gravar valores, criar configurações, enumerar subchaves, remover dados e consultar metadados. O Registro é usado pelo Windows e por muitas aplicações para armazenar preferências, associações, políticas e informações de instalação.
Apesar de prático, ele não deve ser tratado como um dicionário global sem regras. A arquitetura possui hives, permissões, visualizações de 32 e 64 bits, tipos próprios e áreas protegidas. Uma alteração incorreta pode quebrar uma aplicação ou o sistema. Use o menor acesso possível e mantenha backups quando a operação for administrativa.
Disponibilidade
winreg está disponível apenas no Windows. Isole o import em código de plataforma.
import sys
if sys.platform == "win32":
import winreg
else:
winreg = None
Uma biblioteca multiplataforma deve oferecer arquivo de configuração, variável de ambiente ou outro backend quando o Registro não existir.
Hives principais
As raízes mais comuns são HKEY_CURRENT_USER, HKEY_LOCAL_MACHINE, HKEY_CLASSES_ROOT, HKEY_USERS e HKEY_CURRENT_CONFIG. Configurações do usuário normalmente pertencem a HKEY_CURRENT_USER; configurações de máquina costumam ficar em HKEY_LOCAL_MACHINE e podem exigir elevação.
Não escolha uma raiz apenas por conveniência. Defina se o dado é por usuário, por máquina, gerenciado por política ou parte da instalação.
Abra chaves com context manager
Objetos de chave podem ser usados com with, garantindo fechamento mesmo após exceções.
import winreg
caminho = r"Software\MinhaEmpresa\MeuApp"
with winreg.OpenKey(winreg.HKEY_CURRENT_USER, caminho) as chave:
valor, tipo = winreg.QueryValueEx(chave, "Tema")
print(valor, tipo)
Fechar handles é importante em processos longos e testes repetidos. Evite manter chaves abertas durante toda a vida da aplicação sem necessidade.
Crie uma chave
CreateKey() ou CreateKeyEx() cria a chave e abre um handle. A versão Ex permite escolher acesso e opções.
import winreg
caminho = r"Software\MinhaEmpresa\MeuApp"
with winreg.CreateKeyEx(
winreg.HKEY_CURRENT_USER,
caminho,
access=winreg.KEY_WRITE,
) as chave:
winreg.SetValueEx(chave, "Tema", 0, winreg.REG_SZ, "escuro")
Use um namespace claro baseado na organização e no produto. Não grave diretamente em chaves de outra aplicação.
Leia valores com QueryValueEx
QueryValueEx() retorna uma tupla com o valor e o tipo do Registro. Preserve o tipo quando ele fizer parte do contrato.
with winreg.OpenKey(winreg.HKEY_CURRENT_USER, caminho) as chave:
try:
tema, tipo = winreg.QueryValueEx(chave, "Tema")
except FileNotFoundError:
tema = "claro"
Diferencie “valor ausente” de “sem permissão”. Capturar toda exceção e retornar um padrão pode esconder uma política de segurança.
Tipos de dados
Tipos comuns incluem REG_SZ para texto, REG_EXPAND_SZ para texto com variáveis, REG_DWORD para inteiro de 32 bits, REG_QWORD para inteiro de 64 bits, REG_BINARY para bytes e REG_MULTI_SZ para lista de strings.
Não armazene um número como texto se outras ferramentas esperam DWORD. O tipo incorreto dificulta interoperabilidade e validação.
REG_EXPAND_SZ
Um valor REG_EXPAND_SZ pode conter referências como %TEMP%. QueryValueEx() retorna o texto; use ExpandEnvironmentStrings() quando precisar expandi-lo.
texto, tipo = winreg.QueryValueEx(chave, "Caminho")
if tipo == winreg.REG_EXPAND_SZ:
texto = winreg.ExpandEnvironmentStrings(texto)
Expansão não torna o caminho confiável. Normalize e valide antes de abrir arquivos ou executar programas.
Grave valores
SetValueEx() recebe handle, nome, reservado, tipo e valor. O campo reservado deve ser zero.
with winreg.CreateKeyEx(
winreg.HKEY_CURRENT_USER,
caminho,
access=winreg.KEY_SET_VALUE,
) as chave:
winreg.SetValueEx(chave, "Tentativas", 0, winreg.REG_DWORD, 3)
Solicite KEY_SET_VALUE em vez de acesso total quando só precisa escrever valores.
Valor padrão da chave
O valor padrão usa nome vazio. Embora algumas áreas do Windows dependam dele, aplicações próprias normalmente ficam mais claras com nomes explícitos.
winreg.SetValueEx(chave, "", 0, winreg.REG_SZ, "valor padrão")
Documente quando o valor sem nome fizer parte do formato.
Enumere valores
EnumValue() recebe índices começando em zero e lança OSError ao terminar.
indice = 0
while True:
try:
nome, valor, tipo = winreg.EnumValue(chave, indice)
except OSError:
break
print(nome, valor, tipo)
indice += 1
Se uma chave puder ser alterada concorrentemente, a enumeração não representa um snapshot consistente.
Enumere subchaves
EnumKey() segue o mesmo padrão. QueryInfoKey() retorna contagem de subchaves, contagem de valores e horário de modificação.
subchaves, valores, modificado = winreg.QueryInfoKey(chave)
for indice in range(subchaves):
print(winreg.EnumKey(chave, indice))
A contagem pode mudar entre a consulta e a leitura. Trate falhas sem presumir que indicam corrupção.
Exclua valores e chaves
DeleteValue() remove um valor. DeleteKey() remove uma chave vazia; subchaves precisam ser removidas primeiro ou por uma operação apropriada.
with winreg.OpenKey(
winreg.HKEY_CURRENT_USER,
caminho,
access=winreg.KEY_SET_VALUE,
) as chave:
winreg.DeleteValue(chave, "Tentativas")
Antes de uma remoção recursiva, valide que a raiz é exatamente a esperada. Um erro de path pode apagar configurações de outra aplicação.
Permissões de acesso
Máscaras como KEY_READ, KEY_WRITE, KEY_QUERY_VALUE, KEY_SET_VALUE, KEY_ENUMERATE_SUB_KEYS e KEY_CREATE_SUB_KEY controlam o acesso solicitado.
Peça apenas o necessário. Solicitar KEY_ALL_ACCESS aumenta falhas por permissão e amplia impacto de bugs.
Visualizações de 32 e 64 bits
Em Windows de 64 bits, certas áreas possuem visualizações separadas. Flags KEY_WOW64_32KEY e KEY_WOW64_64KEY selecionam explicitamente a visão.
acesso = winreg.KEY_READ | winreg.KEY_WOW64_64KEY
with winreg.OpenKey(winreg.HKEY_LOCAL_MACHINE, caminho, 0, acesso) as chave:
print(winreg.QueryValueEx(chave, "Versao"))
Não presuma que a visão escolhida pelo processo é a que contém os dados. Instaladores e integração com aplicações nativas precisam documentar a arquitetura.
Chaves remotas
ConnectRegistry() conecta a um Registro remoto quando o serviço, firewall, credenciais e políticas permitem.
Evite usar isso como mecanismo geral de gerenciamento. Prefira ferramentas administrativas autenticadas, logs de auditoria e protocolos com controle de acesso explícito.
Backup, carga e restauração
Funções como SaveKey(), LoadKey() e RestoreKey() são administrativas e podem exigir privilégios. Elas operam com arquivos de hive e têm impacto amplo.
Não execute restauração em produção sem backup verificado, janela de manutenção e plano de rollback.
Auditoria
Operações de winreg podem emitir eventos de auditoria do Python. Ambientes controlados podem usar audit hooks para observar abertura, criação e modificação de chaves.
Auditoria não substitui permissões do Windows. Use ambas.
Configuração e segredos
O Registro pode armazenar configuração, mas não transforma texto em segredo. Usuários e processos com permissão podem lê-lo. Tokens, senhas e chaves privadas devem usar mecanismos de credenciais adequados, como o Windows Credential Manager ou proteção criptográfica vinculada ao usuário.
Também evite armazenar dados grandes ou altamente estruturados quando um arquivo ou banco for mais apropriado.
Transações e consistência
Uma sequência de várias escritas pode ficar parcialmente aplicada se o processo falhar. Grave primeiro valores auxiliares, valide e altere um marcador de versão por último, ou use um formato que permita migração idempotente.
Mantenha backups e código capaz de reconhecer versões antigas.
Erros e exceções
Chave ou valor ausente normalmente gera FileNotFoundError; falta de acesso gera PermissionError ou OSError. Capture casos específicos.
try:
with winreg.OpenKey(winreg.HKEY_LOCAL_MACHINE, caminho) as chave:
valor, _ = winreg.QueryValueEx(chave, "Config")
except FileNotFoundError:
valor = None
except PermissionError as erro:
raise RuntimeError("sem acesso à configuração da máquina") from erro
Threads e concorrência
Handles diferentes podem ser usados por threads, mas a lógica de configuração ainda precisa coordenar leituras e escritas. Não suponha que várias alterações formem uma transação.
Centralize migrações e use locks de aplicação quando dois processos próprios puderem atualizar a mesma árvore.
Teste com privilégios reais
Teste como usuário comum e como administrador, em Windows 32 e 64 bits quando relevante, com Registro virtualizado, políticas corporativas, chaves ausentes e permissões negadas. Teste também upgrades e uninstall.
Não execute testes destrutivos em hives reais. Use um caminho exclusivo sob HKEY_CURRENT_USER\Software e remova-o ao final.
Erros comuns
Os erros mais frequentes são gravar em HKEY_LOCAL_MACHINE sem necessidade, pedir acesso total, esquecer a visão WOW64, salvar segredo em texto, não fechar handles, capturar qualquer erro como “não existe”, apagar árvore errada e misturar tipos de Registro.
Conclusão
winreg integra Python ao Registro do Windows com controle detalhado. Modele a configuração, escolha o hive correto, use context managers, solicite o menor acesso e trate 32/64 bits explicitamente.
Consulte a documentação oficial de winreg. Para outras rotinas específicas do Windows, leia msvcrt no Python.
