El módulo winreg expone la API del Registro de Windows para Python. Un programa puede abrir claves, leer y escribir valores, crear árboles de configuración, enumerar subclaves, eliminar datos y consultar metadatos. Windows y muchas aplicaciones de escritorio usan el Registro para preferencias, asociaciones de archivos, políticas, información de instalación y ajustes específicos del equipo.
Aunque la API es práctica, el Registro no debe tratarse como un diccionario global sin restricciones. Tiene hives, listas de control de acceso, vistas separadas de 32 y 64 bits, tipos de datos propios, reglas de virtualización y áreas protegidas. Un cambio incorrecto puede romper una aplicación o afectar al sistema. Solicita el acceso mínimo necesario y crea backups antes de realizar operaciones administrativas.
Disponibilidad
winreg está disponible únicamente en Windows. Mantén el import dentro de una capa específica de plataforma.
import sys
if sys.platform == "win32":
import winreg
else:
winreg = None
Una aplicación multiplataforma debería ofrecer archivo de configuración, variables de entorno, base de datos u otro backend cuando el Registro no exista.
Hives principales
Las raíces más comunes son HKEY_CURRENT_USER, HKEY_LOCAL_MACHINE, HKEY_CLASSES_ROOT, HKEY_USERS y HKEY_CURRENT_CONFIG. Las preferencias de cada usuario suelen pertenecer a HKEY_CURRENT_USER. Los ajustes de toda la máquina suelen ubicarse en HKEY_LOCAL_MACHINE y pueden requerir elevación.
Elige el hive según propiedad y ciclo de vida, no por comodidad. Decide si el dato pertenece a un usuario, a todos, a un instalador, a una política administrada o al propio sistema operativo.
Usa context managers
Los objetos de clave admiten with, lo que garantiza el cierre del handle nativo incluso cuando ocurre una excepción.
import winreg
ruta = r"Software\EmpresaEjemplo\AplicacionEjemplo"
with winreg.OpenKey(winreg.HKEY_CURRENT_USER, ruta) as clave:
valor, tipo = winreg.QueryValueEx(clave, "Tema")
print(valor, tipo)
Cerrar handles es importante en procesos largos, tests repetidos y herramientas que inspeccionan muchas claves. Evita mantener claves abiertas durante toda la vida de la aplicación sin una razón clara.
Crea una clave
CreateKey() o CreateKeyEx() crea una clave y devuelve un handle abierto. La variante Ex permite indicar máscara de acceso y opciones.
import winreg
ruta = r"Software\EmpresaEjemplo\AplicacionEjemplo"
with winreg.CreateKeyEx(
winreg.HKEY_CURRENT_USER,
ruta,
access=winreg.KEY_WRITE,
) as clave:
winreg.SetValueEx(clave, "Tema", 0, winreg.REG_SZ, "oscuro")
Usa un namespace claro basado en la organización y el producto. Nunca escribas dentro de la rama de otra aplicación solo porque ya existe.
Lee valores con QueryValueEx
QueryValueEx() devuelve el valor y su tipo del Registro. Conserva el tipo cuando forme parte del contrato de configuración.
with winreg.OpenKey(winreg.HKEY_CURRENT_USER, ruta) as clave:
try:
tema, tipo = winreg.QueryValueEx(clave, "Tema")
except FileNotFoundError:
tema = "claro"
Distingue “el valor no existe” de “acceso denegado”. Devolver un valor predeterminado para cualquier excepción puede ocultar una política o una instalación defectuosa.
Tipos de datos del Registro
Los tipos frecuentes incluyen REG_SZ para texto, REG_EXPAND_SZ para texto con referencias al entorno, REG_DWORD para enteros de 32 bits, REG_QWORD para enteros de 64 bits, REG_BINARY para bytes y REG_MULTI_SZ para listas de strings.
No almacenes un número como texto si otras herramientas esperan un DWORD. Un tipo incorrecto complica interoperabilidad, validación, upgrades e inspección administrativa.
Expande REG_EXPAND_SZ
Un valor REG_EXPAND_SZ puede contener referencias como %TEMP%. QueryValueEx() devuelve el texto guardado; llama a ExpandEnvironmentStrings() cuando necesites el resultado expandido.
texto, tipo = winreg.QueryValueEx(clave, "Ruta")
if tipo == winreg.REG_EXPAND_SZ:
texto = winreg.ExpandEnvironmentStrings(texto)
La expansión no convierte la ruta en confiable. Normaliza y valida antes de abrir un archivo, cargar una biblioteca o ejecutar un programa.
Escribe valores
SetValueEx() recibe la clave, nombre del valor, campo reservado, tipo y dato. El campo reservado debe ser cero.
with winreg.CreateKeyEx(
winreg.HKEY_CURRENT_USER,
ruta,
access=winreg.KEY_SET_VALUE,
) as clave:
winreg.SetValueEx(clave, "Intentos", 0, winreg.REG_DWORD, 3)
Solicita KEY_SET_VALUE en lugar de acceso de escritura amplio cuando solo necesites modificar valores.
Valor predeterminado sin nombre
El valor predeterminado de una clave utiliza un nombre vacío. Algunos formatos de Windows dependen de él, pero la configuración propia suele ser más clara con nombres explícitos.
winreg.SetValueEx(clave, "", 0, winreg.REG_SZ, "valor predeterminado")
Documenta el valor sin nombre cuando forme parte de un formato público o de instalación.
Enumera valores
EnumValue() acepta índices desde cero y lanza OSError cuando termina la enumeración.
indice = 0
while True:
try:
nombre, valor, tipo = winreg.EnumValue(clave, indice)
except OSError:
break
print(nombre, valor, tipo)
indice += 1
Si otro proceso puede modificar la clave al mismo tiempo, la enumeración no representa un snapshot estable. Pueden aparecer o desaparecer entradas durante el loop.
Enumera subclaves
EnumKey() sigue el mismo patrón indexado. QueryInfoKey() devuelve cantidad de subclaves, cantidad de valores y hora de última modificación.
subclaves, valores, modificado = winreg.QueryInfoKey(clave)
for indice in range(subclaves):
print(winreg.EnumKey(clave, indice))
La cantidad puede cambiar entre la consulta y la lectura. Gestiona fallos sin asumir que cada diferencia indica corrupción.
Elimina valores y claves
DeleteValue() elimina un valor con nombre. DeleteKey() elimina una clave vacía; normalmente las subclaves deben borrarse antes o mediante una operación de árbol apropiada.
with winreg.OpenKey(
winreg.HKEY_CURRENT_USER,
ruta,
access=winreg.KEY_SET_VALUE,
) as clave:
winreg.DeleteValue(clave, "Intentos")
Antes de una eliminación recursiva, verifica que la raíz coincida exactamente con el namespace de la aplicación. Un error al construir la ruta puede borrar ajustes de otro producto.
Máscaras de acceso
Máscaras como KEY_READ, KEY_WRITE, KEY_QUERY_VALUE, KEY_SET_VALUE, KEY_ENUMERATE_SUB_KEYS y KEY_CREATE_SUB_KEY describen las capacidades solicitadas.
Pide únicamente lo necesario. KEY_ALL_ACCESS aumenta los errores de permisos y amplía el impacto de un bug.
Vistas de 32 y 64 bits
En Windows de 64 bits, ciertas zonas del Registro tienen vistas separadas. Las flags KEY_WOW64_32KEY y KEY_WOW64_64KEY seleccionan una vista explícita.
acceso = winreg.KEY_READ | winreg.KEY_WOW64_64KEY
with winreg.OpenKey(winreg.HKEY_LOCAL_MACHINE, ruta, 0, acceso) as clave:
print(winreg.QueryValueEx(clave, "Version"))
No supongas que la arquitectura del proceso selecciona los datos deseados. Instaladores e integraciones con aplicaciones nativas deben documentar qué vista utilizan.
Registro remoto
ConnectRegistry() puede conectarse a otro equipo Windows cuando servicio, firewall, credenciales y políticas lo permiten.
Evita usar el Registro remoto como protocolo general de administración. Prefiere herramientas autenticadas con autorización explícita, auditoría, reintentos y propiedad clara.
Guardar, cargar y restaurar hives
Funciones como SaveKey(), LoadKey() y RestoreKey() son operaciones administrativas que pueden requerir privilegios. Trabajan con archivos de hive y pueden tener un efecto amplio.
No restaures datos de producción sin backup verificado, ventana de mantenimiento, rollback probado y conocimiento de los procesos que pueden mantener valores en caché.
Auditoría
Varias operaciones de winreg emiten eventos de auditoría de Python. Los entornos controlados pueden usar audit hooks para observar apertura, creación, conexión y modificación de claves.
La auditoría complementa los permisos de Windows; no los sustituye. Usa las ACL del sistema operativo como frontera principal.
Configuración no significa secreto
El Registro puede guardar configuración, pero no protege automáticamente secretos. Usuarios y procesos con permiso pueden leer los valores. Contraseñas, tokens y claves privadas deberían utilizar Windows Credential Manager u otra protección criptográfica vinculada al usuario.
Documentos grandes y datos relacionales complejos también suelen encajar mejor en archivos o bases de datos.
Consistencia y migraciones
Una serie de escrituras puede quedar aplicada parcialmente si el proceso falla. Escribe primero los valores auxiliares, valídalos y actualiza al final un marcador de versión o finalización. Diseña migraciones idempotentes que puedan repetirse con seguridad.
Mantén código capaz de reconocer versiones antiguas y conserva información suficiente para revertir un upgrade fallido.
Errores y excepciones
Una clave o valor ausente suele generar FileNotFoundError. Los problemas de acceso pueden producir PermissionError u otro OSError. Captura la condición específica que la aplicación pueda gestionar.
try:
with winreg.OpenKey(winreg.HKEY_LOCAL_MACHINE, ruta) as clave:
valor, _ = winreg.QueryValueEx(clave, "Config")
except FileNotFoundError:
valor = None
except PermissionError as error:
raise RuntimeError("sin acceso a la configuración de la máquina") from error
Threads y escritores concurrentes
Handles separados pueden usarse en distintas threads, pero el modelo de configuración todavía necesita coordinación. Varias escrituras no se convierten en una transacción atómica solo porque cada llamada termine correctamente.
Centraliza migraciones y usa un lock de aplicación cuando dos procesos propios puedan actualizar el mismo árbol.
Prueba con privilegios realistas
Prueba como usuario estándar y como administrador cuando sea necesario. Cubre vistas de 32 y 64 bits, claves ausentes, permisos denegados, políticas corporativas, instalación, upgrade, reparación y desinstalación.
No ejecutes pruebas destructivas contra ramas reales. Usa una ruta exclusiva bajo HKEY_CURRENT_USER\Software y elimínala durante el cleanup.
Errores comunes
Los fallos frecuentes incluyen escribir en HKEY_LOCAL_MACHINE sin necesidad global, solicitar acceso total, olvidar las vistas WOW64, guardar secretos como texto, filtrar handles, interpretar cualquier error como “no existe”, borrar el árbol equivocado y cambiar inesperadamente el tipo de un valor.
Conclusión
winreg da a Python acceso detallado al Registro de Windows. Modela la configuración de forma deliberada, elige el hive correcto, usa context managers, solicita acceso mínimo y gestiona explícitamente las vistas de 32 y 64 bits.
Consulta la documentación oficial de winreg. Para otras operaciones específicas de Windows, lee msvcrt en Python.
