Tool to work with Signal Backup files.
Tool to work with backup files generated by the Signal Android application (https://signal.org/). The tool is provided as-is, there may be bugs. The tool and I are not affiliated with or endorsed by the Signal Foundation.
Signal is an actively developed application and consequently, the database format changes regularly. Often the changes do not affect the backup file format or the working of this program, but every once in a while a change does break (some of) the functionality of this program. It has happened before and it will happen again. Sometimes I fix it within hours, but when I am short on time, it may take a little longer. Any breakage will be dealt with as soon as I have some spare time.
This tool first came in to (public) existence to help fix a few issues in the early backup implementation in Signal Android. Over time much more functionality has been added to this tool. Unfortunately, some of the more experimental functions have occassionally caused of a few issues. For these see ERRATA.
To compile this project, current stable released versions of the following are needed:
dbus. If the program is compiled without dbus, operations that need to open the Signal Desktop client database will not work unless the decrypted encryption key is manually provided.Note that some Linux distributions split their packages depending on whether they are used for compiling programs or not. For example, the OpenSSL dependency may require you to install libssl-dev (on Debian-like systems), or openssl-devel (on Red Hat-like systems). If you need help with this specifically, there are detailed instructions for some common Linux distributions in the compiling section below (under 'CMake').
Windows binary
For the most recent Windows executable, check the releases page. This executable is a static build, cross compiled from my Arch Linux system. It is only minimally tested, but generally appears to work just fine.
Note for Windows users: this is a command line application. This means you can not just double-click the executable to run it, you need to run it from a terminal. Common terminals for Windows are cmd (Command Prompt) and PowerShell. An example of running the program on Windows 10 can be seen here.
Linux packages
nixpkgs as signalbackup-tools and can be installed on NixOS or any system that supports the Nix package manager. For those looking for more information on installing and running the Nix package, or those wanting to help others, there is an issue where information can be found and posted here.macOS
A homebrew formula is provided in HomebrewFormula/signalbackup-tools.rb. To install on macOs with homebrew set up:
brew tap bepaald/signalbackup-tools https://github.com/bepaald/signalbackup-toolsbrew install --HEAD signalbackup-toolsAlternatively, you can download the formula to your machine and run brew install --HEAD --formula [path/to/signalbackup-tools.rb].
Once installed, the program can be upgraded when necessary by running brew upgrade --fetch-HEAD --formula signalbackup-tools.
Manually compiling should also be possible assuming the dependencies are installed, for more info see here, or more recently here. macOS users might also consider the aforementioned Nix package.
Compiling
To compile the program, first make sure the dependencies are installed. Then three main options are available:
cmake installed. On Linux this method also requires pkg-config (unless building without dbus). From the project directory, run:$ cmake -B build -DCMAKE_BUILD_TYPE=Release
$ cmake --build build -j $(nproc)dbus (and pkg-config), add -DWITHOUT_DBUS=1 to the first command.Below is the terminal output for installing the dependencies and compiling the program on a default Ubuntu 24.04 (slightly abbreviated). Start by opening your preferred terminal emulator. Then you should be able to copy and paste the commands below, one after the other.
…The program is now successfully built in the subdirectory build/, and can simply be run from there (ie. ./build/signalbackup-tools [options]). Alternatively, you can move the program to some directory that is in your $PATH to run it from any location without specifying the full path.
Below is the terminal output for installing the dependencies and compiling the program on a default Fedora 41 installation (slightly abbreviated). Start by opening your preferred terminal emulator. Then you should be able to copy and paste the commands below, one after the other.
…The program is now successfully built in the subdirectory build/, and can simply be run from there (ie. ./build/signalbackup-tools [options]). Alternatively, you can move the program to some directory that is in your $PATH to run it from any location without specifying the full path.
The bash script. In the project directory is a bash script BUILDSCRIPT.bash. Simply run it:
$ ./BUILDSCRIPT.bash To build without dbus, add --config without_dbus to the above command. The script can of course be edited at will to change compilation behavior. The flags can also be changed on the command line when running, for example to build with clang++ instead of g++, simply run $ CXX=clang++ ./BUILDSCRIPT.bash.
Manually. The program can be manually compiled simply by running g++ -std=c++20 */*.cc *.cc -lcrypto -lsqlite3. On linux, by default one needs to add the location of the dbus headers and libraries (simplest way, add: $(pkg-config --cflags --libs dbus-1)). Alternatively, to build on Linux without dbus, add -DWITHOUT_DBUS=1. On macOS, the program must be linked to the Security and CoreFoundation frameworks by adding -framework Security -framework CoreFoundation to the build command. Any compiler flags you feel useful can be added, personally I use at least -O3 -Wall -Wextra. When compiling with an old compiler version (gcc 8.x or clang <= 7), also add the -lstdc++fs flag and replace -std=c++20 with -std=c++17.
[!TIP] In all examples below, one or more passphrases are provided on the command line. If so desired, these can be omitted in which case you are prompted for the passphrase at runtime.
In its simplest form, this tool is run as such:
signalbackup-tools [input] [passphrase]This will open the file input using the provided passphrase, and do nothing with it. If an output file is supplied the backup is written to that file:
signalbackup-tools [input] [passphrase] --output [output]Optionally, a new passphrase can be provided for the output file with the option --opassphrase, or -op for short. If not provided, as in the above example, the input passphrase is used again.
Dump decrypted database to disk
The program can dump the decrypted backup components to a directory, or read the contents of a directory and pack and encrypt it back into a valid backup file. When dumping, make sure the directory to dump to is empty to start with. In theory, the decrypted files could be edited before re-encrypting. The tool can be called the same as above, except the output should be a directory:
signalbackup-tools [input] [passphrase] --output [outputdirectory]To skip exporting media (like message attachments, avatars and stickers), add the option --onlydb. To re-encrypt the contents of a directory into a valid backup file, use the directory as input and provide the --output and --opassphrase options.
…NOTE The original and new files are not actually guaranteed to be identical, it just so happens that in this case the AvatarFrames are read from the filesystem in the order they appeared in the original.
Dump media to disk
To only export media attachments from one or all of the threads in a backup, run with --dumpmedia as follows:
signalbackup-tools [input] [passphrase] --dumpmedia [outputdirectory]Where outputdirectory is an empty directory, or does not exist (in which case it will be created).
To limit the export to certain threads, the option `--limittothread
No open issues yet, or sync has not completed.