ntoseye
Drive the ntoseye Windows kernel debugger from Python, and run it from the command line.
See docs/scripting/sdk.md for address-space-bound
views and run control. The
package also installs the ntoseye command (the REPL, ntoseye mcp, dap,
and gdbserver), which runs Python custom commands from
~/.ntoseye/commands/: uv tool install ntoseye or pipx install ntoseye.
Install
pip install ntoseye
Or build from source into a virtualenv with maturin:
cd python
python3 -m venv .venv
source .venv/bin/activate
pip install maturin
maturin develop --release
Or build a wheel and install it:
cd python
maturin build --release --out dist
pip install dist/ntoseye-*.whl
Quick start
import ntoseye
with ntoseye.attach() as dbg: # defaults to the kd backend
print(dbg.inspect.version())
for proc in dbg.processes:
print(proc.pid, proc.name)
For read-only inspection of a paused VM, select backend="memory". Processes
are handles keyed by PID (dbg.processes[pid]); memory and modules for a
specific process are available through proc.memory and proc.modules.
Type stubs
ntoseye/_ntoseye.pyi is generated from the extension by PyO3's
introspection: signatures come from the Rust types and docstrings from the
doc comments. After changing the Rust surface, regenerate it and commit the
result (CI fails when the checked-in stub differs from a fresh one):
maturin develop --release --generate-stubs
Tests
pip install pytest mypy
pytest tests # target-free surface tests
mypy --strict -p ntoseye # the stub and package type-check
NTOSEYE_TEST_BACKEND=kd NTOSEYE_TEST_CONNECT=/tmp/ntoseye-kd.sock pytest tests
The last line also runs tests/test_live.py against a guest: it breaks in,
steps, sets breakpoints on hot kernel functions, and resumes the guest.
Add NTOSEYE_TEST_MEMORY_SOURCE=kd to read guest memory over KD instead of
from the VM process: no root needed for UTM on macOS, and required for a
remote target.
Releasing portable wheels
Release wheels are built by .github/workflows/release.yml with PyO3/maturin-action on native GitHub runners:
- Linux x86-64 and ARM64 build on
ubuntu-22.04andubuntu-24.04-arminside thequay.io/pypa/manylinux_2_28_*images, producingmanylinux_2_28wheels. - Apple Silicon uses the native ARM64
macos-14runner.
Each wheel then passes twine check and the target-free tests (tests/test_surface.py) in a clean virtual environment before upload.
To reproduce a Linux release wheel locally (from the repository root, Docker required):
docker run --rm -e CARGO_TARGET_DIR=/tmp/target -e HOST_IDS="$(id -u):$(id -g)" \
-v "$PWD":/io -w /io/python quay.io/pypa/manylinux_2_28_$(uname -m) bash -c '
dnf install -y clang &&
curl -sSf https://sh.rustup.rs | sh -s -- -y --profile minimal &&
source ~/.cargo/env &&
/opt/python/cp312-cp312/bin/pip install maturin &&
/opt/python/cp312-cp312/bin/maturin build --release --out dist --compatibility manylinux_2_28 &&
chown -R "$HOST_IDS" dist'
1 maintainer
Release files for ntoseye 0.42.0
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Built distributions (wheels)
| File | Interpreter | ABI | Platform | Reset |
|---|---|---|---|---|
| ntoseye-0.42.0-cp39-abi3-manylinux_2_28_x86_64.whl | CPython 3.9 | abi3 | Linux glibc 2.28+ x86-64 | Details |
| ntoseye-0.42.0-cp39-abi3-manylinux_2_28_aarch64.whl | CPython 3.9 | abi3 | Linux glibc 2.28+ ARM64 | Details |
| ntoseye-0.42.0-cp39-abi3-macosx_11_0_arm64.whl | CPython 3.9 | abi3 | macOS 11.0+ ARM64 | Details |
Total release size: 30.3 MB
Release files / ntoseye-0.42.0-cp39-abi3-manylinux_2_28_x86_64.whl
| Download URL | ntoseye-0.42.0-cp39-abi3-manylinux_2_28_x86_64.whl |
|---|---|
| Size | 10.4 MB |
| Tags | CPython 3.9 Linux glibc 2.28+ x86-64 abi3 |
|
SHA-256 checksum How to use checksums |
7afffcd620cab637f882c68be3eccd8cc5fad93bf81b4392aa50565e2108394b
|
|
BLAKE2b-256 checksum How to use checksums |
caf04a8664e8d1b6273385ddfb38b4ea74d9cc99bd5cc475d617c22acc5ddc66
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Sep 27, 2026.
Transparency logRelease files / ntoseye-0.42.0-cp39-abi3-manylinux_2_28_aarch64.whl
| Download URL | ntoseye-0.42.0-cp39-abi3-manylinux_2_28_aarch64.whl |
|---|---|
| Size | 10.5 MB |
| Tags | CPython 3.9 Linux glibc 2.28+ ARM64 abi3 |
|
SHA-256 checksum How to use checksums |
87b28900bfd4311709989c418b752fa525b228beab96208b599f5d2a515616f3
|
|
BLAKE2b-256 checksum How to use checksums |
3b5b4aeef45e0dec463e197a3f040d83e69edea1f0fa7fca2ffc1dd721e16ec1
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Sep 27, 2026.
Transparency logRelease files / ntoseye-0.42.0-cp39-abi3-macosx_11_0_arm64.whl
| Download URL | ntoseye-0.42.0-cp39-abi3-macosx_11_0_arm64.whl |
|---|---|
| Size | 9.4 MB |
| Tags | CPython 3.9 abi3 macOS 11.0+ ARM64 |
|
SHA-256 checksum How to use checksums |
351888d16422022651e8c6928b1dc21a042923935bd0783952e5db246b029239
|
|
BLAKE2b-256 checksum How to use checksums |
26d42fe96dc90d2200bc26f310e09ce4dc60f5a2d60f1f9f9ec3734c56d2488c
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Sep 27, 2026.
Transparency log
