RecoverPy: Searching Raw Linux Storage for Deleted File Data

RecoverPy's Raw Partition Recovery Scope

RecoverPy addresses a narrow recovery problem: a file has been deleted or overwritten, but some of its data may still exist as raw bytes on a partition. The README explains that deletion removes filesystem metadata first, while the underlying disk blocks may remain intact until they are reused. RecoverPy is designed for that surviving window. It is aimed at users who can recognize part of the missing content, such as a configuration key, an identifier, or a sentence fragment.

The distinction between a file and recoverable bytes matters. RecoverPy does not parse filesystem structures, restore the original filename, or infer complete file boundaries. Its output is discovered content at known offsets that the operator inspects and extracts. That makes it different from a conventional file undelete utility that begins with filesystem metadata and attempts to rebuild directory entries. It is also different from creating a complete forensic image before analysis, although the README does not say whether RecoverPy can scan such an image.

The documented platform boundary is Linux with Python 3.9 or later. Although the repository topics include macOS, the README's requirements list only Linux, and `pyproject.toml` classifies the package as POSIX and Linux. The macOS topic alone is insufficient to claim macOS support. Raw-device access typically requires `sudo`, which also means RecoverPy should only be pointed at storage whose state the operator understands.

Streaming Byte Search and Offset Tracking

RecoverPy opens the selected partition in read-only mode and reads it as a sequential raw byte stream. The search engine processes fixed-size chunks rather than loading the entire device into memory. A small overlap is retained between chunks so that a byte pattern crossing a chunk boundary can still be found. This overlap is part of the recovery mechanism, not a filesystem-aware index or a memory map of the partition.

Matching occurs at the byte level. When RecoverPy finds a match, it records the exact absolute offset within the selected device. That offset becomes the anchor for inspection. The user can open a result, examine the surrounding blocks, move to adjacent blocks, and select useful content for saving. Explicit offsets allow this navigation without asking the filesystem to interpret the region or reading a large portion of the device into memory.

The repository layout reflects these responsibilities. `recoverpy/lib/search/` contains the streaming search engine, while `recoverpy/lib/storage/` handles block and device access. Decoding helpers are separated under `recoverpy/lib/text/`, and the terminal interface is implemented in `recoverpy/ui/` with Textual. This separation makes the central behavior clear: storage code supplies raw blocks, search code locates patterns, text utilities assist inspection, and the TUI presents the interaction. The README does not document configurable chunk size, overlap size, output formats, or the exact decoding rules, so those details should not be inferred.

Installing RecoverPy and Starting a Real Search

For a first installation, the README documents `uv`, local installation through `uv`, and installation with `pip`. The quickest documented route is to launch the packaged command through `uvx`. Because RecoverPy reads raw block devices, the command is run with `sudo`.

sudo uvx recoverpy

The terminal interface should open with the ability to select a partition. The `sudo` requirement is expected for raw-device access. The README does not document a dry-run mode or a non-privileged partition-selection screen, so operators should not assume one exists.

For a local installation, the README gives these commands:

uv tool install recoverpy
sudo recoverpy

The first command installs the `recoverpy` tool, and the second starts it with raw-device privileges. This route is appropriate when the command will be started more than once. The alternative documented installer is `pip`:

python -m pip install recoverpy
sudo recoverpy

The package metadata identifies the distribution as `recoverpy`, version 2.3.0, with Python `>=3.9,<4.0.0`. Its sole declared runtime dependency is `textual==8.2.8`. These details come from `pyproject.toml`; the README does not promise compatibility with unlisted platforms.

Searching for a Configuration Key Instead of a Common Word

A useful RecoverPy session begins with a string that is unlikely to occur elsewhere. The README specifically recommends a unique identifier, configuration key, or sentence fragment rather than a common word. That advice follows directly from how the tool searches. RecoverPy reports byte matches, but it does not use a filename or filesystem index to rank likely originals.

After starting the interface, the documented sequence is to select a partition, enter the search string, start the scan, open a result, inspect it, navigate adjacent blocks, and save useful content. A distinctive application setting would therefore be a better initial target than a short word that may generate many unrelated matches. The scan runs incrementally, so its duration primarily depends on the size of the selected device, although the README gives no timing or progress details.

