A tool for forensic file system reconstruction.
Branch: master
Clone or download
Latest commit 3a7c133 Feb 4, 2018
Type Name Latest commit message Commit time
Failed to load latest commit information.
misc Fixes #3 Nov 20, 2016
recuperabit Fix #32 Feb 4, 2018
.gitignore Initial commit Jan 24, 2016
LICENSE Initial commit Jan 24, 2016
README.md Included donation links Dec 3, 2017
__init__.py script + instructions for running on Android Sep 2, 2016
main.py Added traceback routine for exploring ancestors of a file. Closes #29 Dec 10, 2017



Support via PayPal    gitcheese.com

A software which attempts to reconstruct file system structures and recover files. Currently it supports only NTFS.

RecuperaBit attempts reconstruction of the directory structure regardless of:

  • missing partition table
  • unknown partition boundaries
  • partially-overwritten metadata
  • quick format

You can get more information about the reconstruction algorithms and the architecture used in RecuperaBit by reading my MSc thesis or checking out the slides.


usage: main.py [-h] [-s SAVEFILE] [-w] [-o OUTPUTDIR] path

Reconstruct the directory structure of possibly damaged filesystems.

positional arguments:
  path                  path to the disk image

optional arguments:
  -h, --help            show this help message and exit
  -s SAVEFILE, --savefile SAVEFILE
                        path of the scan save file
  -w, --overwrite       force overwrite of the save file
  -o OUTPUTDIR, --outputdir OUTPUTDIR
                        directory for restored contents and output files

The main argument is the path to a bitstream image of a disk or partition. RecuperaBit automatically determines the sectors from which partitions start.

RecuperaBit does not modify the disk image, however it does read some parts of it multiple times through the execution. It should also work on real devices, such as /dev/sda but this is not advised for damaged drives. RecuperaBit might worsen the situation by "stressing" a damaged drive or it could crash due to an I/O error.

Optionally, a save file can be specified with -s. The first time, after the scanning process, results are saved in the file. After the first run, the file is read to only analyze interesting sectors and speed up the loading phase.

Overwriting the save file can be forced with -w.

RecuperaBit includes a small command line that allows the user to recover files and export the contents of a partition in CSV or body file format. These are exported in the directory specified by -o (or recuperabit_output).


RecuperaBit can be run with the standard cPython implementation, however speed can be increased by using it with the Pypy interpreter and JIT compiler:

pypy main.py /path/to/disk.img

Recovery of File Contents

Files can be restored one at a time or recursively, starting from a directory. After the scanning process has completed, you can check the list of partitions that can be recovered by issuing the following command at the prompt:


Each line shows information about a partition. Let's consider the following output example:

Partition #0 -> Partition (NTFS, 15.00 MB, 11 files, Recoverable, Offset: 2048, Offset (b): 1048576, Sec/Clus: 8, MFT offset: 2080, MFT mirror offset: 17400)

If you want to recover files starting from a specific directory, you can either print the tree on screen with the tree command (very verbose for large drives) or you can export a CSV list of files (see help for details).

If you rather want to extract all files from the Root and the Lost Files nodes, you need to know the identifier for the root directory, depending on the file system type. The following are those of file systems supported by RecuperaBit:

File System Type Root Id

The id for Lost Files is -1 for every file system.

Therefore, to restore Partition #0 in our example, you need to run:

restore 0 5
restore 0 -1

The files will be saved inside the output directory specified by -o.


This software is released under the GNU GPLv3. See LICENSE for more details.