lib-registry 3.1.2

a more pythonic way to access the windows registry as winreg

lib_registry

A more pythonic way to access the Windows registry as winreg.

Wraps Python's winreg module with a high-level Registry class providing connection caching, automatic type detection, recursive key operations, and a context manager. On non-Windows platforms, fake_winreg provides a simulated registry so tests and code run everywhere.

Features

• Pythonic Registry class with context manager support
• Automatic registry value type detection (str, int, bytes, list)
• Connection and key handle caching for performance
• Recursive key creation (parents=True) and deletion (delete_subkeys=True)
• Remote computer registry access
• SID enumeration and username resolution
• Save/load registry subtrees to/from files
• WOW64 32/64-bit registry view support
• Registry reflection control
• Cross-platform via fake_winreg on Linux/macOS
• CLI entry point with rich-click styling

Install

pip install lib_registry

Or with uv (recommended):

uv pip install lib_registry

For all installation methods (pipx, uvx, poetry, etc.), see INSTALL.md.

Python 3.10+ Baseline

• Targets Python 3.10 and newer
• Runtime dependencies: rich-click for CLI output, rtoml for TOML parsing, fake_winreg on non-Windows platforms
• CI covers CPython 3.10 through 3.14

Usage

As a library

import lib_registry

# Create a registry accessor
registry = lib_registry.Registry()

# Check if a key exists
registry.key_exist('HKLM\\SOFTWARE\\Microsoft\\Windows NT\\CurrentVersion')

# Read a value
build = registry.get_value(
    'HKLM\\SOFTWARE\\Microsoft\\Windows NT\\CurrentVersion',
    'CurrentBuild',
)

# Create a key and write values
registry.create_key('HKCU\\Software\\MyApp', parents=True)
registry.set_value('HKCU\\Software\\MyApp', 'Setting', 'value')
registry.set_value('HKCU\\Software\\MyApp', 'Count', 42)

# Iterate subkeys and values
for subkey in registry.subkeys('HKEY_USERS'):
    print(subkey)

for name, data, reg_type in registry.values('HKLM\\SOFTWARE\\Microsoft\\Windows NT\\CurrentVersion'):
    print(f'{name} = {data}')

# Save and load registry subtrees
registry.save_key('HKCU\\Software\\MyApp', '/tmp/myapp_backup.json')
registry.load_key(lib_registry.winreg.HKEY_CURRENT_USER, 'Software\\MyAppCopy', '/tmp/myapp_backup.json')

# Clean up
registry.delete_key('HKCU\\Software\\MyApp', delete_subkeys=True)

# SID / user operations (no try/except needed — .DEFAULT handled gracefully)
for sid in registry.sids():
    print(f'{sid} -> {registry.username_from_sid(sid)}')

# Reverse lookup: find SID by username
sid = registry.sid_from_username('alice')

# Use as context manager (handles closed automatically)
with lib_registry.Registry('HKLM') as reg:
    info = reg.key_info('HKLM\\SOFTWARE')

Path separators

Both backslashes and forward slashes are accepted in registry paths:

# These are equivalent:
registry.key_exist('HKLM\\SOFTWARE\\Microsoft')
registry.key_exist('HKLM/SOFTWARE/Microsoft')

CLI Reference

All commands accept registry paths with either backslashes (\) or forward slashes (/). Hive names are case-insensitive (HKLM, hklm, HKEY_LOCAL_MACHINE all work). Run any command with -h for built-in help.

Global options

lib_registry [OPTIONS] COMMAND [ARGS]...

Option	Default	Description
--version		Print version and exit
--traceback/--no-traceback	on	Show full Python traceback on errors
-q, --quiet	off	Suppress non-error output
--json	off	Emit JSON output (for scripting)
--computer HOST		Connect to remote computer registry
-h, --help		Show help and exit

Also available as python -m lib_registry.

---

info -- package metadata

lib_registry info

Print resolved package metadata (name, version, homepage, author).

---

get -- read a value

lib_registry get [OPTIONS] KEY VALUE_NAME

Argument/Option	Required	Description
KEY	yes	Registry key path (e.g. HKLM/SOFTWARE/...)
VALUE_NAME	yes	Name of the value to read (omit for default)
--type	no	Also display the REG_* type alongside the data
--default	no	Read the unnamed default value

