A command-line tool designed specifically to download and manage ROMs from public archives, with features like smart searching, filtering, and automatic extraction of compressed files.

• Overview
• Installation
• Quick Start
• Command Reference
• Advanced Usage
• Configuration
• Supported Platforms
• Performance Optimization
• Troubleshooting

Retro Game Package Manager is a tool that simplifies the management of retro game collections. It features intelligent search algorithms, multi-threaded downloads, automatic archive extraction, and advanced duplicate management capabilities.

• High-Performance Downloads: Multi-threaded architecture with configurable worker pools
• Intelligent Search: Advanced filtering with system-specific queries and exclusion patterns
• Archive Management: Automatic extraction for ZIP, 7Z, TAR.XZ, and RAR formats
• Space Optimization: CHD compression support for significant storage savings
• Duplicate Resolution: Smart duplicate detection with region-based prioritization
• Cross-Platform: Native support for Windows, macOS, and Linux
• Configuration Management: Centralized settings with JSON-based configuration

Install core Python dependencies:

pip install requests tqdm beautifulsoup4 py7zr rarfile

For advanced compression capabilities, install MAME tools:

Ubuntu/Debian:

sudo apt update
sudo apt install mame-tools

macOS (Homebrew):

brew install rom-tools

Windows: Download MAME tools from the official Recalbox website

Ubuntu/Debian:

sudo apt install unrar-free p7zip-full

macOS:

brew install unrar p7zip

pip install .

Verify installation:

retro --version

1. Initialize Configuration

   retro update

2. Search Available Games

   retro search mario

3. Install Games

   retro install sonic genesis

4. Manage Your Collection

   retro list

Synchronizes the local game database with remote repositories.

Usage:

retro update

Process:

• Fetches system definitions from configured repositories
• Downloads and parses directory listings
• Updates local package cache
• Displays system statistics

Output:

Listing systems...
✓ 208.08GB [Panasonic 3DO] (666)
✓ 3.30GB [Commodore Amiga] (3169)
✓ 1.2TB [PlayStation] (8,234)
✗ 0.00B [Atari 2600] (0)

Installs games matching specified search criteria.

Usage:

retro install <search_terms>

Search Patterns:

• Name-based: retro install mario
• System-specific: retro install mario nes
• Bulk installation: retro install all gbc
• Exclusion filtering: retro install mario -demo -beta

Interactive Process:

[genesis] 145.75MB (71)
  (1.00MB) Sonic The Hedgehog (USA, Europe)
  (2.00MB) Sonic The Hedgehog 2 (World)
  (4.00MB) Sonic 3D Blast (USA, Europe, Korea) (En)

Total: 145.75MB (71 packages)
Do you want to continue? [Y/n]: y

Installing: ⋯18 ↓4 ⚙2 ✓27 ✗0: 75%
✓ 27 installed, ✗ 0 failed

Removes installed games matching specified criteria.

Usage:

retro remove <search_terms>

Examples:

retro remove mario           # Remove all Mario games
retro remove all psx         # Remove all PlayStation games
retro remove sonic -beta     # Remove Sonic games, keep betas

Displays comprehensive information about installed games.

Usage:

retro list

Output Format:

[genesis] 70.00MB (33)
  (1.00MB) Aerobiz Supersonic (USA).md
  (2.00MB) Sonic & Knuckles (World).md
  (512.00KB) Sonic The Hedgehog (USA, Europe).md

[psx] 627.79MB (3)
  (266.21MB) Rampage - Through Time (Europe) (En,Fr,De).chd
  (136.74MB) Rampage - World Tour (Europe).chd

74 games from 2 systems, 773.54MB used.

Searches available games without installation.

Usage:

retro search <search_terms>

Advanced Search:

retro search zelda           # Basic name search
retro search zelda nes        # System-specific search
retro search all snes         # Complete system listing
retro search mario -demo      # Exclusion-based search

Output with Installation Status:

[genesis] 145.75MB (71) (5 installed)
  (1.00MB) Sonic The Hedgehog (USA, Europe)
  (2.00MB) Sonic The Hedgehog 2 (World) [installed]
  (4.00MB) Sonic 3D Blast (USA, Europe, Korea) (En)

Converts ROM files to CHD format for space optimization.

Usage:

retro compress

Compression Process:

The following files will be compressed:
  [psx] (266.21MB) Rampage - Through Time (Europe) (En,Fr,De).iso
    → Create: Rampage - Through Time (Europe) (En,Fr,De).chd
    → Delete: Rampage - Time (Europe) (En,Fr,De).iso
    → Delete: Rampage - Time (Europe) (En,Fr,De).bin

