Reproducible builds

Signal has supported reproducible builds since version 3.15.0. The process lets you independently verify that the app distributed through the Play Store (or the Signal website) is built from exactly the source code in the public repository — with no hidden modifications.

How it works

Signal is distributed as an Android App Bundle. The Play Store uses the bundle to generate a set of device-specific APKs that include only the resources needed for a given device. Reproducing the build and comparing those APKs to what is installed on a device is the core of the verification process. The build environment is captured as a Docker image. Because the image pins all build tool versions, Java version, NDK, and SDK components, anyone who builds the image from the same Dockerfile gets a bit-for-bit identical compiler toolchain. Combined with Signal’s deterministic build configuration, the compiled output is reproducible.

The Dockerfile

The Dockerfile in reproducible-builds/ is the authoritative description of the build environment:

# reproducible-builds/Dockerfile
FROM ubuntu:jammy-20230624@sha256:b060fffe8e1561c9c3e6dea6db487b900100fc26830b9ea2ec966c151ab4c020

RUN apt install -y git openjdk-17-jdk unzip wget

ENV ANDROID_COMMAND_LINE_TOOLS_FILENAME commandlinetools-linux-10406996_latest.zip
ENV ANDROID_API_LEVELS                  android-36
ENV ANDROID_BUILD_TOOLS_VERSION         35.0.0
ENV ANDROID_HOME /usr/local/android-sdk-linux

RUN yes | sdkmanager --sdk_root="${ANDROID_HOME}" \
    "platforms;${ANDROID_API_LEVELS}" \
    "build-tools;${ANDROID_BUILD_TOOLS_VERSION}" \
    "ndk;28.0.13004108" \
    "cmake;3.22.1"

Key pinned components:

Base image: Ubuntu Jammy, pinned by digest
JDK: OpenJDK 17
Android SDK: API level 36, build-tools 35.0.0
NDK: 28.0.13004108
CMake: 3.22.1

Prerequisites

Before you start, install the following tools:

git
docker
python (3.x)
uv (Python package manager)
adb — Android Debug Bridge
bundletool — bundletool releases

Enable Developer Options and USB Debugging on the Android device you want to verify. Connect the device and confirm it is visible:

adb devices

Step-by-step verification

Set up directories

Create a working directory to hold the APKs you will compare:

mkdir ~/reproducible-signal
mkdir ~/reproducible-signal/apks-from-device
mkdir ~/reproducible-signal/apks-i-built

Check your Signal version

In the Signal app go to Settings → Help and note the version number, for example 7.7.0. All subsequent commands use this version.

Clone the exact version

Tags follow the pattern v<version>:

git clone --depth 1 --branch v7.7.0 https://github.com/signalapp/Signal-Android.git

Build the Docker image

cd Signal-Android/reproducible-builds
docker build -t signal-android .

This step downloads and installs all SDK components. It may take several minutes on first run.

Build the app bundle

Run the Gradle build inside the container. The container mounts the repository root and runs as your local user to avoid permission issues:

cd Signal-Android
docker run --rm \
  -v "$(pwd)":/project \
  -w /project \
  --user "$(id -u):$(id -g)" \
  signal-android \
  ./gradlew bundlePlayProdRelease

The output bundle is at app/build/outputs/bundle/playProdRelease/Signal-Android-play-prod-release.aab.

cp app/build/outputs/bundle/playProdRelease/Signal-Android-play-prod-release.aab \
   ~/reproducible-signal/apks-i-built/bundle.aab

Generate device-specific APKs from the bundle

With your device connected, use bundletool to generate the APKs that match your device:

cd ~/reproducible-signal/apks-i-built
bundletool build-apks \
  --bundle=bundle.aab \
  --output-format=DIRECTORY \
  --output=apks \
  --connected-device

Move the split APKs up one level and discard the bundle:

apks-i-built/
  base-master.apk
  base-arm64-v8a.apk   # ABI name depends on your device
  base-xxhdpi.apk      # density name depends on your device

Pull the APKs from your device

cd ~/reproducible-signal
adb shell pm path org.thoughtcrime.securesms \
  | sed 's/package://' \
  | xargs -I{} adb pull {} apks-from-device/

