Metadata-Version: 2.4
Name: iOS-backup-manager
Version: 2.9.0a8
Summary: iOS Backup Manager CLI and Windows GUI
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: Pillow>=10.0.0
Requires-Dist: pillow-heif>=0.13.0
Requires-Dist: imageio-ffmpeg>=0.4.9
Requires-Dist: pymobiledevice3>=2.0.0
Requires-Dist: pydantic>=2.0.0
Requires-Dist: protobuf>=4.0.0
Requires-Dist: iphone_backup_decrypt>=0.9.0
Requires-Dist: pycryptodome>=3.18.0
Provides-Extra: gui
Requires-Dist: tkinterdnd2>=0.3.0; extra == "gui"
Requires-Dist: wmi>=1.5.1; platform_system == "Windows" and extra == "gui"
Requires-Dist: pywin32>=306; platform_system == "Windows" and extra == "gui"
Dynamic: license-file

# 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.9 - Cross-Platform Support (January 2026)
- ✅ **Full Windows, macOS CLI, and Linux CLI 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
- ✅ **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
iOS Backup Manager GUI
<img width="1627" height="885" alt="iOSBackupManagerScreenshot" src="https://github.com/user-attachments/assets/150415ac-cf11-44e5-b2b6-9ea0bddefe38" />
<img width="1619" height="875" alt="Screenshot 2025-12-11 125606" src="https://github.com/user-attachments/assets/19cf9f2c-b66e-4639-8aaf-1c654b67af6f" />
<img width="1620" height="884" alt="Screenshot 2025-12-11 131847" src="https://github.com/user-attachments/assets/b4e11982-5e2a-463a-9598-87e9ba71420a" />
iOS Backup Manager Reports
<img width="1063" height="1013" alt="chrome_lmeGVepSCU" src="https://github.com/user-attachments/assets/dfe121db-dda9-40e2-ac2a-127f8b5febd4" />
<img width="1063" height="1013" alt="chrome_nItvVLpBvd" src="https://github.com/user-attachments/assets/2f0a7d03-4bfb-465c-b9dc-b40b53df3ede" />
<img width="1063" height="1013" alt="eFgowhDtUK" src="https://github.com/user-attachments/assets/0d431768-5388-4010-9499-b6b78498b33f" />
<img width="1063" height="1013" alt="chrome_oeDIyNvPh7" src="https://github.com/user-attachments/assets/0aa0a658-0985-419a-85f1-1ce4a92d1489" />
<img width="1063" height="1013" alt="chrome_HzB5VM3zPk" src="https://github.com/user-attachments/assets/2adcc2ec-2de8-4456-85ac-3c3a6b41c87f" />
<img width="1063" height="1013" alt="chrome_ObtCD1F70a" src="https://github.com/user-attachments/assets/a1a88595-f1ea-4fdf-93ef-97a518b0b04b" />
<img width="1063" height="1013" alt="chrome_w36oamGGsc" src="https://github.com/user-attachments/assets/25674e35-d591-428f-81d9-dcc6bcea2065" />
<img width="1063" height="1013" alt="WindowsTerminal_ckpfHUoSdx" src="https://github.com/user-attachments/assets/026a9bd5-1bd0-4571-b204-1eb3ad85e55b" />
<img width="1063" height="1013" alt="WindowsTerminal_5xk42bJO6F" src="https://github.com/user-attachments/assets/b2aec57a-553a-4dd7-9e78-ae98a65092c7" />
<img width="1063" height="1013" alt="WindowsTerminal_rCddEryht9" src="https://github.com/user-attachments/assets/36da2120-7c3c-42e6-8f0d-eb7abbde6e12" />
<img width="1063" height="1013" alt="CO1fWDrlqL" src="https://github.com/user-attachments/assets/a715435e-6836-48a7-b2d3-4b766b2ae1d8" />
<img width="1063" height="1013" alt="chrome_KPy4KFY0YK" src="https://github.com/user-attachments/assets/5be1cd4a-321c-4495-be3e-b28e90428d21" />
iOS Backup Manager Reports - Device View
<img width="1063" height="1013" alt="chrome_KPy4KFY0YK" src="https://github.com/user-attachments/assets/cea7f9d7-623b-4a28-ba74-346870790b8e" />





---

## 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

