{"id":10100,"library":"pykd","title":"pykd: Python WinDbg Extension","description":"pykd is a Python extension for WinDbg, providing scripting capabilities for Windows kernel and user-mode debugging. It allows users to automate debugging tasks, analyze crash dumps, and extend WinDbg functionality with Python. The current version is 0.3.4.15. Its release cadence is irregular, typically tied to WinDbg updates and community contributions.","status":"active","version":"0.3.4.15","language":"en","source_language":"en","source_url":"https://github.com/pykd/pykd","tags":["debugger","windbg","windows","reverse-engineering","kernel-debugging","usermode-debugging","automation"],"install":[{"cmd":"pip install pykd","lang":"bash","label":"Install pykd"}],"dependencies":[],"imports":[{"note":"The pykd module is available for import after the pykd extension is loaded within a WinDbg debugger session.","symbol":"pykd","correct":"import pykd"}],"quickstart":{"code":"import pykd\n\ntry:\n    # Get the current process ID if a user-mode debuggee is attached\n    pid = pykd.getCurrentProcessId()\n    print(f\"Current Process ID: {pid}\")\n\n    # Read a register value (e.g., EAX for 32-bit, RAX for 64-bit)\n    # This assumes a debuggee is running and registers are available.\n    register_name = \"eax\" if pykd.is32Bit() else \"rax\"\n    reg_value = pykd.reg(register_name)\n    print(f\"{register_name.upper()} register value: 0x{reg_value:x}\")\n\n    # Execute a simple WinDbg command and print its output\n    output = pykd.dbgCommand(\"!peb\")\n    print(\"\\nOutput of '!peb':\")\n    print(output[:200] + \"...\" if len(output) > 200 else output) # Truncate for display\nexcept pykd.BaseException as e:\n    print(f\"pykd error encountered: {e}\")\n    print(\"This script must be run within a WinDbg session with a debuggee attached.\")\n","lang":"python","description":"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."},"warnings":[{"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.","message":"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.","severity":"gotcha","affected_versions":"all"},{"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`.","message":"The architecture (32-bit or 64-bit) of the Python interpreter used by pykd must precisely match the architecture of the WinDbg installation.","severity":"breaking","affected_versions":"all"},{"fix":"Wrap pykd calls in `try...except pykd.BaseException as e:` blocks for robust error handling specific to pykd's error reporting.","message":"Errors originating from WinDbg or pykd operations are raised as `pykd.BaseException` or its subclasses, not standard Python exceptions like `RuntimeError` or `ValueError`.","severity":"gotcha","affected_versions":"all"},{"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.","message":"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.","severity":"gotcha","affected_versions":"all"}],"env_vars":null,"last_verified":"2026-04-17T00:00:00.000Z","next_check":"2026-07-16T00:00:00.000Z","problems":[{"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.","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.","error":"ImportError: DLL load failed while importing pykd: %1 is not a valid Win32 application."},{"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.","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.","error":"ModuleNotFoundError: No module named 'pykd'"},{"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`.","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.","error":"NameError: name 'pykd' is not defined"},{"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.","cause":"A `pykd` function that requires an active debuggee (process, kernel, or dump) was called when no debuggee was attached or loaded in WinDbg.","error":"pykd.BaseException: No debuggee available"}]}