Examples:

lib_registry get "HKLM/SOFTWARE/Microsoft/Windows NT/CurrentVersion" CurrentBuild
# Output: 19045

lib_registry get --type "HKLM/SOFTWARE/Microsoft/Windows NT/CurrentVersion" CurrentBuild
# Output: REG_SZ: 19045

---

set -- write a value

lib_registry set [OPTIONS] KEY VALUE_NAME DATA

Argument/Option	Required	Description
KEY	yes	Registry key path
VALUE_NAME	yes	Name of the value to write
DATA	yes	Value data as string (converted based on --type)
--type TYPE	no	Registry type. One of: REG_SZ, REG_DWORD, REG_QWORD, REG_BINARY, REG_MULTI_SZ, REG_EXPAND_SZ, REG_NONE, etc. Without --type, data is always stored as REG_SZ (string). Use --type REG_DWORD explicitly for integers.
--default	no	Write the unnamed default value (VALUE_NAME ignored)

Type conversion rules:

--type	DATA is parsed as	Example
(omitted)	always string (REG_SZ)	42 -> REG_SZ, hello -> REG_SZ
REG_SZ	string	"hello world"
REG_DWORD	integer (32-bit)	42
REG_QWORD	integer (64-bit)	9999999999
REG_BINARY	UTF-8 encoded bytes	"raw data"
REG_MULTI_SZ	\0-delimited string list	"line1\0line2\0line3"
REG_NONE	None (empty)	(DATA ignored)

Examples:

lib_registry set HKCU/Software/MyApp Setting "hello world"
lib_registry set HKCU/Software/MyApp Count 42 --type REG_DWORD
lib_registry set HKCU/Software/MyApp Paths "C:\bin\0D:\tools" --type REG_MULTI_SZ

Silent on success (exit code 0).

---

delete-value -- remove a value

lib_registry delete-value KEY VALUE_NAME

Argument/Option	Required	Description
KEY	yes	Registry key path
VALUE_NAME	yes	Name of the value to delete
--force	no	Suppress error if value does not exist

Silent on success.

---

list -- list subkeys and values

lib_registry list [OPTIONS] KEY

Argument/Option	Required	Description
KEY	yes	Registry key path
--keys	no	Show subkeys only
--values	no	Show values only
--recursive, -r	no	Recurse into subkeys

Without flags, shows both subkeys and values. Output format:

[KEY] SubkeyName
[REG_SZ] ValueName = data
[REG_DWORD] Count = 42

Examples:

lib_registry list HKEY_USERS
lib_registry list --keys HKEY_USERS
lib_registry list --values "HKLM/SOFTWARE/Microsoft/Windows NT/CurrentVersion"

---

exists -- check key existence

lib_registry exists KEY

Argument	Required	Description
KEY	yes	Registry key path

Produces no output. Exit code 0 if the key exists, 1 if it does not. Designed for shell scripting:

if lib_registry exists HKCU/Software/MyApp; then
    echo "Key exists"
fi

---

create-key -- create a registry key

lib_registry create-key [OPTIONS] KEY

Argument/Option	Required	Description
KEY	yes	Registry key path to create
--parents	no	Create intermediate parent keys if missing

Silent on success. Without --parents, fails if the parent key does not exist.

Examples:

lib_registry create-key HKCU/Software/MyApp
lib_registry create-key HKCU/Software/MyApp/Deep/Nested/Key --parents

---

delete-key -- delete a registry key

lib_registry delete-key [OPTIONS] KEY

Argument/Option	Required	Description
KEY	yes	Registry key path to delete
--recursive	no	Also delete all subkeys and their values recursively
--force	no	Suppress error if key does not exist

Silent on success. Without --recursive, fails if the key has subkeys.

Examples:

lib_registry delete-key HKCU/Software/MyApp
lib_registry delete-key HKCU/Software/MyApp --recursive

---

export -- save a key subtree to file

lib_registry export KEY FILE

Argument	Required	Description
KEY	yes	Registry key path to export
FILE	yes	Output file path (JSON format)

Saves the key and all its subkeys/values to a JSON file. Use import to restore.

lib_registry export HKCU/Software/MyApp backup.json

---

import -- load a key subtree from file

