pykd: Python WinDbg Extension

Common errors

• ImportError: DLL load failed while importing pykd: %1 is not a valid Win32 application.

  cause The architecture (32-bit or 64-bit) of the pykd.pyd library does not match the architecture of the Python interpreter attempting to load it, or the WinDbg installation.
  fix Ensure your Python interpreter (python.exe) and WinDbg are both 32-bit or both 64-bit. Reinstall pykd using `pip install pykd` in the correct Python environment if necessary.

• ModuleNotFoundError: No module named 'pykd'

  cause The `pykd` package was not installed, or it was installed in a different Python environment than the one WinDbg is configured to use for its scripting engine.
  fix Identify the Python environment used by WinDbg (check WinDbg settings or `!pykd.info` if `pykd` partially loads) and run `pip install pykd` within that specific environment.

• NameError: name 'pykd' is not defined

  cause This error occurs when a Python script tries to use `pykd` functions, but the `pykd` extension was not properly loaded in WinDbg, or `import pykd` was omitted in the Python script itself.
  fix Before running Python scripts, ensure the pykd extension is loaded in WinDbg (e.g., `!load <path_to_pykd.pyd>`) and ensure your script starts with `import pykd`.

• pykd.BaseException: No debuggee available

  cause A `pykd` function that requires an active debuggee (process, kernel, or dump) was called when no debuggee was attached or loaded in WinDbg.
  fix Attach to a process, start a debuggee, or load a crash dump in WinDbg before executing the `pykd` functions that interact with the debuggee. Wrap such calls in `try...except pykd.BaseException` for robust handling.

Warnings

• gotcha pykd is not a standalone Python library; it must be run within a WinDbg debugger session. Attempting to run pykd code outside WinDbg will result in errors.
  Fix: Ensure WinDbg is running and the pykd extension (e.g., pykd.pyd) is loaded via `!load <path_to_pykd.pyd>` or `!pykd.py` before executing pykd Python scripts.
• breaking The architecture (32-bit or 64-bit) of the Python interpreter used by pykd must precisely match the architecture of the WinDbg installation.
  Fix: Use a 32-bit Python interpreter with 32-bit WinDbg, and a 64-bit Python interpreter with 64-bit WinDbg. Mismatch causes `ImportError: DLL load failed`.
• gotcha Errors originating from WinDbg or pykd operations are raised as `pykd.BaseException` or its subclasses, not standard Python exceptions like `RuntimeError` or `ValueError`.
  Fix: Wrap pykd calls in `try...except pykd.BaseException as e:` blocks for robust error handling specific to pykd's error reporting.
• gotcha Using `pip install pykd` installs the package for a specific Python environment. If WinDbg is configured to use a different Python installation, pykd won't be found.
  Fix: Identify the Python environment WinDbg is configured to use (e.g., via `!pykd.info` or WinDbg settings) and run `pip install pykd` within that specific environment.

Install

• pip install pykd Install pykd

Imports

• pykd

  import pykd

  The pykd module is available for import after the pykd extension is loaded within a WinDbg debugger session.

Quickstart

This quickstart demonstrates basic interaction with the WinDbg debugger through pykd, such as retrieving process information, reading register values, and executing debugger commands. This code is intended to be executed within a WinDbg session after loading the pykd extension.

import pykd

try:
    # Get the current process ID if a user-mode debuggee is attached
    pid = pykd.getCurrentProcessId()
    print(f"Current Process ID: {pid}")

    # Read a register value (e.g., EAX for 32-bit, RAX for 64-bit)
    # This assumes a debuggee is running and registers are available.
    register_name = "eax" if pykd.is32Bit() else "rax"
    reg_value = pykd.reg(register_name)
    print(f"{register_name.upper()} register value: 0x{reg_value:x}")

    # Execute a simple WinDbg command and print its output
    output = pykd.dbgCommand("!peb")
    print("\nOutput of '!peb':")
    print(output[:200] + "..." if len(output) > 200 else output) # Truncate for display
except pykd.BaseException as e:
    print(f"pykd error encountered: {e}")
    print("This script must be run within a WinDbg session with a debuggee attached.")