pwndbg: version floors, optional commands, and an experimental LLDB port
Exploit Development and Reverse Engineering with GDB & LLDB Made Easy
At a glance
- What is it?
- pwndbg is a Python module loaded into GDB or run as an LLDB REPL. Its two front ends carry different version floors, its command set depends on which optional dependencies you install, and its container recipe asks for ptrace with seccomp unconfined.
- Who is it for?
- pwndbg fits reverse engineers and exploit developers who already work in GDB or LLDB on Linux ELF, kernel, or embedded targets and want an importable package instead of a large single-file script. Treat the LLDB front end as experimental, since it needs Python 3.12 and LLDB 19 and is still the only route to Mach-O binaries on macOS.
- Can I use it commercially?
- Yes. MIT is a permissive licence: you can use, modify and sell software built on it, as long as you keep its copyright and licence notices.
- Is it still maintained?
- Yes. The repository last received commits 4 days ago.
- What is it written in?
- Mainly Python, according to GitHub's language statistics.
Answers come from the project's GitHub data, last synced on November 15, 2026, and from our analysis. They are not legal advice.
Star history
- pwndbg/pwndbg11,210 ★ · +290
| Repository | 2026-09-22 | 2026-11-15 |
|---|---|---|
| pwndbg/pwndbg | 10.9k | 11.2k |
290 Stars in the last 54 days, measured from the daily GitHub snapshot. Compare with other projects
Editorial analysis
A Python package beside gdbinit.py, not a single script
pwndbg is not a dotfile you append to your GDB startup. The repository root holds gdbinit.py next to a pwndbg/ package directory, alongside pwndbginit/, themes/, docs/, nix/, tests/, profiling/, and scripts/. The README frames this as a Python module which can be loaded into GDB or run as a REPL interface for LLDB, and the layout follows from that: the code lives in importable files rather than one long script.
The size contrast is the stated reason for that design. Comparing pwndbg with gdbinit, PEDA, GEF, and bata24/GEF, the README quotes their single-file weights as 103KB, 195KB, 423KB, and 5.24MB respectively, and says pwndbg aims to replace that class of tool with a faster, cleaner implementation.
For a reader choosing between the two styles, the difference shows up the moment something misbehaves. With a package you can open the module that owns a command and read it. With a 5.24MB file you start searching. The README does not name commands itself: it points at a features page and a cheatsheet PDF.
The LLDB front end sits on newer Python and a newer LLDB
The two front ends are not symmetrical, and the compatibility table says so directly:
| pwndbg-gdb | - Python 3.10+ <br/>- GDB 12.1+ | Battle-tested on Ubuntu 22.04/24.04 |
| pwndbg-lldb | - Python 3.12+ <br/>- LLDB 19+ | Experimental/early-stage support |
| qemu-user | QEMU 8.1+ | vFile API is needed for vmmap |
| qemu-system | QEMU 6.2+ | Supported version since Ubuntu 22.04 |pwndbg-gdb takes Python 3.10+ and GDB 12.1+ and is described as battle-tested on Ubuntu 22.04/24.04. pwndbg-lldb takes Python 3.12+ and LLDB 19+ and is labelled Experimental/early-stage support. The README states that the LLDB implementation in pwndbg is still in early-stage and may contain bugs or limitations, and routes known issues to GitHub Issues under the LLDB Port label.
That gap decides your platform before you choose a feature. The use case table lists debugging Mach-O binaries on macOS as LLDB only, with no GDB entry, so a macOS binary puts you on the front end the compatibility table calls experimental, on a Python baseline two minor versions newer than the GDB one (3.12 versus 3.10). Read the LLDB Port issues for your LLDB version before building a workflow on it, and expect gaps nobody has filed yet. Linux ELF, Linux kernel debugging under qemu-system, and embedded ARM Cortex-M or RISC-V targets are listed for both front ends, so the split is narrower than the version gap suggests.
vmmap needs a QEMU floor, and on qemu-user the vFile API
Both QEMU modes carry a minimum, and one of them carries an API requirement on top. The compatibility table puts qemu-user at QEMU 8.1+ and notes that the vFile API is needed for vmmap, while qemu-system sits at QEMU 6.2+ as a supported version since Ubuntu 22.04.
So a memory map of a qemu-user guest is not a given. Run an older QEMU, or a build without the vFile API, and vmmap has no data behind it. The use case table narrows that mode further: Linux user-space emulation with qemu-user is listed for GDB only, with no LLDB entry, unlike Linux kernel debugging under qemu-system, which lists both. The dependency that backs the qemu-system side is pinned to a commit rather than a release range:
# Optional? only for qemu-system vmmap
"pt @ git+https://github.com/martinradev/gdb-pt-dump@50227bda0b6332e94027f811a15879588de6d5cb",Two consequences follow. An offline or locked-down install has to carry that VCS dependency or resolve it ahead of time, because a version range would be far easier to vendor. And an LLDB user who wants qemu-user memory maps gets nothing at all, with the table stating the limit rather than leaving you to find it.
The installation section is a link, and the install path lives in the Dockerfile
The Installation section of the repository page is one line: See installation instructions, pointing at https://pwndbg.re/stable/setup. No command, no package name, no distro matrix appears there. The same holds for the command set, which the README defers to a features page and a cheatsheet PDF.
The container build is one place in the repository where the install path is visible, and it is a Python project install driven by uv and a shell script:
COPY ./uv.lock /pwndbg/
COPY ./pyproject.toml /pwndbg/
# pyproject.toml requires these files, pip install would fail
RUN touch README.md && mkdir pwndbg && touch pwndbg/empty.py
COPY ./setup.sh /pwndbg/
RUN DEBIAN_FRONTEND=noninteractive ./setup.shsetup.sh is copied in early, along with scripts/common.sh because the script needs it, and the image touches a placeholder README.md and pwndbg/empty.py first, since pip install fails without them. The image points its environment at a virtualenv path of /venv through PWNDBG_VENV_PATH and UV_PROJECT_ENVIRONMENT, then prepends ${PWNDBG_VENV_PATH}/bin to PATH.
For a reader that means the offline story is thin. Installation lives on a web page, the repository does not list supported package names or a distro matrix, and any instruction you relied on months ago may no longer match the current setup guide. Plan to re-read that page before a rebuild rather than trusting a saved snippet.
Optional dependencies decide which commands exist at all
pyproject.toml separates what pwndbg always needs from what only some commands need, and the comments say which is which. The always-present set includes capstone6pwndbg==8.0.0, unicorn>=2.1.4,<3, pwntools>=4.14.1,<5, pyelftools>=0.33,<1, psutil>=7.0.0,<8, and uv>=0.12.0, which the file notes is installed into the venv. Then the optional block maps a dependency to the command that needs it:
# Optional? only for qemu-system vmmap
"pt @ git+https://github.com/martinradev/gdb-pt-dump@50227bda0b6332e94027f811a15879588de6d5cb",
# Optional? 'ziglang' must be optional, as it is not available on every platform.
# It is only used for the 'cymbol' command and some `asm` functionality.
"ziglang==0.14.1 ; (platform_system == 'Linux' and platform_machine != 'loongarch64') or platform_system != 'Linux'",
# Used for symbol syncing (e.g. klookup --apply and decompiler integration)
"niche-elf==0.3.7",Elsewhere the same file marks ipython as optional and only for the ipi command, ropgadget==7.6 as optional and only for the ropgadget command, requests for the ai commands, and rich for pretty print traceback. A decompiler-plugin dependency is marked optional, and its comment says to bump pwndbg/commands/decompiler_integration together with it, so the decompiler plugins have to move in step with the code loading them.
The hard edge is ziglang. Its environment marker excludes Linux on loongarch64, and the comment says it is not available on every platform and is used only for the cymbol command and some asm functionality. On that platform cymbol is absent and part of asm loses its backend. Each optional entry maps to a named command rather than to the debugger itself, so a minimal install loses features one command at a time..
Every compose service inherits ptrace and an unconfined seccomp profile
The compose file defines one anchor that all services merge in, and it is worth reading before you run anything on a shared machine:
base: &base-spec
build: .
security_opt:
- seccomp:unconfined
cap_add:
- SYS_PTRACESYS_PTRACE is the capability a debugger needs to control another process, and seccomp:unconfined removes the syscall filter, so every service asks for more privilege than an ordinary image would.
The service list covers ubuntu24.04, ubuntu22.04, and debian12 from the Dockerfile, archlinux from Dockerfile.arch, and fedora41, fedora42, and fedora43 from Dockerfile.dnf. Each names both a published ghcr image with pull_policy: always and a build section, so a local compose build compiles the repository Dockerfiles rather than handing you the tagged image. The Dockerfile comment gives the intended one-liner for the prebuilt path and the update path for the same service:
# docker compose run --rm -v $(pwd):/pwndbg ubuntu24.04
#
# Update your prebuilt image:
# docker compose pull ubuntu24.04The main and ubuntu24.04-mount services bind mount the repository to /pwndbg, which is what makes your source visible to the debugger and also what lets the container write to your working tree. The image also sets LANG to en_US.utf8 and TZ to America/New_York, defaults worth changing before you read any timestamped output. On hardened or shared runners, the capability and the unconfined filter are the reason to check policy before using this recipe.
Date-shaped releases, a dev branch, and docs split across two channels
Versions here are dates. pyproject.toml declares version 2026.10.28, and the three recent releases follow the same pattern: 2026.10.28, 2026.10.22, and 2026.09.15. The default branch is dev, and the last push was on 2026-10-12.
One detail is easy to trip over. The documentation channels are split: the features link points at pwndbg.re/stable/features/ while the cheatsheet link points at pwndbg.re/dev/CHEATSHEET.pdf.
That split has a concrete failure mode. A cheatsheet printed from the dev channel can list commands that the release you have installed does not have. Read the cheatsheet as a description of the dev branch, not of your installed version, and treat the release date in pyproject.toml as the number that tells you what you actually have.
Editorial conclusion
pwndbg fits reverse engineers and exploit developers who already work in GDB or LLDB on Linux ELF, kernel, or embedded targets and want an importable package instead of a large single-file script. Treat the LLDB front end as experimental, since it needs Python 3.12 and LLDB 19 and is still the only route to Mach-O binaries on macOS. Before committing, check the LLDB Port issues against your LLDB version, confirm QEMU 8.1 or newer with the vFile API if you rely on qemu-user vmmap, and decide which optional dependencies you want, because cymbol, the decompiler plugins, and the ai commands are absent without them.
Frequently asked questions
What commands are available in Pwndbg?
The repository page does not enumerate them; it links the features page at pwndbg.re/stable/features/ and a cheatsheet PDF. pyproject.toml names several commands tied to optional dependencies: ipi, ropgadget, ai, cymbol, vmmap, and klookup.
how to install pwndbg
The Installation section only points to https://pwndbg.re/stable/setup and contains no command. The container build reveals the underlying path: copy uv.lock and pyproject.toml into the image, then run DEBIAN_FRONTEND=noninteractive ./setup.sh.
how to install pwndbg on ubuntu
The compose file ships ubuntu22.04 and ubuntu24.04 services, both built from the Dockerfile with an image build arg of ubuntu:22.04 or ubuntu:24.04, and the Dockerfile comment gives the run command as docker compose run --rm -v $(pwd):/pwndbg ubuntu24.04.
pwndbg vs peda
The README lists PEDA among past projects that are hard to extend and packaged as a large single file, quoted at 195KB, and says pwndbg aims to replace that class of tool with a faster, cleaner implementation.
pwndbg vscode
The README does not mention a VS Code extension. The project is loaded into GDB or run as an LLDB REPL.
what is pwndbg
A GDB and LLDB plug-in written in Python for low-level software developers, hardware hackers, reverse engineers, and exploit developers. The name is pronounced /paʊnˈdiˌbʌg/ and the project is MIT licensed.
Official sources
Add this badge to your README
If you maintain this project, the badge below links readers to this analysis and shows its maintenance status from the daily GitHub snapshot. Paste the markdown into your README; add ?metric=license or ?metric=stars to the image URL for a different field.
[](https://hysenlabs.com/projects/pwndbg-pwndbg)Star history chart for your README
[](https://hysenlabs.com/projects/pwndbg-pwndbg)Was this useful?