The winreg module exposes the Windows Registry API to Python. A program can open keys, read and write values, create configuration trees, enumerate subkeys, remove data, and inspect metadata. Windows and many desktop applications use the Registry for preferences, file associations, policies, installation details, and machine-specific settings.
Although the API is convenient, the Registry should not be treated as an unrestricted global dictionary. It has hives, access-control lists, separate 32-bit and 64-bit views, native data types, virtualization rules, and protected areas. A mistaken change can break an application or affect the operating system. Request the smallest access mask possible and back up administrative data before changing it.
Availability
winreg is available only on Windows. Keep the import inside a platform-specific layer.
import sys
if sys.platform == "win32":
import winreg
else:
winreg = None
A cross-platform application should offer a configuration file, environment variables, a database, or another backend when the Registry is unavailable.
Main hives
Common roots include HKEY_CURRENT_USER, HKEY_LOCAL_MACHINE, HKEY_CLASSES_ROOT, HKEY_USERS, and HKEY_CURRENT_CONFIG. Per-user preferences generally belong under HKEY_CURRENT_USER. Machine-wide settings often live under HKEY_LOCAL_MACHINE and may require elevation.
Choose a hive according to ownership and lifecycle, not convenience. Decide whether the data belongs to one user, all users, an installer, a managed policy, or the operating system.
Use keys as context managers
Registry key objects support with, which guarantees that the native handle is closed even when an exception occurs.
import winreg
path = r"Software\ExampleCompany\ExampleApp"
with winreg.OpenKey(winreg.HKEY_CURRENT_USER, path) as key:
value, value_type = winreg.QueryValueEx(key, "Theme")
print(value, value_type)
Closing handles matters in long-running processes, repeated tests, and tools that inspect many keys. Avoid keeping keys open for the entire application lifetime without a reason.
Create a key
CreateKey() or CreateKeyEx() creates a key and returns an open handle. The Ex variant allows an explicit access mask and options.
import winreg
path = r"Software\ExampleCompany\ExampleApp"
with winreg.CreateKeyEx(
winreg.HKEY_CURRENT_USER,
path,
access=winreg.KEY_WRITE,
) as key:
winreg.SetValueEx(key, "Theme", 0, winreg.REG_SZ, "dark")
Use a clear namespace based on the organization and product. Never write inside another application’s branch merely because it already exists.
Read values with QueryValueEx
QueryValueEx() returns both the value and its Registry type. Preserve the type when it is part of the configuration contract.
with winreg.OpenKey(winreg.HKEY_CURRENT_USER, path) as key:
try:
theme, value_type = winreg.QueryValueEx(key, "Theme")
except FileNotFoundError:
theme = "light"
Distinguish “value does not exist” from “access denied.” Returning a default for every exception can conceal a policy or installation problem.
Registry data types
Frequently used types include REG_SZ for text, REG_EXPAND_SZ for text containing environment references, REG_DWORD for 32-bit integers, REG_QWORD for 64-bit integers, REG_BINARY for bytes, and REG_MULTI_SZ for a list of strings.
Do not store a number as text if another tool expects a DWORD. The wrong type makes interoperability, validation, upgrades, and administrative inspection harder.
Expand REG_EXPAND_SZ values
A REG_EXPAND_SZ value may contain references such as %TEMP%. QueryValueEx() returns the stored string; call ExpandEnvironmentStrings() when the expanded result is required.
text, value_type = winreg.QueryValueEx(key, "Path")
if value_type == winreg.REG_EXPAND_SZ:
text = winreg.ExpandEnvironmentStrings(text)
Expansion does not make the path trustworthy. Normalize and validate the result before opening a file, loading a library, or launching a program.
Write values
SetValueEx() receives a key, value name, reserved field, Registry type, and data. The reserved field must be zero.
with winreg.CreateKeyEx(
winreg.HKEY_CURRENT_USER,
path,
access=winreg.KEY_SET_VALUE,
) as key:
winreg.SetValueEx(key, "Retries", 0, winreg.REG_DWORD, 3)
Request KEY_SET_VALUE instead of broad write access when setting values is the only required operation.
The default unnamed value
The default value of a key uses an empty name. Some Windows formats depend on it, but application-owned configuration is usually clearer with explicit names.
winreg.SetValueEx(key, "", 0, winreg.REG_SZ, "default value")
Document the unnamed value when it is part of a public or installation format.
Enumerate values
EnumValue() accepts zero-based indexes and raises OSError when enumeration is complete.
index = 0
while True:
try:
name, value, value_type = winreg.EnumValue(key, index)
except OSError:
break
print(name, value, value_type)
index += 1
If another process can modify the key concurrently, the enumeration is not a stable snapshot. Entries may be inserted or removed while the loop runs.
Enumerate subkeys
EnumKey() follows the same indexed pattern. QueryInfoKey() returns the number of subkeys, number of values, and last modification time.
subkey_count, value_count, modified = winreg.QueryInfoKey(key)
for index in range(subkey_count):
print(winreg.EnumKey(key, index))
The count may change between the query and the read. Handle failures rather than assuming that every mismatch indicates corruption.
Delete values and keys
DeleteValue() removes a named value. DeleteKey() removes an empty key; child keys normally must be removed first or with an appropriate tree operation.
with winreg.OpenKey(
winreg.HKEY_CURRENT_USER,
path,
access=winreg.KEY_SET_VALUE,
) as key:
winreg.DeleteValue(key, "Retries")
Before recursive deletion, verify that the root path is exactly the intended application namespace. A path-building bug can erase another product’s settings.
Access masks
Masks such as KEY_READ, KEY_WRITE, KEY_QUERY_VALUE, KEY_SET_VALUE, KEY_ENUMERATE_SUB_KEYS, and KEY_CREATE_SUB_KEY describe requested capabilities.
Ask only for what the operation needs. KEY_ALL_ACCESS increases permission failures and expands the impact of programming mistakes.
32-bit and 64-bit views
On 64-bit Windows, selected Registry areas have separate views. Flags KEY_WOW64_32KEY and KEY_WOW64_64KEY select a view explicitly.
access = winreg.KEY_READ | winreg.KEY_WOW64_64KEY
with winreg.OpenKey(winreg.HKEY_LOCAL_MACHINE, path, 0, access) as key:
print(winreg.QueryValueEx(key, "Version"))
Do not assume that the process architecture selects the desired data. Installers and integrations with native applications should document which view they use.
Remote Registry
ConnectRegistry() can connect to another Windows machine when the service, firewall, credentials, and policies permit it.
Avoid using remote Registry access as a general management protocol. Prefer authenticated administration tools with explicit authorization, audit trails, retries, and clear ownership.
Save, load, and restore hives
Functions such as SaveKey(), LoadKey(), and RestoreKey() are administrative operations that may require privileges. They work with hive files and can have broad effects.
Never restore production Registry data without a verified backup, a maintenance window, a tested rollback procedure, and an understanding of open processes that may cache values.
Auditing
Several winreg operations emit Python auditing events. Controlled environments can use audit hooks to observe key opening, creation, connection, and modification.
Auditing supplements Windows access controls; it does not replace them. Use operating-system permissions as the primary boundary.
Configuration is not secret storage
The Registry can hold configuration, but it does not automatically protect secrets. Users and processes with permission can read values. Passwords, tokens, and private keys should use an appropriate credential facility such as Windows Credential Manager or user-bound cryptographic protection.
Large documents and complex relational data are also usually better stored in files or a database.
Consistency and migrations
A series of writes can be left partially applied if the process crashes. Write supporting values first, validate them, and update a version or completion marker last. Make migrations idempotent so they can run again safely.
Keep code capable of recognizing old versions and preserve enough information to roll back a failed upgrade.
Errors and exceptions
A missing key or value commonly raises FileNotFoundError. Access problems may raise PermissionError or another OSError. Catch the specific condition that the application can handle.
try:
with winreg.OpenKey(winreg.HKEY_LOCAL_MACHINE, path) as key:
value, _ = winreg.QueryValueEx(key, "Config")
except FileNotFoundError:
value = None
except PermissionError as error:
raise RuntimeError("cannot access machine configuration") from error
Threads and concurrent writers
Separate handles may be used by different threads, but the configuration model still needs coordination. Several writes do not become an atomic transaction merely because each call succeeds.
Centralize migrations and use an application-level lock when two of your own processes may update the same tree.
Test with realistic privileges
Test as a standard user and as an administrator when required. Cover 32-bit and 64-bit views, missing keys, denied permissions, corporate policies, install, upgrade, repair, and uninstall flows.
Do not run destructive tests against real product branches. Use a unique path under HKEY_CURRENT_USER\Software and remove it during cleanup.
Common mistakes
Frequent mistakes include writing to HKEY_LOCAL_MACHINE without a machine-wide requirement, requesting full access, forgetting WOW64 views, storing secrets as plain text, leaking handles, treating every error as “not found,” deleting the wrong tree, and changing a value’s Registry type unexpectedly.
Conclusion
winreg gives Python detailed access to the Windows Registry. Model the configuration deliberately, choose the correct hive, use context managers, request minimal access, and handle 32-bit and 64-bit views explicitly.
Consult the official winreg documentation. For other Windows-specific runtime operations, see Python msvcrt.
