RecuperaBit rebuilds NTFS directory trees from corrupted metadata

The target is metadata damage, not damaged file content

RecuperaBit is described as a tool for forensic file system reconstruction, software that attempts to reconstruct file system structures and recover files. Currently it supports only NTFS.

The scope of the damage it targets is specific, and it is the one that makes the tool interesting. The reconstruction is attempted regardless of a missing partition table, unknown partition boundaries, partially overwritten metadata, or a quick format. Those are four different ways a volume can lose its index while the data blocks themselves may still be intact, and they are exactly the cases where a standard undelete tool has nothing to work with because it expects a valid file system to navigate.

The design output is a rebuilt directory structure, not just a list of carved fragments. That difference matters in a forensic workflow, where a file's path is part of its evidentiary value.

The README points to the underlying algorithms through the author's MSc thesis and a set of slides, and the topics tag the project dfir, disk, forensics, ntfs, partition and recover-files. The tool is GPL-3.0 licensed, and pyproject.toml records it as GPL-3.0-or-later with Development Status 5, Production/Stable. The author is Andrea Lazzarotto, and the last push was on 2026-07-26, with the most recent tagged release being v1.1.6 from 2022-01-02.

Installation is a pip or uv call

The installation section is short, which is not what you would expect from a tool with an interactive command shell later on. The package is on PyPI and installs with pip:

pip install recuperabit

or, as a tool, with uv:

uv tool install recuperabit

The packaging metadata backs that up. The project name is RecuperaBit at version 1.1.6.post1, it requires Python 3.9 or newer, and its dependencies list is empty, meaning the reconstruction logic is written in the standard library rather than on top of a parsing framework. The console script is declared as recuperabit = "recuperabit.cli:main", and the build backend is uv_build. The classifiers cover Python 3.9 through 3.15, and the environment is a console application intended for information technology and system administration audiences.

The repository layout is modern for a project of its age, with a src directory, a pyproject.toml, a uv.lock and a .github directory, which is consistent with a tool that has been modernised since the v1.1 releases.

One point from the documentation belongs here rather than later: the tool can be run with the standard cPython implementation, but speed can be increased by using it with the Pypy interpreter and JIT compiler, invoked as pypy3 main.py /path/to/disk.img. For a tool that scans a whole image, that is a meaningful difference in wall clock time.

Always work on a copy, because the tool reads the image repeatedly

The usage warning in the documentation is the most operationally important paragraph in the README, and it comes before any instruction about what to type.

The main argument is the path to a bitstream image of a disk or partition. RecuperaBit automatically determines the sectors from which partitions start, and it 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 the documentation says this is not advised for damaged drives, because RecuperaBit might worsen the situation by stressing a damaged drive, or it could crash due to an I/O error. Both failure modes are bad. A drive that is degrading can lose the last readable copy of a sector during a long read-heavy scan, and a tool that crashes on an I/O error leaves you with a partial scan and an image that is no longer pristine.

The safe workflow is the standard forensic one: image the disk first with a dedicated imaging tool, verify the image, and point RecuperaBit at the image file. The tool's own behaviour, reading some regions more than once, is normal for reconstruction, since it revisits metadata structures while rebuilding, but it does mean a live device is exposed to sustained random reads rather than a single sequential pass.

The command line interface is minimal, with the path to the disk image as the positional argument and four options:

usage: recuperabit [-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 save file is what makes the second run fast

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.

That is a two phase design that matches how the algorithm has to work. The scanning pass has to look broadly across the image, and the reconstruction pass then works from what was found. Saving the scan results means a second run does not repeat the expensive broad pass, which matters on a large image where the scan is the slow part.

The -w flag forces an overwrite of the save file, and the existence of that flag is itself informative. If the underlying data has changed, or you want a clean scan rather than a resumed one, you need to discard the old results, and the tool makes that an explicit decision rather than something it decides for you.

The output side has two channels. 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, and these are exported in the directory specified by -o, or recuperabit_output if the option is not given. The CSV listing is the artefact you would attach to a report, since it enumerates what was recovered and from where.

Restoring from a directory id, and the Root node for NTFS is 5

After the scanning process has completed, the list of partitions that can be recovered is shown by issuing a command at the prompt, and each line shows information about a partition:

recoverable

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)