Do you want to continue? [Y/n]: y

Compressing: ⋯0 ⚙1 ✓0 ✗0: 100%
✓ 1 compressed, ✗ 0 failed

Intelligently removes duplicate ROMs based on quality metrics.

Usage:

retro autoremove

Duplicate Resolution:

The following duplicate games will be processed:
Sonic The Hedgehog:
  [genesis] (512.00KB) Sonic The Hedgehog (USA, Europe).md
    → Keep: Best version
  [genesis] (512.00KB) Sonic The Hedgehog (Japan).md
    → Delete: Duplicate

Do you want to continue? [Y/n]: y
✓ 1 duplicates removed

• Exact match: retro search "Super Mario Bros"
• Partial match: retro search mario
• System filter: retro search mario nes
• Complete system: retro search all snes

• Single exclusion: retro search mario -demo
• Multiple exclusions: retro search sonic -beta -prototype -hack
• Complex filtering: retro search zelda nes -demo -beta

The autoremove command prioritizes ROMs in this order:

1. World (W) - International releases
2. Europe (E) - European releases
3. USA (U) - North American releases
4. Japan (J) - Japanese releases

Adjust worker counts in ~/.config/retro/settings.json:

{
  "fetch_workers": 15,      # Increase for faster updates
  "install_workers": 30,     # Increase for faster downloads
  "convert_workers": 8,      # Increase for faster CHD conversion
  "compress_workers": 8      # Increase for faster compression
}

• Use wired connections for large downloads
• Configure proxy settings if needed
• Monitor bandwidth usage during bulk operations

Configuration is stored in ~/.config/retro/settings.json:

{
  "roms_dir": "~/roms",
  "fetch_workers": 10,
  "install_workers": 20,
  "convert_workers": 4,
  "compress_workers": 4
}

System configurations are stored in ~/.config/retro/systems.json:

{
  "genesis": {
    "name": "Sega Genesis",
    "format": ["md", "smd", "bin"],
    "url": [
      "https://archive.org/download/redump-sega-genesis-mega-drive/"
    ]
  },
  "psx": {
    "name": "Sony PlayStation",
    "format": ["bin", "cue", "chd"],
    "url": [
      "https://archive.org/download/redump-sony-playstation/"
    ]
  }
}

~/.config/retro/
├── systems.json      # System definitions and repository URLs
├── packages.json     # Cached game database
└── settings.json     # User preferences and configuration

~/roms/               # Primary ROM storage (configurable)
├── genesis/          # Sega Genesis games
├── psx/              # PlayStation games
├── nes/              # Nintendo Entertainment System games
├── snes/             # Super Nintendo games
└── ...               # Additional system directories

Network Settings:

• Use wired connections for stability
• Configure appropriate worker counts based on bandwidth
• Monitor system resources during bulk operations

Storage Optimization:

• Use CHD compression for disc-based games
• Implement regular duplicate cleanup
• Consider SSD storage for frequently accessed games

Memory Usage:

• Monitor RAM usage during large downloads
• Adjust worker counts based on available memory
• Close unnecessary applications during bulk operations

CPU Utilization:

• Balance worker counts with CPU cores
• Use compression during off-peak hours
• Monitor system temperature during intensive operations

"No package data found" error:

retro update

Permission denied errors:

# Ensure write permissions to ROMs directory
chmod 755 ~/roms
# Ensure write permissions to config directory
chmod 755 ~/.config/retro

"chdman not found" error: Install MAME tools as described in the Installation section.

Network timeouts:

• Check internet connection stability
• Reduce worker counts in settings.json
• Verify repository accessibility

Incomplete downloads:

• Enable download verification in settings
• Check available disk space
• Verify write permissions

Slow downloads:

• Increase install_workers in settings.json
• Check network bandwidth limitations
• Verify repository server performance

High CPU usage:

• Decrease worker counts in settings.json
• Close resource-intensive applications
• Monitor system temperature

Disk space issues:

• Use retro compress for space optimization
• Remove unwanted games with retro remove
• Consider external storage solutions

This tool is designed to help manage ROMs for games you legally own. Please ensure you only download games that you have purchased or that are in the public domain. The developers of this tool do not condone piracy and are not responsible for any illegal use of this software.

Important: Always respect copyright laws and only download games you legally own. This tool is provided for educational and preservation purposes only.