# fatdefrag
A tool for defragmenting FAT32 and exFAT filesystems on Linux and macOS. Designed for SD cards used with embedded systems (e.g., SDFat library) where fragmented files cause significant performance degradation.
NOTE: This was originally created for BlueSCSI but since release v2026.02.08 is not required any more due to FastSeek by Ian (@polpo).
WARNING: Backup your data before any operation with this tool.
## Why?
When using FAT filesystems on SD cards with embedded devices, fragmented files force the SD card controller to perform multiple seeks through the FAT table, dramatically slowing sequential reads. In addition some devices such as the FloppyEMU can't read fragmented files.
Neither Linux nor macOS has a native FAT defragmentation tool. This project fills that gap.
## Features
- **Check fragmentation**: Analyze files and report extent counts
- **Single-file defrag**: Move a fragmented file to contiguous clusters
- **Full filesystem defrag**: Defragment all fragmented files at once
- **Crash recovery journaling**: Journal-based recovery for interrupted operations
## Portable Binaries
Pre-built x86_64 Linux binaries are available on the [GitHub Releases](https://github.com/yourusername/fatdefrag/releases) page. No compilation or dependencies required.
**GUI** (AppImage):
```bash
chmod +x fatdefrag-gui-x86_64.AppImage
./fatdefrag-gui-x86_64.AppImage
# If FUSE is unavailable:
./fatdefrag-gui-x86_64.AppImage --appimage-extract-and-run
```
**CLI/TUI** (statically linked):
```bash
chmod +x fatdefrag-linux-x86_64
./fatdefrag-linux-x86_64 check /dev/sdX1
```
**NixOS** users: AppImages require FUSE, which NixOS doesn't provide by default. Use `appimage-run`:
```bash
nix-shell -p appimage-run --run "appimage-run ./fatdefrag-gui-x86_64.AppImage"
```
## Building from Source
See [BUILDING.md](BUILDING.md) for build instructions, requirements, and portable build details.
## GUI Usage
Launch the GUI with:
```bash
./fatdefrag-gui-linux-x86_64 # or fatdefrag-gui-macOS-aarch64, etc.
```
**Features:**
- **Drive selector**: Shows only removable FAT32/exFAT drives (protects system drives)
- **Cluster map**: Visual representation of disk layout with real-time animation during defrag
- **Fragmented files list**: Click a file to highlight its clusters on the map
- **Defrag All / Defrag File**: Defragment everything or just selected files
- **Backup warning**: Confirmation dialog before any defrag operation
**Color Legend:**
- Dark blue: Free clusters
- Teal: Used (contiguous) clusters
- Orange/Red: Fragmented clusters
- Yellow pulse: Reading
- Green pulse: Writing
- White border: Selected file's clusters
**Note:** The GUI can enumerate drives without root, but defrag operations require block device access. On Linux, use`sudo` or add your user to the `disk` group. On macOS, the app will prompt for permission automatically.
## TUI Usage
A ncurses Terminal UI (TUI) remenicent of the DOS days.
Launch the TUI with:
```bash
./fatdefrag-tui-linux-x86_64 # or fatdefrag-tui-macOS-aarch64, etc.
```
**Keyboard Controls:**
| Key | Action |
|-----|--------|
| `↑/↓` | Change drive selection |
| `A` | Analyze selected drive |
| `D` | Defrag All (after analysis) |
| `S` | Stop current operation |
| `R` | Refresh drive list |
| `Q` | Quit |
**Color Legend:**
- White: Used clusters
- Cyan: Free clusters
- Red: Fragmented clusters
- Yellow: Reading
- Green: Writing
**Note:** Requires block device access. On Linux, use `sudo` or add your user to the `disk` group. On macOS, the app will prompt for permission automatically.
## CLI Usage
Requires block device access. On Linux, use `sudo` or add your user to the `disk` group. On macOS, the app will prompt for permission automatically.
```bash
# Analyze entire filesystem
fatdefrag check /dev/sdX1
# Analyze with verbose output (show fragmented files)
fatdefrag check /dev/sdX1 -v
# Check specific file
fatdefrag check /dev/sdX1 -f /path/to/file.bin
# Defragment all files (dry-run first)
fatdefrag defrag /dev/sdX1 -n
# Defragment all fragmented files
fatdefrag defrag /dev/sdX1
# Defragment a specific file
fatdefrag defrag /dev/sdX1 -f /path/to/file.bin
# Copy file contiguously to FAT device (dry-run first)
fatdefrag copy /path/to/source.bin /dev/sdX1:/dest.bin -n
# Copy file contiguously
fatdefrag copy /path/to/source.bin /dev/sdX1:/dest.bin
```
### Options
| Option | Description |
|--------|-------------|
| `-v, --verbose` | Show detailed output |
| `-f, --file <path>` | Specify file path on filesystem |
| `-n, --dry-run` | Don't make changes, show what would be done |
| `-h, --help` | Show help |
## Windows Users
For defragmenting FAT volumes on Windows, try [Defraggler](https://www.ccleaner.com/defraggler).
## License
Copyright (c) 2026 Eric Helgeson. All rights reserved. See [LICENSE](LICENSE) for details.
This project includes vendored third-party libraries under permissive open source licenses. See [THIRD_PARTY_LICENSES](THIRD_PARTY_LICENSES) for details.
