Skip to content

Home

Jump to bottom
ivellioscolin edited this page Feb 11, 2025 · 1 revision

About

Welcome to the pykd (maintenance fork) wiki!

The pykd project started in 2010, aiming to enhance WinDbg scripting with Python in addition to WinDbg's built-in script engine. Pykd was initially hosted on codeplex (dead link) (MSFT discontinued CodePlex in 2017, and shut down the archive in 2021) and later moved to githomelab.ru (author's own machine, also a dead link). There are still some webpage archives available.

The last commit to pykd/kdlib on githomelab.ru was in 2020, and githomelab.ru is no longer accessible. According to PyPI, the last update of the pykd Python module stopped at 0.3.4.15, supporting up to Python 3.9. However, there are still many pykd users, including myself, who rely on pykd to automate our WinDbg tasks. Luckily, I kept a local backup of the pykd repositories, so I mirrored it to pykd on GitHub in early 2023, and recently (early 2025), I continued the maintenance mainly for my own convenience.

User Guide

The original document (in Russian) can be found here. The ChatGPT-translated version can be found here. There are no plans to update those docs in the repository, so accuracy cannot be guaranteed.

A simplified guide:

Install

  1. Download the latest pykd.dll (pykd WinDbg extension, aka pykd bootstrapper) from here and place it into the WinDbg extension directory (winext under WinDbg, or the directory pointed to by _NT_DEBUGGER_EXTENSION_PATH). Compile from source if you don't trust the binary. Check if the pykd_ext can be loaded in WinDbg:
kd> .load pykd.dll
kd> .chain

Extension DLL chain:
...
    pykd: image 2.0.0.25, API 0.0.0, built Wed Jan  6 18:35:42 2021
        [path: C:\_Dev\dbgext\pykd.dll]
...
  1. Install the pykd package. If not using PyPI, the latest wheel release can be found here. Assume the PATH environment variable already includes Python.
# To use a wheel from PyPI
> python.exe -m pip install --user pykd

# To install a local wheel
> py.exe -3.13 -m pip install --user <pykd*.whl>

# Or specify Python directly instead of using the launcher.
> python.exe -m pip install --user <pykd*.whl>

If installed successfully, pykd should appear in the pip list:

Package    Version
pykd       0.3.4.15

And the Python REPL should be able to import pykd without errors:

> py.exe -3.13
Python 3.13.1 (tags/v3.13.1:0671451, Dec  3 2024, 19:06:28) [MSC v.1942 64 bit (AMD64)] on win32
Type "help", "copyright", "credits" or "license" for more information.
>>> import pykd
>>>

REPL

In WinDbg, enter Python REPL mode and execute WinDbg commands:

kd> !py -3.11
Input> import pykd
Input> print(pykd.dbgCommand("r"))
>>> print(pykd.dbgCommand("r"))
rax=ffffe40fc44c4a90 rbx=ffffce03b256c4c0 rcx=ffffe40fc44c4a90
rdx=0000000000000500 rsi=ffffce03b8f1fce0 rdi=ffffce03bc6a7000
rip=fffff8050e4a6fcb rsp=fffff40d621d0680 rbp=ffffe40fc44c4a90
 r8=0000000000000001  r9=0000000000000fff r10=fffff8050962bd90
r11=00000000000001b4 r12=0000000000000023 r13=0000000000000001
r14=0000000000000000 r15=0000000000000a28
iopl=0         nv up ei ng nz na po nc
cs=0010  ss=0018  ds=002b  es=002b  fs=0053  gs=002b             efl=00040286
watchdog+0x6fcb:
fffff805`0e4a6fcb 488b4628        mov     rax,qword ptr [rsi+28h] ds:002b:ffffce03`b8f1fd08=????????????????

>>>

Scripting

In WinDbg, execute a script with arguments directly:

kd> !py -g script.py 10 "string"

More Usage

kd> !pykd.help

Build Guide

The main pykd sub-projects have now been submoduled into the parent pykd project. The most common use case is to build pykd_ext and pykd, which can be done via the main solution file only. kdlibcpp and pykd_ext also have their own solution files, which can be built separately.

Prepare Source

All source code will be ready after the submodules are updated recursively. It takes approximately 7.2 GB in total.

> git clone https://github.com/ivellioscolin/pykd
> cd pykd
> git checkout <branch or tag>
> git submodule update --init --recursive

Build via Visual Studio

Open pykd.sln with Visual Studio, choose release_x.y|$(Platform). Right-click pykd_ext_2.0 to build the pykd_ext, pykd.dll will be saved in "$(SolutionDir)pykd_ext\Out". Right-click the pykd project to build pykd, pykd.pyd and the packaged wheel will be saved in "$(SolutionDir)Out".

Build via MSBuild

Alternatively, you can build via the command line without opening Visual Studio. The same $(OutDir) as above applies.

> vcvarsall.bat x86_amd64
> msbuild.exe <path_to_pykd.sln> /t:pykd /property:Configuration=Release_3.10 /property:Platform=x64
> msbuild.exe <path_to_pykd.sln> /t:pykd_ext_2_0 /property:Configuration=Release_3.10 /property:Platform=x64

Issue Report

Feel free to start a discussion or bug report here.

Clone this wiki locally