lib_registry import KEY SUB_KEY FILE

Argument	Required	Description
KEY	yes	Hive or parent key (e.g. HKCU)
SUB_KEY	yes	Subkey path under KEY where data will be loaded
FILE	yes	Input file path (JSON, as produced by export)

lib_registry import HKCU Software/MyAppCopy backup.json

---

search -- find values by pattern

lib_registry search [OPTIONS] KEY

Argument/Option	Required	Description
KEY	yes	Registry key path to search under (recursive)
--name PATTERN	no	Glob pattern to match value names (e.g. "Install*")
--data PATTERN	no	Glob pattern to match value data (e.g. "*Microsoft*")

Recursively walks all subkeys under KEY and prints matching values. At least one of --name or --data should be specified.

Output format:

HKLM\SOFTWARE\Microsoft\Windows NT\CurrentVersion  [REG_SZ] CurrentBuild = 19045

Examples:

lib_registry search "HKLM/SOFTWARE/Microsoft/Windows NT/CurrentVersion" --name "Current*"
lib_registry search HKLM/SOFTWARE --data "*Python*"

---

users -- list Windows users from registry

lib_registry users

No arguments. Enumerates SIDs from the ProfileList and resolves usernames. Output is a formatted table:

      Registry Users
+-----------------------+----------+
| SID                   | Username |
+-----------------------+----------+
| S-1-5-21-...-1000     | alice    |
| S-1-5-18              | SYSTEM   |
+-----------------------+----------+

---

sid -- resolve a SID to a username

lib_registry sid SID

Argument	Required	Description
SID	yes	Security Identifier to resolve

Prints the username for the given SID. Handles .DEFAULT gracefully.

lib_registry sid S-1-5-21-1234567890-1234567890-1234567890-1001
# Output: alice

lib_registry sid .DEFAULT
# Output: Default

lib_registry --json sid .DEFAULT
# Output: {"sid": ".DEFAULT", "username": "Default"}

---

whoami -- resolve a username to its SID

lib_registry whoami USERNAME

Argument	Required	Description
USERNAME	yes	Windows username to look up

Reverse lookup: finds the SID for the given username (case-insensitive).

lib_registry whoami alice
# Output: S-1-5-21-1234567890-1234567890-1234567890-1001

lib_registry --json whoami alice
# Output: {"username": "alice", "sid": "S-1-5-21-..."}

---

tree -- visual key hierarchy

lib_registry tree [OPTIONS] KEY

Argument/Option	Required	Description
KEY	yes	Registry key path
--depth N	no	Maximum depth to display (default: 3)

Displays a Rich tree view of the key hierarchy. With --json, outputs a nested dict.

lib_registry tree HKEY_USERS --depth 2
lib_registry --json tree HKLM/SOFTWARE --depth 1

---

copy -- copy a key

lib_registry copy [OPTIONS] SRC_KEY DST_KEY

Argument/Option	Required	Description
SRC_KEY	yes	Source key path
DST_KEY	yes	Destination key path (created if needed)
--recursive	no	Also copy all subkeys recursively

Copies all values from SRC_KEY to DST_KEY. With --recursive, copies the entire subtree.

lib_registry copy HKCU/Software/MyApp HKCU/Software/MyAppBackup --recursive

---

rename -- rename a value

lib_registry rename KEY OLD_NAME NEW_NAME

Argument	Required	Description
KEY	yes	Registry key path
OLD_NAME	yes	Current value name
NEW_NAME	yes	New value name

Renames a registry value by copying its data and type to the new name, then deleting the old name. Atomic within a single key.

lib_registry rename HKCU/Software/MyApp OldSetting NewSetting

---

diff -- compare two keys

lib_registry diff KEY_A KEY_B

Argument	Required	Description
KEY_A	yes	First key path to compare
KEY_B	yes	Second key path to compare

Recursively compares values and subkeys between two registry key subtrees. Shows values only in A, only in B, and values that differ.

lib_registry diff HKCU/Software/MyApp HKCU/Software/MyAppBackup
lib_registry --json diff HKCU/Software/V1 HKCU/Software/V2

Output format:

  - HKCU\Software\MyApp  (only in KEY_A)
  + HKCU\Software\MyAppBackup  (only in KEY_B)
  ~ HKCU\Software\MyApp / Setting
    A: old_value
    B: new_value

