iOS-backup-manager 2.9.0a9

iOS Backup Manager CLI and Windows GUI

iOS Backup Manager

A powerful cross-platform tool for merging, purging, restoring, and extracting data from iOS/iTunes backups

iOS Backup Manager & Data Recovery Tool enables you to selectively preview and export photos, messages, contacts, calendars, notes, call history, voicemail, and voice memos. You can also make iOS style backups and restore backups to iOS devices. The tool also allows a user to modify iOS backup by merging backups together or purging data from the backups. Perfect for data recovery, backup consolidation, and forensic analysis.

CLI supports Windows, macOS, and Linux. GUI is Windows-only for now.

---

✨ Recent Updates

Version 2.0 - Cross-Platform Support (December 2025)

• ✅ Full Windows, macOS, and Linux support - Unified codebase with platform-specific optimizations
• ✅ Non-modal extraction dialogs - Continue working while extraction runs in background
• ✅ Platform abstraction layer - Consistent experience across all operating systems
• ✅ Automated build system - One-command builds for all platforms
• ✅ Enhanced device detection - Optimized for each platform (WMI events on Windows, polling on Mac/Linux)

---

Features

Core Functionality

• Selective Export - Preview and export specific categories without full restoration
• Full Export of all Data - Export all data that can be found in beautiful HTML friendly searchable reports
• Live Device Backup - Create backups directly from connected iOS devices
• Data Recovery - Recover data from corrupted, incomplete, or damaged backups
• Merge Multiple Backups - Combine data from two iOS backups into a single unified backup
• Purge data from Backup - Can purge or remove select databases from backups (legal remediation)
• Restore Backups - Can be used to restore backups to a device
• Background Operations - Continue browsing and preparing other backups while extraction runs

Supported Data Categories

• 📷 Photos & Media - Images, videos, and camera roll
• 💬 SMS/iMessage - Text messages and iMessages with full conversation history
• 👤 Contacts - Complete contact database with all fields
• 📅 Calendar - Events, reminders, and calendars
• 📝 Notes - All notes and attachments
• 📞 Call History - Complete call logs
• 🎤 Voicemail - Voicemail recordings and metadata
• 🎵 Voice Memos - Voice recordings
• ⚙️ Settings - Device settings and preferences

Advanced Features

• Preview Before Export - Browse and search data before exporting
• Batch Operations - Export multiple conversations or categories at once
• Smart Merging - Intelligent conflict resolution and duplicate detection
• HTML Export - Export SMS conversations as beautifully formatted HTML
• Conversation Pagination - Efficiently handle large message databases (10,000+ messages)
• Drag-and-Drop Support - Easy backup loading via drag-and-drop
• Device Detection - Automatic detection of connected iOS devices
• Wallpaper Preview - Visual backup identification with device wallpaper thumbnails
• Parallel Extraction - Extract multiple categories simultaneously

---

Screenshots

---

Requirements

System Requirements

• Operating System: Windows 10/11, macOS 10.13+, or Linux (Ubuntu 20.04+, Fedora 34+, Debian 11+)
• Python: 3.9 or higher (for development)
• iTunes: Not required, but backups must be in iTunes backup format

Python Dependencies

All dependencies are listed in requirements.txt:

• Pillow (≥10.0.0) - Image processing for wallpaper previews
• pillow-heif (≥0.13.0) - HEIF/HEIC image support
• tkinterdnd2 (≥0.3.0) - Drag-and-drop support
• imageio-ffmpeg (≥0.4.9) - Media conversion
• pymobiledevice3 (≥2.0.0) - iOS device detection and communication
• pydantic (≥2.0.0) - Data validation
• google-protobuf (≥4.0.0) - Protocol buffers
• wmi (≥1.5.1) - Windows device monitoring (Windows only, optional)
• pywin32 (≥306) - Windows API access (Windows only, optional)

---

Installation

Option 0: Install CLI via pip (Cross-platform)

python -m pip install ios-backup-manager

CLI commands:

iosbackup --help
iosbackup list-categories --backup "PATH_TO_BACKUP"
iosbackup extract --backup "PATH_TO_BACKUP" --output "PATH_TO_OUTPUT"

See docs/CLI_USAGE.md for more CLI examples and options.

If iosbackup isn’t found

The CLI entrypoint is installed with the wheel, but your shell must be able to find it.

Option 1: Use pipx (recommended)

python -m pip install --user pipx
python -m pipx ensurepath
pipx install ios-backup-manager

Then run:

iosbackup --help

Option 2: Use a virtual environment