Recovery quality depends on the surviving layout. If the target content is split across blocks, RecoverPy provides the means to inspect adjacent regions. If another write reused those blocks, no search technique can return data that is no longer present. The README does not claim that matching results will be contiguous, complete, or automatically grouped into the original file. Saving useful content is an operator decision made after inspection, not an automatic reconstruction stage.

Overwrite Risk During Block-Level Recovery

The most important operational limitation appears in the README's warning: avoid writing to the target partition during recovery and unmount it when possible. This advice follows from RecoverPy's block-oriented access. If the operating system writes new data to the same storage, surviving fragments can be replaced. Since RecoverPy can recover only what remains, reducing new writes protects the remaining evidence.

The README does not claim that the tool creates a forensic image, snapshots a partition, protects against hardware write caches, or guarantees that every read operation leaves the device untouched. It says that the selected partition is opened in read-only mode, but that software-level behavior should not be confused with a separate storage preservation procedure. Users who cannot safely exclude writes from the target device have a reason to stop before scanning.

There is also no promise of completeness. RecoverPy does not interpret filesystem structures, so it cannot tell the operator where a deleted file began and ended. A result can be partial or fragmented. Searching for another distinctive fragment may find another surviving region, but the README does not describe an automatic assembly workflow. RecoverPy should therefore be understood as a targeted extraction interface, not a substitute for preserving the complete medium or restoring a directory from filesystem metadata.

RecoverPy Versus Filesystem-Aware Undelete Tools

The clearest alternative is a filesystem-aware undelete utility that reads existing metadata, follows directory structures, and attempts to restore entries under their original names. RecoverPy deliberately takes the opposite route. It bypasses filesystem abstractions and searches the selected device as raw bytes. That choice helps when metadata is gone but recognizable content remains. It also means RecoverPy cannot automatically rebuild a conventional file hierarchy.

A complete disk acquisition workflow is another different approach. Instead of launching an interactive search against the selected partition, an acquisition workflow would preserve the medium as a full image and perform later examination against that image. The README does not establish whether RecoverPy supports image files, so this is an approach-level comparison rather than a claim about image compatibility. Users who require chain-of-custody procedures or exact whole-device copying would need functionality that the README does not attribute to RecoverPy.

For small, targeted recovery, raw byte search is the defining benefit. For recovering many named files from a still-readable filesystem, filesystem metadata is more useful. For preserving all sectors, including areas that cannot be recognized by a search string, acquisition is the more appropriate method. RecoverPy sits closest to the first case.

RecoverPy 2.3.0 Development and GPL-3.0 Implications

Version 2.3.0 is the current version identified in `pyproject.toml`, and the release list dates that release to 2026-02-14. The last push was on 2026-08-03, and the repository is not archived. Those facts indicate recent project activity, but they do not establish recovery success rates, platform compatibility beyond the documented Linux requirement, or fitness for every forensic setting.

The development setup uses `uv`. Repository contributors can synchronize the development environment with:

uv sync --dev

They can then run the local RecoverPy command:

sudo uv run recoverpy

The documented test command is:

uv run pytest -q

These commands establish a specific maintenance workflow, but the README does not provide test coverage, release policy, migration notes, or compatibility guarantees between versions. The package uses the GPL-3.0 License. Distribution and modification of the software fall under that license's terms. The project metadata reports `GPL-3.0 License` and classifies it as `GNU General Public License v3 (GPLv3)`; determining particular legal obligations requires reviewing the actual license text.

Editorial conclusion

RecoverPy fits Linux users, system administrators, and forensic practitioners who know part of a deleted file's contents and need to inspect surviving raw blocks. It is the wrong choice for automatic restoration of named files, complete disk imaging, encrypted data without access to its plaintext, or storage whose blocks have already been overwritten. Before adoption, verify that the target is supported by the Linux environment, confirm access to the correct partition under read-only conditions, and test the workflow against a disk image or disposable copy rather than the only remaining copy of the data.

Frequently asked questions

Official sources

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