Installation

Complete guide to installing AFL++ via Docker or building from source on Linux, macOS, and iOS

AFL++ can be installed using Docker for quick setup, or built from source for optimal performance and customization.

Docker installation (recommended for quick start)

The easiest way to get started with AFL++ is using the official Docker image, available for both x86_64 and arm64:

docker pull aflplusplus/aflplusplus
docker run -ti -v /location/of/your/target:/src aflplusplus/aflplusplus

This image is automatically published when a push to the stable branch happens. Your target source code will be accessible at /src inside the container.

You can also pull aflplusplus/aflplusplus:dev for the most current development state of AFL++.

Using tmpfs for better performance

For heavy fuzzing workloads, use a RAM-disk to prevent wear on SSDs/HDDs:

docker run -ti --mount type=tmpfs,destination=/ramdisk -e AFL_TMPDIR=/ramdisk aflplusplus/aflplusplus

Building from source on Linux (x86)

Building from source is recommended over Docker for production fuzzing campaigns to achieve optimal performance.

Prerequisites

Install required dependencies on Debian/Ubuntu/Kali:

Replace -18 with whatever LLVM version is available in your distribution. We recommend LLVM 18 or newer, with a minimum of LLVM 14.

sudo apt-get update
sudo apt-get install -y build-essential python3-dev automake cmake git flex bison libglib2.0-dev libpixman-1-dev python3-setuptools cargo libgtk-3-dev
# try to install llvm-18 and install the distro default if that fails
sudo apt-get install -y lld-18 llvm-18 llvm-18-dev clang-18 || sudo apt-get install -y lld llvm llvm-dev clang
sudo apt-get install -y gcc-$(gcc --version|head -n1|sed 's/\..*//g'|sed 's/.* //')-plugin-dev libstdc++-$(gcc --version|head -n1|sed 's/\..*//g'|sed 's/.* //')-dev
sudo apt-get install -y meson ninja-build # for QEMU mode
sudo apt-get install -y cpio libcapstone-dev # for Nyx mode
sudo apt-get install -y wget curl # for Frida mode
sudo apt-get install -y python3-pip # for Unicorn mode

It is recommended to install the newest available gcc, clang, and llvm-dev possible in your distribution.

Build and install

Clone the repository and build:

git clone https://github.com/AFLplusplus/AFLplusplus
cd AFLplusplus
git submodule update --init
make distrib
sudo make install

Build targets

The following build targets are available:

• all: Main AFL++ binaries and llvm/gcc instrumentation
• binary-only: Everything for binary-only fuzzing (frida_mode, nyx_mode, qemu_mode, unicorn_mode, coresight_mode, libdislocator, libtokencap)
• source-only: Everything for source code fuzzing (nyx_mode, libdislocator, libtokencap)
• distrib: Everything for both binary-only and source code fuzzing
• install: Installs everything you have compiled
• clean: Cleans compiled files
• deepclean: Cleans everything including downloads

1. Quick build

   If you only want plain AFL++ without binary-only modes:

   make all
   
2. Source-only build

   For source code fuzzing with assisting tools but no binary-only support:

   make source-only
   
3. Full build

   For complete AFL++ with all features:

   make distrib
   

Build options

You can customize the build with these options:

• PERFORMANCE=1: Compile with performance optimizations (recommended, except on macOS)
• STATIC=1: Compile AFL++ statically (does not work on macOS)
• LLVM_CONFIG=llvm-config-18: Specify LLVM config if your distro uses non-standard names
• NO_PYTHON=1: Disable Python support
• NO_QEMU=1: Disable building QEMU support
• NO_FRIDA=1: Disable building FRIDA support
• NO_UNICORN=1: Disable building Unicorn

Example with performance optimizations:

make PERFORMANCE=1

Building on macOS (x86_64 and arm64)

macOS has platform-specific quirks that require additional configuration.

Configure shared memory

Increase SYSV shared memory settings before building:

sudo afl-system-config

See Apple’s documentation for making these settings permanent.

Install dependencies

Install required packages via Homebrew:

brew install wget git make cmake llvm gdb coreutils

Configure environment

Determine your Homebrew installation path:

brew info llvm

Then set the appropriate base path:

# For Apple Silicon (M1/M2/M3)
export HOMEBREW_BASE="/opt/homebrew/opt"

# Or for Intel Macs
export HOMEBREW_BASE="/usr/local/opt"

Configure PATH and compiler variables:

export PATH="$HOMEBREW_BASE/coreutils/libexec/gnubin:/usr/local/bin:$HOMEBREW_BASE/llvm/bin:$PATH"
export CC=clang
export CXX=clang++

Build

Follow the general Linux build instructions:

git clone https://github.com/AFLplusplus/AFLplusplus
cd AFLplusplus
git submodule update --init
make all
sudo make install

Verify the installation:

which afl-clang-fast

afl-clang-lto, afl-gcc-fast, and qemu_mode are not supported on macOS. However, FRIDA mode (-O) works on both x86 and arm64.

macOS-specific considerations

Disable the crash reporting daemon before fuzzing:

sudo afl-system-config

Performance notes:

• Fuzzing is typically slower on macOS than Linux due to non-POSIX fork() semantics
• Consider running fuzzing jobs inside a Linux VM for better performance
• If you encounter compatibility issues, set AFL_NO_FORKSRV=1 before starting afl-fuzz

Building on iOS (arm64 and arm64e)

Option 1: Compilation on jailbroken iOS (recommended)

For jailbroken iOS devices with Procursus support:

1. Install dependencies

   SSH into your device and install packages:

   sudo apt install wget git make cmake clang gawk llvm ldid coreutils build-essential xz-utils
   
2. Configure environment

   export IOS_SDK_PATH="/usr/share/SDKs/iPhoneOS.sdk"
   export CC=clang
   export CXX=clang++
   
3. Build

   Follow the general Linux build instructions

Option 2: Cross-compilation on macOS

For building on macOS to deploy on jailbroken iOS:

1. Install ldid

   brew install ldid-procursus
   
2. Configure environment

   export IOS_SDK_PATH="$(xcrun --sdk iphoneos --show-sdk-path)"
   export CC="$(xcrun --sdk iphoneos -f clang) -target arm64-apple-ios14.0"
   export CXX="$(xcrun --sdk iphoneos -f clang++) -target arm64-apple-ios14.0"
   export HOST_CC=cc
   
3. Build and transfer

   Follow the general Linux build instructions, then transfer binaries to your iOS device

Verifying installation

After installation, verify that AFL++ is working:

afl-fuzz -h
afl-cc -h

You should see the help messages for these tools.

Next steps

Now that AFL++ is installed, proceed to the quickstart guide to fuzz your first target.