That single line carries a lot of forensic detail. The offset in sectors and the offset in bytes, the sectors per cluster, and the MFT and MFT mirror offsets all describe the geometry of the reconstructed volume, and the MFT mirror offset in particular is a useful cross-check because a plausible mirror location is a good sign that the reconstruction landed on a real structure rather than a coincidence.

Files can be restored one at a time or recursively, starting from a directory. To see the tree on screen there is the tree command, which the documentation warns is very verbose for large drives, and the alternative is to export a CSV list of files with the help command for details.

Extracting everything requires the identifier of the root directory, which depends on the file system type. The documentation gives a table with NTFS mapped to 5, and notes that the id for Lost Files is -1 for every file system. So for the example partition:

restore 0 5 restore 0 -1

The first command restores from the root, the second from the lost and found area where files that had a parent that could not be reconstructed end up. The files are saved inside the output directory specified by -o.

NTFS compressed files are the documented gap

There is a Limitation section and it contains one item: RecuperaBit does not work with compressed files on an NTFS filesystem.

The documentation goes further and explains why that matters for anyone considering it. If you have deep knowledge of the inner workings of file compression on the NTFS filesystem, your help would be much appreciated, as available documentation is quite sparse on the topic.

That last clause is the honest part. NTFS compression, the LZNT1 style compressed data streams that the file system stores, is poorly documented publicly, and a tool that reconstructs the metadata of such a volume has to understand the compression metadata well enough to interpret the entries it finds. If it does not, the affected entries are simply not recovered, and the file names may be missing along with the data.

The practical implication is that a volume with compressed files has an unknown recovery rate, and you cannot tell from the tool's output how many entries were skipped. On a Windows system, compression is not the default, but it is used for system directories such as the Windows directory in some configurations, so it is not a rare edge case on a workstation image.

Beyond that, the support boundary is the file system itself. NTFS is the only supported format, so an ext4 volume, an APFS volume or a FAT32 stick falls outside the tool entirely, and the partition detection step will find nothing it can reconstruct.

Where this is the wrong tool

Three situations rule it out, and they are all about scope rather than quality.

The first is a non NTFS volume. The limitation is stated without hedging, currently it supports only NTFS, and the root id table has a single row. For a Linux ext4 filesystem, a macOS APFS container or a camera card, this tool does nothing, and a general purpose file carver that walks the raw data blocks is the right approach.

The second is a volume whose metadata is fine. If the partition table is intact and the directory structure is readable, you want tools for undeleting specific files or for copying the volume, and RecuperaBit's entire value, reconstructing structure from damaged metadata, is not needed. Running a reconstruction over a healthy volume is slower and produces a derived tree rather than the original one.

The third is a deadline with a large image. The scanning pass is the slow part, the save file only helps on a second run, and the documentation notes that the tree command is very verbose for large drives. On a multi terabyte image you will be waiting, and the interactive command shell is single threaded, so there is no parallelism described anywhere in the documentation.

The alternative worth naming is a general purpose carver, which scans raw data blocks for file signatures and reconstructs files without needing the file system metadata. The trade is the reverse of RecuperaBit's. A carver recovers file content from a volume with destroyed metadata but gives you flattened, renamed files with no original directory structure, while RecuperaBit gives you the tree when it can rebuild it, and the documentation is honest that it currently only does NTFS.

Editorial conclusion

RecuperaBit fits an incident responder or system administrator who has a damaged NTFS volume, a missing partition table or a quick format, and needs the directory structure rebuilt before deciding which files to recover. It is the wrong tool for ext4, APFS or any non NTFS filesystem, since NTFS is the only supported format, and it is the wrong tool when the priority is content recovery from a volume whose metadata is intact, since a general purpose carver is faster for that. Before running it, check three things: that you are working on a bitstream image rather than the original drive, because the documentation warns that reading a damaged drive repeatedly can worsen its condition, that you keep the scan save file, since it is what makes the second run fast, and that no file you need is an NTFS compressed file, because compressed file support is an explicit gap.

Frequently asked questions

Official sources

1. Issues
2. Lazza/RecuperaBit on GitHub
3. License: GPL-3.0
4. README
5. Releases