---

Access constants

All winreg KEY_* access constants are re-exported for convenience:

from lib_registry import KEY_READ, KEY_WRITE, KEY_ALL_ACCESS, KEY_WOW64_64KEY

API Reference

Constructor

Registry(key=None, computer_name=None)

Create a registry accessor. Optionally connect to a hive immediately. Supports context manager (with Registry('HKLM') as reg:).

# Local registry
reg = Registry()

# Connect to hive at creation
reg = Registry('HKLM')

# Remote computer
reg = Registry('HKLM', computer_name='server01')

# Context manager — handles closed automatically
with Registry('HKCU') as reg:
    build = reg.get_value('HKCU\\Software\\Microsoft', 'Version')

---

Key Operations

create_key(key, sub_key='', exist_ok=True, parents=False) -> HKEYType

Create a registry key and return a handle.

reg.create_key('HKCU/Software/MyApp')                    # existing key OK
reg.create_key('HKCU/Software/MyApp', exist_ok=False)     # raises if exists
reg.create_key('HKCU/Software/A/B/C', parents=True)       # create intermediates

create_key_ex(key, sub_key='', access=KEY_WRITE) -> HKEYType

Create with explicit access mask (for WOW64 scenarios).

from lib_registry import KEY_WOW64_64KEY
reg.create_key_ex('HKCU/Software/MyApp', access=KEY_WOW64_64KEY)

delete_key(key, sub_key='', missing_ok=False, delete_subkeys=False)

Delete a key. Fails if key has children unless delete_subkeys=True.

reg.delete_key('HKCU/Software/MyApp')                         # leaf key only
reg.delete_key('HKCU/Software/MyApp', delete_subkeys=True)    # recursive
reg.delete_key('HKCU/Software/Missing', missing_ok=True)      # no error if absent

delete_key_ex(key, sub_key='', access=KEY_WOW64_64KEY)

Delete with WOW64 view control.

key_exist(key, sub_key='') -> bool

if reg.key_exist('HKLM/SOFTWARE/Python'):
    print("Python is installed")

key_info(key, sub_key='') -> tuple[int, int, int]

Returns (number_of_subkeys, number_of_values, last_modified_win_timestamp).

subkeys, values, ts = reg.key_info('HKLM/SOFTWARE')

number_of_subkeys(key, sub_key='') -> int

number_of_values(key, sub_key='') -> int

has_subkeys(key, sub_key='') -> bool

last_access_timestamp(key, sub_key='') -> float

Unix epoch timestamp (seconds since 1970-01-01).

last_access_timestamp_windows(key, sub_key='') -> int

Windows timestamp (100ns intervals since 1601-01-01).

---

Subkey & Value Iteration

subkeys(key, sub_key='') -> Iterator[str]

for name in reg.subkeys('HKEY_USERS'):
    print(name)

values(key, sub_key='') -> Iterator[tuple[str, RegData, int]]

Yields (value_name, value_data, value_type_int) tuples.

for name, data, reg_type in reg.values('HKLM/SOFTWARE/Microsoft/Windows NT/CurrentVersion'):
    print(f'{name} ({reg_type}) = {data}')

---

Value Operations

get_value(key, value_name) -> RegData

Read a value's data. Pass None or '' as value_name for the unnamed default value.

build = reg.get_value('HKLM/SOFTWARE/Microsoft/Windows NT/CurrentVersion', 'CurrentBuild')

get_value_ex(key, value_name) -> tuple[RegData, int]

Read data and registry type.

data, reg_type = reg.get_value_ex('HKLM/SOFTWARE/Microsoft/Windows NT/CurrentVersion', 'CurrentBuild')
# reg_type is e.g. winreg.REG_SZ (1)

set_value(key, value_name, value, value_type=None)

Write a value. Type is auto-detected from the Python type if value_type is None.

Python type	Auto-detected REG_TYPE
str	REG_SZ
int	REG_DWORD
bytes	REG_BINARY
list[str]	REG_MULTI_SZ
None	REG_NONE

