Python winreg Windows Registry — Core Concepts

What the Windows Registry is

The Windows Registry is a hierarchical database that stores configuration settings for the operating system, installed software, user preferences, and hardware. Nearly every Windows behavior — from file associations to startup programs to network settings — is controlled by registry entries.

Registry structure

The registry is organized like a file system:

• Hives (top-level roots):

  • HKEY_LOCAL_MACHINE (HKLM) — system-wide settings
  • HKEY_CURRENT_USER (HKCU) — current user’s settings
  • HKEY_CLASSES_ROOT (HKCR) — file type associations
  • HKEY_USERS — all user profiles
  • HKEY_CURRENT_CONFIG — current hardware profile

• Keys — like folders, organized in a tree

• Values — named data entries within a key (each has a name, type, and data)

The winreg module

winreg is a standard library module available only on Windows. It provides low-level access to the registry.

Reading a value

import winreg

# Find where Python is installed
key = winreg.OpenKey(winreg.HKEY_LOCAL_MACHINE,
                     r"SOFTWARE\Python\PythonCore\3.12\InstallPath")
install_path, reg_type = winreg.QueryValueEx(key, "")
winreg.CloseKey(key)
print(f"Python installed at: {install_path}")

Using context managers

with winreg.OpenKey(winreg.HKEY_CURRENT_USER,
                    r"SOFTWARE\Microsoft\Windows\CurrentVersion\Explorer") as key:
    shell_state, _ = winreg.QueryValueEx(key, "ShellState")

The with statement ensures the key is closed even if an error occurs.

Enumerating subkeys

def list_subkeys(hive, path):
    with winreg.OpenKey(hive, path) as key:
        i = 0
        while True:
            try:
                subkey_name = winreg.EnumKey(key, i)
                print(subkey_name)
                i += 1
            except OSError:
                break

list_subkeys(winreg.HKEY_LOCAL_MACHINE, r"SOFTWARE\Microsoft")

Enumerating values

def list_values(hive, path):
    with winreg.OpenKey(hive, path) as key:
        i = 0
        while True:
            try:
                name, data, vtype = winreg.EnumValue(key, i)
                print(f"{name} = {data} (type: {vtype})")
                i += 1
            except OSError:
                break

Value types

Type constant	Meaning	Python type
REG_SZ	String	str
REG_EXPAND_SZ	String with environment variables	str
REG_DWORD	32-bit integer	int
REG_QWORD	64-bit integer	int
REG_BINARY	Raw binary data	bytes
REG_MULTI_SZ	List of strings	list[str]

Writing to the registry

# Add a program to startup
key = winreg.OpenKey(winreg.HKEY_CURRENT_USER,
                     r"SOFTWARE\Microsoft\Windows\CurrentVersion\Run",
                     0, winreg.KEY_SET_VALUE)
winreg.SetValueEx(key, "MyApp", 0, winreg.REG_SZ,
                  r"C:\Program Files\MyApp\myapp.exe")
winreg.CloseKey(key)

Writing to HKEY_LOCAL_MACHINE requires administrator privileges. Writing to HKEY_CURRENT_USER works for the current user without elevation.

Creating and deleting keys

# Create a new key
key = winreg.CreateKey(winreg.HKEY_CURRENT_USER, r"SOFTWARE\MyApp\Settings")
winreg.SetValueEx(key, "Theme", 0, winreg.REG_SZ, "dark")
winreg.CloseKey(key)

# Delete a value
with winreg.OpenKey(winreg.HKEY_CURRENT_USER, r"SOFTWARE\MyApp\Settings",
                    0, winreg.KEY_SET_VALUE) as key:
    winreg.DeleteValue(key, "Theme")

# Delete a key (must have no subkeys)
winreg.DeleteKey(winreg.HKEY_CURRENT_USER, r"SOFTWARE\MyApp\Settings")

32-bit vs 64-bit registry views

On 64-bit Windows, there are separate registry views for 32-bit and 64-bit applications. Control which you access with flags:

# Access 64-bit view explicitly
key = winreg.OpenKey(winreg.HKEY_LOCAL_MACHINE, r"SOFTWARE\SomeApp",
                     0, winreg.KEY_READ | winreg.KEY_WOW64_64KEY)

# Access 32-bit view explicitly
key = winreg.OpenKey(winreg.HKEY_LOCAL_MACHINE, r"SOFTWARE\SomeApp",
                     0, winreg.KEY_READ | winreg.KEY_WOW64_32KEY)

Common misconception

“The registry is just for system settings.”

Many applications store their own configuration in the registry — license keys, user preferences, recent file lists, window positions. It is also used for COM object registration, file type associations, and context menu entries. Understanding the registry is key to understanding how Windows software integrates with the OS.

One thing to remember: winreg gives Python full read/write access to the Windows Registry — master OpenKey, QueryValueEx, and SetValueEx for the most common tasks, and always close keys (or use with statements) to avoid resource leaks.