remap-badblocks 1.0.1

CLI tool for remapping bad sectors on Linux disks using device-mapper

remap-badblocks

remap-badblocks is a Linux CLI tool written in Python that scans a block device for bad sectors and creates a device-mapper target that skips over them. It can also reserve extra space to dynamically remap future badblocks.

It's a simple way to extend the usefulness of slightly damaged drives, ideal for anyone who wants to avoid discarding a disk due to a few bad sectors. This can also be useful for disk rescue, when your broken disk fails when reading some of its sectors (see example workflow below).

Features

• Scans disks using badblocks to identify damaged sectors
• Creates a device-mapper target that avoids bad sectors
• Reserves spare sectors for dynamic remapping
• Supports using only part of a device (e.g., for hard partitioning or isolation)

Installation

From PyPI

pip install remap-badblocks

From source

git clone [https://gitlab.com/Luigi-98/remap-badblocks.git](https://gitlab.com/Luigi-98/remap-badblocks.git)
cd remap-badblocks
pip install -e .

Usage

Database

remap-badblocks relies on a single source of stateful storage: a SQLite database. By default, it is stored at /etc/remap_badblocks/devices_config.db, but you can specify an alternative location using the -P option.

Device Model

A device in remap-badblocks is a logical configuration that:

• points to a physical block device (e.g. /dev/sda)
• scans bad blocks and keeps track of them over time
• defines how they are remapped using spare sectors
• creates a virtual block device that actually remaps broken sectors to good ones

The actual /dev/mapper/... device is only created when you run apply.

CLI Overview

remap-badblocks -h

Usage: remap-badblocks [OPTIONS] COMMAND [ARGS]...

Badblocks remapper for block devices.

Commands:
  init            Initialize a device (add + scan + remap + apply)
  update-mapping  Scan for new badblocks, update mapping, and apply
  apply           Apply an existing mapping (recreate /dev/mapper device)

  device          Low-level device operations
  version         Show version

High-level commands (recommended)

These commands cover the most common workflows:

# Initialize a device (first-time setup)
remap-badblocks init my_disk --path /dev/sda --spare-space 100MB

# Periodically update mapping with new badblocks
remap-badblocks update-mapping --name my_disk --mode read

# Recreate the device-mapper (e.g. after reboot)
remap-badblocks apply

Low-level commands

You can also control each step individually and do some tweaking of the devices:

remap-badblocks device -h

Commands:
  add       Define a new device (no mapping yet)
  list      List devices
  get       Show device info from DB
  set       Modify device configuration
  remove    Remove a device

  scan      Scan for badblocks (updates DB only)
  remap     Update mapping based on known badblocks
  apply     Apply mapping to create /dev/mapper device

Advanced workflows

Manual control

# Define device (choose spare space here)
remap-badblocks device add my_disk --path /dev/sda --spare-space 100MB

# Scan disk
remap-badblocks device scan my_disk --mode read

# Update mapping
remap-badblocks device remap my_disk

# Apply mapping
remap-badblocks device apply my_disk

Incremental remapping (data recovery scenario)

# Scan for new badblocks only
remap-badblocks device scan my_disk

# Remap all badblocks that were not remapped so far
remap-badblocks device remap my_disk

This allows updating the mapping without rebuilding it from scratch, minimizing disruption and preserving data access.

Disk rescue workflow (read-first, map-later)

remap-badblocks can also be used as a read stabilizer for damaged disks during data recovery. The idea is to:

1. create an initial mapping table without taking badblocks into account, this way you can preserve the original sector order,
2. remap broken sectors, so that disk doesn't fail trying to read from them,
3. use external tools to copy the data.
   • if new badblocks need to be remapped during rescue, you can pause the rescue, scan for new badblocks and remap them live without any downtime for the virtual remapper device

Step 1 — Define the device without scanning

Create the device and reserve spare sectors, but do not scan yet:

remap-badblocks device add rescue_disk --path /dev/sda --spare-space 10MB
remap-badblocks device remap --name rescue_disk --ignore-badblocks

At this point there are no badblocks recorded and no remapping logic applied beyond reserving space.

Step 2 — Remap broken sectors

Now that you've got a 1:1 mapping from real device to virtual device, you can remap badblocks to spare sectors.

If you already have a list of badblocks, you can avoid further disk wear by doing this:

remap-badblocks device scan --name rescue_disk --mode skip --known-badblocks-file /my/known/badblocks/list.txt
remap-badblocks device remap --name rescue_disk
remap-badblocks device apply --name rescue_disk

Otherwise, let remap-badblocks scan the disk for you before remapping.

sudo remap-badblocks device scan --name rescue_disk --mode read
remap-badblocks device remap --name rescue_disk
sudo remap-badblocks device apply --name rescue_disk

Now your virtual disk can be accessed at /dev/mapper/rescue_disk as a block device.

Step 3 — Run your recovery tool

Use tools like ddrescue, testdisk, or filesystem-specific recovery utilities against the mapper:

ddrescue /dev/mapper/rescue_disk image.img mapfile

Incrementally handle read errors

When read errors occur, you can still remap badblocks without taking the device down. I/O will be suspended only during the apply command, so that no downtime is needed.

Option A — Targeted scan (avoid if possible)

sudo remap-badblocks device scan --name rescue_disk --mode read
remap-badblocks device remap --name rescue_disk
sudo remap-badblocks device apply --name rescue_disk --allow-reapply

Option B — Manual intervention (advanced, but avoids wearout of disk) If you know the failing block ranges from your recovery tool, you can add/remap them directly, then re-apply.

sudo remap-badblocks device scan --name rescue_disk --mode skip --known-badblocks-file /my/known/badblocks/list.txt
remap-badblocks device remap --name rescue_disk
sudo remap-badblocks device apply --name rescue_disk --allow-reapply

Contributing

We welcome feedback, bug reports, feature ideas, code contributions, and help shaping the roadmap — or even rethinking the project from the ground up.

Start with CONTRIBUTING.md, then open an issue or submit a merge request to get involved.

License

GPL v3 License — see LICENSE for details.

Community

• GitLab: remap-badblocks project page
• PyPI: remap-badblocks
• Issues: remap-badblocks Gitlab issues

Acknowledgements & Related Tools

• badblocks
• device-mapper