Skip to content

Setup Pwndbg for Development¤

Installing Pwndbg from source¤

Run the following: 

git clone https://github.com/pwndbg/pwndbg
cd pwndbg
./setup.sh
Officially supported is Ubuntu 22.04 and later, but the setup script also supports the following distributions:

  • Debian-based OSes (via apt-get)
  • Fedora and Red Hat (via dnf)
  • Clear (via swiped)
  • OpenSUSE LEAP (via zypper)
  • Arch and Manjaro (via community AUR packages)
  • Void (via xbps)
  • Gentoo (via emerge)

Tip

If you have an older ubuntu version you may still use Pwndbg:

however if you wish to contribute, it is recommended you upgrade your distribution.

Running with GDB¤

Pwndbg requires GDB 12.1 or later. If the GDB version your distro provides is too old, build GDB from source: 

sudo apt install libgmp-dev libmpfr-dev libreadline-dev texinfo  # required by build
git clone git://sourceware.org/git/binutils-gdb.git
mkdir gdb-build
cd gdb-build
../binutils-gdb/configure --enable-option-checking --disable-nls --disable-werror --with-system-readline --with-python=$(which python3) --with-system-gdbinit=/etc/gdb/gdbinit --enable-targets=all --disable-binutils --disable-ld --disable-gold --disable-gas --disable-sim --disable-gprof
make -j $(nproc)
Since the ./setup.sh script made it so you source Pwndbg from your ~/.gdbinit, Pwndbg will start up automatically any time you run gdb.

Running with LLDB¤

Pwndbg requires LLDB 19 or later. You can get it like this on Ubuntu 24.04: 

sudo apt install -y lldb-19 liblldb-19-dev
but it will be added to your PATH as lldb-19 so you should either alias it or export it in your shell: 
export PATH=/usr/lib/llvm-19/bin/:$PATH
so you can invoke it as lldb. Also export this environment variable: 
export LLDB_DEBUGSERVER_PATH=/usr/lib/llvm-19/bin/lldb-server
Pwndbg doesn't use the lldb driver binary directly, it drives its own REPL and interacts with LLDB through liblldb. You can run Pwndbg with LLDB by running: 
uv run python pwndbg-lldb.py [binary-to-debug]

The development environment¤

After installing Pwndbg like described above, there are a few ways to set up the development environment. The simplest one is by running: 

./setup-dev.sh
but you can also use the docker container or develop using nix.

Development from docker¤

You can create a Docker image with everything already installed for you. You can use docker compose 

docker compose run -i main
or build and run the container with 
docker build -t pwndbg .
docker run -it --cap-add=SYS_PTRACE --security-opt seccomp=unconfined -v `pwd`:/pwndbg pwndbg bash

Development using Nix¤

Pwndbg supports development with Nix which installs all the required development dependencies:

  1. Install Nix with Determinate Nix Installer.
  2. Enter the development shell with nix develop or automate this with direnv.
  3. Run local changes with pwndbg or pwndbg-lldb. Run tests with ./tests.sh.