CLI commands:
```bash
iosbackup --help
iosbackup menu
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) or just normal pip (but you'll have to manually add paths)** 
```bash
python -m pip install --user pipx
python -m pipx ensurepath
pipx install ios-backup-manager
```
Then open a new shell and run:
```bash
iosbackup
or
iosbackup-gui #for windows gui
```
The most common entry point is the interactive menu, run
```bash
iosbackup menu
```
This should be enough for most people to get started with the CLI

**Option 2: Use a virtual environment**
```bash
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)**
```bash
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):
```bash
iosbackup-gui

### Option 1: Download Pre-Built Executable (Easiest)

**Windows:**
1. Download `iOSBackupManager.exe` from [Releases](https://github.com/mcampetta/iOSBackupManager/releases)
2. Run the executable - no installation required!

### Option 2: Run from Source (Recommended for Development)

1. **Clone the Repository**
   ```bash
   # If this github is still in development and private use the second command (private link) to clone the repo instead.
   git clone https://github.com/mcampetta/iOSBackupManager.git # If Public
   git clone https://mcampetta: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@github.com/mcampetta/iOSBackupManager.git # If Private
   ```
   
### Option 3: Build from Source

See [BUILD_GUIDE.md](BUILD_GUIDE.md) for comprehensive build instructions for all platforms.

**Quick Build Instructions:**

**Windows:**
```cmd
pip install pyinstaller
pyinstaller iOSBackupManager-windows.spec
```
Output: `dist\iOSBackupManager.exe`

**macOS:**
```bash
pip3 install pyinstaller
pyinstaller iOSBackupManager-macos.spec
```
Output: `dist/iOSBackupManager.app`

**Linux:**
```bash
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`
   - 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
  The CLI is available after installing the package:

  python -m pip install ios-backup-manager

  Once installed, use the iosbackup command.

  ### Quick Start

  # Show available commands
  ```
  iosbackup --help
  ```
  # List categories available in a backup
  ```
  iosbackup list-categories --backup "C:\Path\To\Backup" --password "your_password"
  ```

  # Extract all categories to an output folder
  ```
  iosbackup extract --backup "C:\Path\To\Backup" --output "C:\Output\Folder" --password "your_password"
  ```

  # Extract a single category
  ```
  iosbackup extract --backup "C:\Path\To\Backup" --output "C:\Output\Folder" --categories health_fitness
  --password "your_password"
  ```

  ### Common Options

  - --backup Path to the iTunes/Finder backup folder (UDID folder)
  - --output Folder where extracted data and reports will be written
  - --categories Comma‑separated list of category IDs (use list-categories to discover)
  - --password Password for encrypted backups
  - --parallel / --no-parallel Enable or disable parallel extraction (default: parallel)
  - --no-master-report Skip the Start_Here report
  - --summary Generate extraction summary text
  - --timezone Set timezone label in reports (default: UTC)

  ### Examples

  # Extract only messages and notes
  ```
  iosbackup extract ^
    --backup "D:\Backups\00008110-001C4C5A3A88201E" ^
    --output "D:\Case\Extracted" ^
    --categories sms,notes ^
    --password "example123"
  ```

  # Extract everything without master report
  ```
  iosbackup extract ^
    --backup "D:\Backups\00008110-001C4C5A3A88201E" ^
    --output "D:\Case\Extracted" ^
    --categories all ^
    --no-master-report ^
    --password "example123"
  ```

  # List backups under a root (max depth 4)
  ```
  iosbackup list-backups --root "D:\Backups" --max-depth 4
  ```

  ### Notes

  - Encrypted backups require the correct password.
  - Category output is placed under subfolders by default (e.g., Health & Fitness/Health_Fitness.html).
  - Use list-categories to verify availability for a specific backup before extraction.

## 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](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

Non-Commercial - 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](https://github.com/mcampetta/iOSBackupManager/issues) page.

For build-related questions, see [BUILD_GUIDE.md](BUILD_GUIDE.md).

---

## Changelog

### Version 2.0 (December 2025)
- Added full cross-platform support (Windows, macOS (CLI Only), Linux (CLI Only) )
- 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

---

## Commercial Use
If you are a company or service provider and wish to use iOS Backup Manager
commercially, please see `COMMERCIAL-LICENSING.md`.

**Star ⭐ this repository if you find it helpful!**