python -m venv .venv
# activate it:
#  - Windows: .venv\Scripts\activate
#  - macOS/Linux: source .venv/bin/activate
python -m pip install ios-backup-manager
iosbackup --help

Option 3: Run via python -m (always works)

python -m ios_backup_manager.cli --help

If you prefer PATH setup, ensure your Python "Scripts" directory is on PATH:

• Windows: %APPDATA%\Python\Python39\Scripts or C:\Program Files\Python39\Scripts
• macOS/Linux: ~/.local/bin (or the active venv's bin/)

GUI command (Windows only):

iosbackup-gui

Option 1: Download Pre-Built Executable (Easiest)

Windows:

1. Download iOSBackupManager.exe from Releases
2. Run the executable - no installation required!

macOS:

1. Download iOSBackupManager.app from Releases
2. Open the .app bundle
3. First run: Right-click → Open (to bypass Gatekeeper)

Linux:

1. Download iOSBackupManager from Releases
2. Make executable: chmod +x iOSBackupManager
3. Run: ./iOSBackupManager

Option 2: Run from Source (Recommended for Development)

1. Clone the Repository

   git clone https://github.com/mcampetta/iOSBackupManager.git
   
   cd iOSBackupManager
   

2. Install Dependencies

   # you may need to add "python -m" or "python3 -m" in front of commands starting with pip depedning no your path setup. 
   pip install -r requirements.txt
   
   # Windows users (optional, for real-time device detection):
   pip install wmi pywin32
   

3. Run the Application

   python backup_merger_gui.py
   

Option 3: Build from Source

See BUILD_GUIDE.md for comprehensive build instructions for all platforms.

Quick Build Instructions:

Windows:

pip install pyinstaller
pyinstaller iOSBackupManager-windows.spec

Output: dist\iOSBackupManager.exe

macOS:

pip3 install pyinstaller
pyinstaller iOSBackupManager-macos.spec

Output: dist/iOSBackupManager.app

Linux:

pip3 install pyinstaller
pyinstaller iOSBackupManager-linux.spec

Output: dist/iOSBackupManager

Or use the automated build scripts:

• Windows: build-windows.bat
• macOS: ./build-macos.sh
• Linux: ./build-linux.sh

---

Usage

GUI Mode (Recommended)

1. Launch the Application

   • Windows: Double-click iOSBackupManager.exe
   • macOS: Open iOSBackupManager.app
   • Linux: Run ./iOSBackupManager
   • From source: python backup_merger_gui.py

2. Load Backups

   • Click "Browse" or drag-and-drop backup folders into the left/right panels
   • Or connect an iOS device to create a new backup
   • Default backup locations:
     • Windows: %APPDATA%\Apple Computer\MobileSync\Backup\
     • macOS: ~/Library/Application Support/MobileSync/Backup/
     • Linux: ~/.local/share/MobileSync/Backup/

3. Preview Data (Optional)

   • Click on blue category names (Photos & Media, SMS, Contacts) to preview data
   • Search, browse, and select specific items to export
   • Preview windows are non-blocking - you can open multiple previews

4. Extract All Data

   • Click "Extract All Data" to export everything
   • Choose output directory and options
   • Continue working in main window while extraction runs in background
   • View progress in the extraction dialog

5. Configure Merge Settings

   • Select which categories to include from each backup
   • Choose conflict resolution strategy (prefer left/right)
   • Specify which backup's settings to use for the new device

6. Merge Backups

   • Click "Merge Backups"
   • Choose output directory
   • Wait for merge to complete

7. Export Individual Categories (Alternative)

   • Preview any category
   • Select items to export (or export all)
   • Choose export location
   • Data is exported in standard formats (HTML, VCF, ICS, etc.)

Command Line Mode

For automated workflows or batch processing:

python merge_backups.py \
  --recovered "path/to/first/backup" \
  --customer "path/to/second/backup" \
  --out "path/to/output" \
  --prefer recovered \
  --new-device customer \
  --photos-mode merge \
  --sms-mode merge \
  --contacts-mode merge

Available Options:

• --recovered - Path to first backup
• --customer - Path to second backup
• --out - Output directory for merged backup
• --prefer - Which backup to prefer for conflicts (recovered or customer)
• --new-device - Which backup's device identity to use (recovered or customer)
• --photos-mode - Photo merge strategy: merge, recovered, customer, or skip
• --sms-mode - SMS merge strategy: merge, recovered, customer, or skip
• --contacts-mode - Contacts merge strategy: merge, recovered, customer, or skip
• --calendar-mode - Calendar merge strategy: merge, recovered, customer, or skip
• --notes-mode - Notes merge strategy: merge, recovered, customer, or skip
• --call-history-mode - Call history merge strategy: merge, recovered, customer, or skip
• --voicemail-mode - Voicemail merge strategy: merge, recovered, customer, or skip
• --voice-memos-mode - Voice memos merge strategy: merge, recovered, customer, or skip

---

Project Structure

iOSBackupManager/
├── backup_merger_gui.py           # Main GUI application
├── merge_backups.py                # CLI merge utility
├── requirements.txt                # Python dependencies
├── BUILD_GUIDE.md                  # Comprehensive build instructions
│
├── platform_utils.py               # Cross-platform utilities
├── file_manager.py                 # File manager integration
├── device_detection.py             # Device detection abstraction
│
├── iOSBackupManager-windows.spec   # Windows build configuration
├── iOSBackupManager-macos.spec     # macOS build configuration
├── iOSBackupManager-linux.spec     # Linux build configuration
│
├── build-windows.bat               # Windows build script
├── build-macos.sh                  # macOS build script
├── build-linux.sh                  # Linux build script
│
├── extractors/                     # Data extraction modules
│   ├── base.py                     # Base extractor class
│   ├── contacts_extractor.py       # Contacts data extraction
│   ├── photos_extractor.py         # Photos/media extraction
│   ├── sms_extractor.py            # SMS/iMessage extraction
│   ├── calendar_extractor.py       # Calendar extraction
│   ├── notes_extractor.py          # Notes extraction
│   ├── call_history_extractor.py   # Call history extraction
│   ├── voicemail_extractor.py      # Voicemail extraction
│   └── voice_memos_extractor.py    # Voice memos extraction
│
├── preview_windows/                # Preview UI windows
│   ├── base.py                     # Base preview window
│   ├── contacts_preview.py         # Contacts preview
│   ├── photos_preview.py           # Photos preview
│   └── sms_preview.py              # SMS preview
│
├── full_extraction_dialogs.py      # Full extraction UI
│
├── mergers/                        # Data merging modules
│   ├── db_merger_base.py           # Base merger class
│   ├── contacts_merger.py          # Contacts merger
│   ├── photos_merger.py            # Photos merger
│   ├── sms_merger.py               # SMS merger
│   ├── calendar_merger.py          # Calendar merger
│   └── notes_merger.py             # Notes merger
│
└── resources/                      # UI assets
    ├── iPhoneFrame.png            # iPhone frame
    ├── iPadFrame.png              # iPad frame
    ├── connect_guide.png          # Connection guide
    ├── trust_guide.png            # Trust guide
    ├── findmy_guide.png           # Find My guide
    └── activation_guide.png       # Activation guide

---

Platform-Specific Features

Windows

• ✅ Real-time WMI device detection (instant notification)
• ✅ Windows Explorer integration ("Open in Explorer", "Select in Explorer")
• ✅ No console window (pure GUI application)
• ✅ Single executable file (~92 MB)

macOS

• ✅ Native .app bundle
• ✅ Finder integration ("Open in Finder", "Reveal in Finder")
• ✅ Polling-based device detection (2-second interval)
• ✅ macOS-style keyboard shortcuts

Linux

• ✅ Standalone executable
• ✅ File manager integration (xdg-open, nautilus, dolphin, etc.)
• ✅ Polling-based device detection (2-second interval)
• ✅ Works on major distributions (Ubuntu, Fedora, Debian, Arch)

---

Common Use Cases

1. Recover Data from Corrupted Backup

If you have a corrupted backup but want to extract specific data:

1. Open the GUI
2. Load the corrupted backup
3. Click on any blue category name to preview
4. Export the data you need

2. Merge Two Partial Backups

If you have two backups from the same device at different times:

1. Load both backups (left and right panels)
2. Select which categories to include from each
3. Choose conflict resolution (usually "prefer" the newer backup)
4. Click "Merge Backups"

3. Extract Messages for Legal/Forensic Purposes

1. Load the backup
2. Click "SMS" to open the preview
3. Search for specific contacts or keywords
4. Select conversations to export
5. Export as HTML (automatically splits large conversations)

4. Consolidate Multiple Devices

If you're consolidating data from two different devices:

1. Load both backups
2. Select which data categories to merge
3. Choose which device identity to use
4. Merge into a new backup

5. Process Multiple Backups Simultaneously

With non-modal extraction dialogs:

1. Start "Extract All Data" on first backup
2. Browse and load second backup while first extraction runs
3. Start extraction on second backup
4. All extractions run in parallel (to different output folders)

---

Troubleshooting

Common Issues

Problem: "Manifest.db not found"

• Solution: Ensure you're selecting the root backup folder (contains Manifest.db file)

Problem: "No preview available" for encrypted backups

• Solution: iOS Backup Manager works with unencrypted backups only. Decrypt backups using iTunes first.

Problem: Wallpaper not showing

• Solution: Install Pillow: pip install Pillow pillow-heif

Problem: Can't detect connected device

• Windows: Ensure device is unlocked and trusted, iTunes or Apple Mobile Device Support installed
• macOS: Install/update iTunes or Apple Mobile Device Support
• Linux: Install usbmuxd: sudo apt-get install usbmuxd (or equivalent for your distro)

Problem: Drag-and-drop not working

• Solution: Install tkinterdnd2: pip install tkinterdnd2

Problem: Export fails with large conversations

• Solution: Conversations are automatically split every 10,000 messages. Try exporting smaller selections.

Problem: Main window unresponsive during extraction

• Solution: This was fixed in v2.0! Update to latest version for non-modal extraction dialogs.

Platform-Specific Issues

Windows:

• WMI not available: Device detection falls back to polling (2-second interval)

macOS:

• "App is damaged" on first run: Right-click → Open (instead of double-clicking)
• Or run: xattr -cr iOSBackupManager.app

Linux:

• File manager doesn't open: Install xdg-utils: sudo apt-get install xdg-utils
• Device not detected: Ensure usbmuxd service is running: sudo systemctl start usbmuxd

---

Performance Notes

• Large Databases: The tool efficiently handles backups with 100,000+ messages and 10,000+ photos
• Export Speed: First export may be slower; subsequent exports use caching for 40-60% speed improvement
• Memory Usage: Preview windows load data in pages (100 items at a time) to minimize memory usage
• HTML Export: Large conversations are automatically split into multiple files to prevent browser crashes
• Parallel Operations: Extract multiple backups simultaneously (to different output folders)
• Background Processing: All long-running operations run in background threads to keep UI responsive

---

Contributing

Contributions are welcome! Please feel free to submit pull requests or open issues for bugs and feature requests.

Development Setup

1. Fork the repository
2. Create a feature branch (git checkout -b feature/amazing-feature)
3. Make your changes
4. Test thoroughly on target platforms
5. Update BUILD_GUIDE.md if build process changes
6. Commit your changes (git commit -m 'Add amazing feature')
7. Push to the branch (git push origin feature/amazing-feature)
8. Open a Pull Request

Testing Cross-Platform Changes

• Windows: Test locally
• macOS: Test on Mac system or use CI/CD
• Linux: Test on Linux VM or use CI/CD

---

Build System

This project includes a comprehensive cross-platform build system:

• Platform-specific PyInstaller configs: Optimized for each OS
• Automated build scripts: One-command builds
• Comprehensive documentation: See BUILD_GUIDE.md

Quick Build:

• Windows: build-windows.bat or pyinstaller iOSBackupManager-windows.spec
• macOS: ./build-macos.sh or pyinstaller iOSBackupManager-macos.spec
• Linux: ./build-linux.sh or pyinstaller iOSBackupManager-linux.spec

---

License

MIT License - See LICENSE file for details

---

Acknowledgments

• pymobiledevice3 - iOS device communication library
• Pillow - Image processing library
• pillow-heif - HEIF/HEIC image support
• tkinterdnd2 - Drag-and-drop support for Tkinter
• imageio-ffmpeg - Video and audio processing
• PyInstaller - Cross-platform executable creation

---

Disclaimer

This tool is designed for legitimate data recovery and backup management purposes. Users are responsible for ensuring they have proper authorization to access and merge backup data. The authors assume no liability for misuse of this software.

---

Support

For issues, questions, or feature requests, please open an issue on the GitHub Issues page.

For build-related questions, see BUILD_GUIDE.md.

---

Changelog

Version 2.0 (December 2025)

• Added full cross-platform support (Windows, macOS, Linux)
• Implemented platform abstraction layer
• Added non-modal extraction dialogs for better UX
• Created automated build system for all platforms
• Enhanced device detection with platform-specific optimizations
• Improved file manager integration for all platforms
• Added comprehensive BUILD_GUIDE.md documentation

Version 1.x (Previous)

• Initial Windows-only release
• Core backup merging and extraction functionality
• Preview windows for photos, SMS, and contacts
• Device detection and backup creation
• HTML export for conversations
• Wallpaper preview support

---

Star ⭐ this repository if you find it helpful!