You should now have a apks-from-device/ directory containing base.apk and one or more split_config.*.apk files.

Compare the APKs

Install the apkdiff dependencies and run the comparison:

cd ~/Signal-Android/reproducible-builds/apkdiff
uv sync

Then compare each pair (adjust ABI and density names to match your device):

uv run apkdiff.py \
  ~/reproducible-signal/apks-i-built/base-master.apk \
  ~/reproducible-signal/apks-from-device/base.apk

uv run apkdiff.py \
  ~/reproducible-signal/apks-i-built/base-arm64-v8a.apk \
  ~/reproducible-signal/apks-from-device/split_config.arm64-v8a.apk

uv run apkdiff.py \
  ~/reproducible-signal/apks-i-built/base-xxhdpi.apk \
  ~/reproducible-signal/apks-from-device/split_config.xxhdpi.apk

Each successful comparison ends with APKs match!.

Verifying the website APK

For users without Play Store access, Signal provides a universal APK at signal.org/android/apk. The website build is a single larger APK rather than an app bundle, which simplifies comparison to one pair of APKs. Build with assembleWebsiteProdRelease instead:

docker run --rm \
  -v "$(pwd)":/project \
  -w /project \
  --user "$(id -u):$(id -g)" \
  signal-android \
  ./gradlew assembleWebsiteProdRelease

Output is at app/build/outputs/apk/websiteProdRelease/. Compare that APK directly to the one downloaded from the website (or pulled from the device).

The reproducible-builds/ directory

reproducible-builds/
├── Dockerfile           # Pinned build environment definition
├── README.md            # Official step-by-step guide
├── apkdiff/
│   └── apkdiff.py       # APK comparison script (skips signing metadata)
└── docker/
    ├── apt.conf         # APT configuration for the Docker image
    └── sources.list     # Package mirror sources

apkdiff.py knows how to compare APK internals correctly: APKs are zip archives, so a naive byte-for-byte diff would fail due to zip metadata differences. The script unpacks both APKs, skips files that are intentionally different between Play Store and self-built versions (signing information, stamp-cert-sha256), and compares the remaining entries.

Troubleshooting

APKs don't match

Verify you checked out the exact git tag matching the version on your device.
Confirm you are comparing the right pairs: base-to-base, ABI-to-ABI, density-to-density.
Rebuild the Docker image from scratch (docker build --no-cache) — the Dockerfile may have changed between versions.
Check open issues in case a known mismatch is being tracked.

Build fails inside Docker

Ensure Docker has sufficient memory (at least 4 GB recommended).
Make sure the repo was cloned cleanly at the exact tag — a dirty working tree can affect build outputs.
Check that the --user flag matches your local UID/GID to avoid permission issues with Gradle caches.

bundletool reports unsupported signature scheme

Google’s public bundletool release does not yet support v3.1 APK signature schemes. You may need to build bundletool from source. Track progress on bundletool issue #369.

Code Transparency (extra credit)

In addition to the full reproducible build check, you can run a faster Code Transparency verification. This checks that the APK on your device was signed with Signal’s transparency key after being submitted to the Play Store:

bundletool check-transparency \
  --mode=connected_device \
  --package-name="org.thoughtcrime.securesms"

Confirm the certificate fingerprint in the output matches:

57 24 B1 15 23 8C 7B 03 E2 6A D9 01 34 FC 77 C5
7B 69 E7 ED DE 3B 70 C2 A7 8E C7 A5 58 3E FC 8E

Code Transparency is a weaker check than the full reproducible build process. It verifies the APK was not modified after Signal submitted it, but it does not verify that the submitted code matches the public git repository. The full reproducible build process covers both.

Development

Internals

How it works

The Dockerfile

Prerequisites

Step-by-step verification

Verifying the website APK

The reproducible-builds/ directory

Troubleshooting

Code Transparency (extra credit)

​How it works

​The Dockerfile

​Prerequisites

​Step-by-step verification

​Verifying the website APK

​The reproducible-builds/ directory

​Troubleshooting

​Code Transparency (extra credit)

How it works

The Dockerfile

Prerequisites

Step-by-step verification

Verifying the website APK

The reproducible-builds/ directory

Troubleshooting

Code Transparency (extra credit)