Skip to content
Get packs

Guide · Open source

How to use pwndbg: install, run and inspect memory in GDB

Updated · written with AI from the project's own documentation and checked against our catalogue data

pwndbg is a free, MIT-licensed Python plug-in that loads into GDB and adds features the stock debugger lacks, such as a hexdump command and clearer views of registers and memory. This guide is for reverse engineers, exploit developers and CTF players who already use a command-line debugger. After reading it you will know what pwndbg needs, how to get the project, where to find its docs and cheatsheet, and what to expect from it.

pwndbgpwndbg/pwndbg · ★ 11.1k · MIT

Quick start

  1. 1Check your Python and debugger versions. For GDB, confirm Python 3.10 or newer and GDB 12.1 or newer, as listed in the README's compatibility table.
  2. 2Clone the repository. Run git clone https://github.com/pwndbg/pwndbg to get the source.
  3. 3Read the setup instructions. Open the installation instructions linked from the README at pwndbg.re/stable/setup and follow them for your system.
  4. 4Pick your debugger. Use GDB for most Linux ELF and qemu-user work. Use LLDB only if you accept that it is early-stage.
  5. 5Open a target and inspect memory. Load a binary in the debugger with pwndbg active, then use hexdump and the register and memory views instead of raw x commands.
  6. 6Keep the cheatsheet nearby. Print or open the CHEATSHEET PDF linked from the README for command reference.

What pwndbg needs before you install it

The project's compatibility table lists the requirements for the GDB side of pwndbg: Python 3.10 or newer and GDB 12.1 or newer. The README says the GDB setup is battle-tested on Ubuntu 22.04 and 24.04.

The LLDB side (pwndbg-lldb) lists Python 3.12+ and LLDB 19+, and the README labels it experimental.

  • GDB path: Python 3.10+, GDB 12.1+
  • LLDB path: Python 3.12+, LLDB 19+ (experimental)
  • Both debuggers: the README says pwndbg ensures a consistent experience across them

Get pwndbg onto your machine

The README's install section does not give full steps. It points to the project's installation instructions on the homepage, and lists a clone command for the repository. Follow the setup page on the official site for the complete procedure.

Clone the repository with the command below, then read the setup instructions in the project docs before going further.

  • Installation instructions live at the project's setup page on pwndbg.re
  • The README lists the GitHub repository as the source for the project
git clone https://github.com/pwndbg/pwndbg

Choose between GDB and LLDB for your target

The README's table maps targets to debuggers. For Linux binaries and ELF files, both GDB and LLDB are listed. Mach-O binaries on macOS are listed for LLDB only. Linux user-space emulation with qemu-user is listed for GDB only.

For embedded work on ARM Cortex-M or RISC-V/32, the README lists both debuggers. The README notes that the LLDB implementation is early-stage and may contain bugs, so GDB is the safer default for most work.

  • Linux ELF binaries: GDB or LLDB
  • Mach-O binaries on macOS: LLDB
  • qemu-user emulation: GDB
  • Linux kernel debugging with qemu-system: GDB or LLDB
  • Embedded ARM Cortex-M or RISC-V/32: GDB or LLDB

Use the features that replace raw GDB commands

The README's main complaint is that vanilla GDB makes it hard to read memory and registers. Its example is typing x/30gx $rsp, which it says often gives minimal information. pwndbg adds commands and views that the README says fill these gaps, including a hexdump command.

For a full list of commands and their options, use the Features page and the CHEATSHEET linked from the README. The README invites you to print the cheatsheet.

  • hexdump: a readable memory dump, named in the README as a gap in stock debuggers
  • Clearer register and memory views than the raw x command
  • Full feature list: pwndbg.re/stable/features/
  • Printable cheatsheet: pwndbg.re/dev/CHEATSHEET.pdf

Know where pwndbg fits next to GEF and PEDA

The README describes GEF, PEDA and gdbinit as useful projects that are hard to extend and are packaged as large single files. It says pwndbg aims to replace them with a more modular, faster and more robust implementation. This is the project's own claim, so test it on your workload.

If you already rely on GEF or PEDA, the README's comparison is the place to start. Pwndbg is a Python module with a suite of utilities, so it is organized differently from a single-file script.

  • Comparable projects named in the README: GEF, PEDA, gdbinit
  • pwndbg is described as modular; the README contrasts it with single-file packaging
  • Documentation and questions: project docs and the Discord server linked from the README

Get help and report LLDB problems

The README links three places for help: the project documentation, a Discord server, and the GitHub issue tracker. Known LLDB issues are tracked in GitHub Issues under the LLDB Port label.

Contributions are welcome. The README points to a Contributing Guide on the dev documentation site.

  • Docs: pwndbg.re/stable/
  • Discord: linked from the README
  • LLDB known issues: GitHub Issues filtered by the LLDB Port label
  • Contributing guide: pwndbg.re/dev/contributing/

What people use it for

  • Inspecting a stack layout in an ELF binary with a readable hexdump instead of raw x/30gx output
  • Working through a CTF binary exploitation challenge under GDB
  • Debugging an ARM Cortex-M or RISC-V/32 target with GDB, as listed in the README's support table
  • Checking register and memory state while developing an exploit against a Linux program

Frequently asked questions

Is pwndbg free?

Yes. The repository is licensed under MIT, as shown in the project header. The README also mentions a sponsorship page for people who want to support development.

What are the requirements for pwndbg?

For the GDB setup, the README lists Python 3.10 or newer and GDB 12.1 or newer. The LLDB setup lists Python 3.12 or newer and LLDB 19 or newer, and is marked experimental.

How do I install pwndbg?

The README gives the command git clone https://github.com/pwndbg/pwndbg and directs you to the installation instructions at pwndbg.re/stable/setup for the full steps.

Does pwndbg work on Windows?

The README says the project focuses on GDB and LLDB and does not cover WinDbg. It does not claim native Windows debugging support, so check the project docs before relying on it there.

Is pwndbg better than GEF or PEDA?

The README says pwndbg aims to replace GEF, PEDA and gdbinit with a faster, cleaner and more robust implementation, and it describes those tools as hard to extend. That is the project's own claim, so compare them on your own tasks before choosing.

Is the LLDB version stable?

No. The README says the LLDB implementation is still early-stage and may contain bugs or limitations. Known issues are tracked on GitHub, and the README asks users to report problems.

New agent skills, repos and AI tools — every week

The best new skills and open-source projects, the fastest-growing repos, and one free prompt. Five minutes to read. Unsubscribe anytime.

Our verdict

pwndbg is a good fit if you already work in GDB on Linux ELF binaries, CTF challenges, qemu-user targets or embedded ARM and RISC-V systems and want a more readable memory and register view. Skip it if you need a stable LLDB workflow, native Windows debugging, or a point-and-click graphical debugger.

Install options & downloads