reg.set_value('HKCU/Software/MyApp', 'Name', 'Alice')              # REG_SZ
reg.set_value('HKCU/Software/MyApp', 'Count', 42)                  # REG_DWORD
reg.set_value('HKCU/Software/MyApp', 'Data', b'\x00\x01')          # REG_BINARY
reg.set_value('HKCU/Software/MyApp', 'Paths', ['C:\\', 'D:\\'])     # REG_MULTI_SZ
reg.set_value('HKCU/Software/MyApp', 'Env', '%PATH%', winreg.REG_EXPAND_SZ)  # explicit type

delete_value(key, value_name)

reg.delete_value('HKCU/Software/MyApp', 'Name')

---

File Operations

save_key(key, file_name, sub_key='')

Save a key subtree to a file (JSON with fake_winreg, binary hive on Windows).

reg.save_key('HKCU/Software/MyApp', '/tmp/backup.json')

load_key(key, sub_key, file_name)

Load a subtree from file into a registry location.

reg.load_key(winreg.HKEY_CURRENT_USER, 'Software/MyAppCopy', '/tmp/backup.json')

flush_key(key, sub_key='')

Force pending writes to disk (rarely needed).

---

Handle Management

close_key(key, sub_key='')

Explicitly close a cached key handle.

close_all()

Close all cached key handles and hive connections. Called automatically by __exit__.

---

SID / User Operations

sids() -> Iterator[str]

Iterate SIDs from the ProfileList.

for sid in reg.sids():
    print(sid)   # e.g. 'S-1-5-21-...-1001'

username_from_sid(sid) -> str

Resolve a SID to a username. Returns "Default" for .DEFAULT.

reg.username_from_sid('S-1-5-21-...-1001')   # 'alice'
reg.username_from_sid('.DEFAULT')              # 'Default'

sid_from_username(username) -> str

Reverse lookup (case-insensitive).

reg.sid_from_username('alice')    # 'S-1-5-21-...-1001'
reg.sid_from_username('Default')  # '.DEFAULT'

---

Reflection Control (64-bit Windows)

disable_reflection_key(key, sub_key='')

enable_reflection_key(key, sub_key='')

query_reflection_key(key, sub_key='') -> bool

Returns True if reflection is disabled.

---

Utility

expand_environment_strings(string) -> str (static method)

Expand %VAR% references.

Registry.expand_environment_strings('%USERPROFILE%\\Documents')
# '/home/alice/Documents' (or 'C:\Users\alice\Documents' on Windows)

---

Helper Functions (module-level)

from lib_registry import resolve_key, get_key_as_string, normalize_separators

resolve_key('HKLM/SOFTWARE/Microsoft')           # (HKEY_LOCAL_MACHINE, 'SOFTWARE\\Microsoft')
get_key_as_string(winreg.HKEY_LOCAL_MACHINE)      # 'HKEY_LOCAL_MACHINE'
normalize_separators('HKLM/SOFTWARE/test')        # 'HKLM\\SOFTWARE\\test'

---

Type Alias

RegData = None | bytes | int | str | list[str]

All registry values are one of these types.

---

Exception Hierarchy

RegistryError
  RegistryConnectionError
  RegistryKeyError
    RegistryKeyNotFoundError
    RegistryKeyExistsError
    RegistryKeyCreateError
    RegistryKeyDeleteError
  RegistryValueError
    RegistryValueNotFoundError
    RegistryValueDeleteError
    RegistryValueWriteError
  RegistryHKeyError
  RegistryNetworkConnectionError
  RegistryHandleInvalidError

from lib_registry import Registry, RegistryKeyNotFoundError

reg = Registry()
try:
    reg.get_value('HKCU/Software/NoSuchApp', 'key')
except RegistryKeyNotFoundError:
    print("Key not found")

---

Access Constants

Re-exported from winreg for convenience:

from lib_registry import (
    KEY_READ, KEY_WRITE, KEY_ALL_ACCESS,
    KEY_WOW64_32KEY, KEY_WOW64_64KEY,
    KEY_QUERY_VALUE, KEY_SET_VALUE,
    KEY_CREATE_SUB_KEY, KEY_ENUMERATE_SUB_KEYS,
    KEY_NOTIFY, KEY_CREATE_LINK, KEY_EXECUTE,
)

Further Documentation

• Install Guide
• Development Handbook
• Contributor Guide
• Changelog
• Module Reference
• License