* readme/docs changes in install methods
* tip
* tip
* tip
* cleanup installation instructions
* gdb/lldb is bundled
---------
Co-authored-by: k4lizen <124312252+k4lizen@users.noreply.github.com>
- [Install from source GDB](#install-from-source-gdb)
- [Install from source LLDB](#install-from-source-lldb)
- [Environment setup](#environment-setup)
- [Development using Nix](#development-using-nix)
- [Testing](#testing)
@ -26,6 +28,60 @@
# Development Basics
## Install from source GDB
Installation from source is straightforward:
```shell
git clone https://github.com/pwndbg/pwndbg
cd pwndbg
./setup.sh
```
Pwndbg is supported on Ubuntu 22.04, and 24.04 with GDB 12.1 and later. We do not test
on any older versions of Ubuntu, so `pwndbg` may not work on these versions.
- For Ubuntu 20.04 use the [2024.08.29 release](https://github.com/pwndbg/pwndbg/releases/tag/2024.08.29)
- For Ubuntu 18.04 use the [2023.07.17: ubuntu18.04-final release](https://github.com/pwndbg/pwndbg/releases/tag/2023.07.17)
We may accept pull requests fixing issues in older versions on a case by case basis,
please discuss this with us on [Discord][discord] first. You can also always checkout
an older version of `pwndbg` from around the time the Ubuntu version you're interested
in was still supported by Canonical, or you can attempt to build a newer version of GDB from source.
Other Linux distributions are also supported via `setup.sh`, including:
* 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)
If you use any Linux distribution other than Ubuntu, we recommend using the [latest available GDB](https://www.gnu.org/software/gdb/download/) built from source. You can build it as:
@ -79,130 +79,7 @@ Pwndbg ensures a consistent experience across both, so switching between them is
## How?
For a portable version with no external dependencies, scroll down for the [Portable Installation](#portable-installation) section.
### Installing LLDB
* Install via the Nix package manager (you can use Nix on any distribution):
```shell
nix shell github:pwndbg/pwndbg#pwndbg-lldb
pwndbg-lldb ./your-binary
```
* Or download portable version with no external dependencies, scroll down for the [Portable Installation](#portable-installation) section
* ~~Or install from source, instructions below.~~ (not supported)
### Installing GDB
* Install via the Nix package manager (you can use Nix on any distribution):
```shell
nix shell github:pwndbg/pwndbg
pwndbg ./your-binary
```
* Or download portable version with no external dependencies, scroll down for the [Portable Installation](#portable-installation) section
* Or install from source, instructions below.
<details>
<summary>Click here to expand instructions</summary>
Installation from source is straightforward:
```shell
git clone https://github.com/pwndbg/pwndbg
cd pwndbg
./setup.sh
```
Pwndbg is supported on Ubuntu 22.04, and 24.04 with GDB 12.1 and later. We do not test
on any older versions of Ubuntu, so `pwndbg` may not work on these versions.
- For Ubuntu 20.04 use the [2024.08.29 release](https://github.com/pwndbg/pwndbg/releases/tag/2024.08.29)
- For Ubuntu 18.04 use the [2023.07.17: ubuntu18.04-final release](https://github.com/pwndbg/pwndbg/releases/tag/2023.07.17)
We may accept pull requests fixing issues in older versions on a case by case basis,
please discuss this with us on [Discord][discord] first. You can also always checkout
an older version of `pwndbg` from around the time the Ubuntu version you're interested
in was still supported by Canonical, or you can attempt to build a newer version of GDB from source.
Other Linux distributions are also supported via `setup.sh`, including:
* 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)
If you use any Linux distribution other than Ubuntu, we recommend using the [latest available GDB](https://www.gnu.org/software/gdb/download/) built from source. You can build it as:
There are multiple ways to install pwndbg, depending on whether you want to use it [with GDB](#installing-pwndbg-gdb), [with LLDB](#installing-pwndbg-lldb), use a [portable release](#download-the-portable-version), or install it [from source](#installing-from-source).
```shell
git clone https://github.com/pwndbg/pwndbg
cd pwndbg
./setup.sh
## Installing pwndbg-gdb
Install via curl/sh (Linux/macOS)
```{.bash .copy}
curl -qsL 'https://install.pwndbg.re' | sh -s -- -t pwndbg-gdb
```
## Install on Linux distributions
Nix package manager (you can use Nix on any distribution):
```shell
nix shell github:pwndbg/pwndbg
pwndbg ./your-binary
Install via Homebrew (macOS)
```{.bash .copy}
brew install pwndbg/tap/pwndbg-gdb
```
Pwndbg is supported on Ubuntu 22.04, and 24.04 with GDB 12.1 and later. We do not test on any older versions of Ubuntu, so `pwndbg` may not work on these versions (for Ubuntu 18.04 use the [2023.07.17: ubuntu18.04-final release](https://github.com/pwndbg/pwndbg/releases/tag/2023.07.17)). We may accept pull requests fixing issues in older versions on a case by case basis, please discuss this with us on [Discord](https://discord.gg/x47DssnGwm) first. You can also always checkout an older version of `pwndbg` from around the time the Ubuntu version you're interested in was still supported by Canonical, or you can attempt to build a newer version of GDB from source.
Other Linux distributions are also supported via `setup.sh`, including:
* 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)
If you use any Linux distribution other than Ubuntu, we recommend using the [latest available GDB](https://www.gnu.org/software/gdb/download/) built from source. You can build it as:
When installing with GDB, you may also download a package to install through your package manager of choice. Download the package from the [releases page](https://github.com/pwndbg/pwndbg/releases) and pick the appropriate download from the second table.
## Portable Installation from package
The portable version includes all necessary dependencies and should work without the need to install additional packages.
### Download the Portable Version:
Download the portable version from the [Pwndbg releases page](https://github.com/pwndbg/pwndbg/releases) by selecting the desired version.
Choose the appropriate version for your system architecture (x86_64, armv7l, aarch64, riscv64).
### Installation on RPM-based Systems (CentOS/Alma/Rocky/RHEL):
```shell
RPM-based Systems (CentOS/Alma/Rocky/RHEL):
```{.bash .copy}
dnf install ./pwndbg-2025.04.18.x86_64.rpm
# pwndbg
```
### Installation on DEB-based Systems (Debian/Ubuntu/Kali):
curl -qsL 'https://install.pwndbg.re' | sh -s -- -t pwndbg-lldb
```
Install via Homebrew (macOS)
```{.bash .copy}
brew install pwndbg/tap/pwndbg-lldb
```
Install via the Nix package manager (Linux/macOS):
```{.bash .copy}
nix shell github:pwndbg/pwndbg#pwndbg-lldb
```
## Download the Portable Version
You can download a portable release on the [pwndbg releases page](https://github.com/pwndbg/pwndbg/releases). There are seperate releases for GDB and LLDB. Use the first table to pick the appropriate download for your system architecture. You can then unpack the archive with:
```{.bash .copy}
tar -v -xf <archive-name>
```
And run pwndbg with
```bash
./pwndbg/bin/pwndbg
```
or
```
./pwndbg/bin/pwndbg-lldb
```
depending on which version you installed. You may add the appropriate file to your shell's PATH.
!!! warning ".gdbinit doesn't work for portable release"
If you're running `./pwndbg/bin/pwndbg` from the portable release, it is a known limitation that pwndbg settings in your `.gdbinit` won't work (see [issue #2774](https://github.com/pwndbg/pwndbg/issues/2774)). Also, make sure not to source pwndbg in your gdbinit as it already happens automatically for portable releases (if this is the first time you're installing pwndbg, you don't need to worry about this).
## Installing from source
See the relevant section in DEVELOPING.md: [with GDB](https://github.com/pwndbg/pwndbg/blob/dev/DEVELOPING.md#install-from-source-gdb), [with LLDB](https://github.com/pwndbg/pwndbg/blob/dev/DEVELOPING.md#install-from-source-lldb).
patryk4815
8 months ago
committed by
GitHub