Skip to main content

Modrinth Auto Updater

The Modrinth Auto Updater is a Python application designed to automate the process of updating Minecraft modpacks using the Modrinth API. It handles version compatibility, modloader filtering, and generates both client and server modpack files in the Modrinth Pack (.mrpack) format.

Overview​

Managing Minecraft modpacks involves tracking numerous mods, each with their own version requirements and compatibility constraints. The Modrinth Auto Updater simplifies this process by:

  • Automatically checking for compatible mod updates
  • Respecting Minecraft version requirements
  • Handling modloader compatibility (Fabric, Quilt, Forge, NeoForge)
  • Generating separate client and server packs
  • Creating comprehensive changelogs
  • Backing up existing mod files

Core Features​

GUI Interface​

The application provides a graphical user interface built with Tkinter, featuring:

Modern Theme​

The interface uses a dark theme optimized for extended use, reducing eye strain during lengthy update operations. The color scheme follows modern design principles with careful contrast ratios.

Configuration Panel​

All update parameters are accessible through an intuitive configuration panel:

  • Modpack directory selection with file browser
  • Minecraft version selector
  • Modloader type dropdown (Fabric, Quilt, Forge, NeoForge)
  • Client/server pack generation toggles
  • Output directory configuration
  • Overrides folder path

Real-Time Output​

The console area displays:

  • Color-coded log messages (success in green, warnings in yellow, errors in red)
  • Progress indicators for long-running operations
  • Detailed information about each mod being processed
  • API response details for debugging

Cross-Platform Support​

The GUI works consistently across:

  • Windows (native look and feel)
  • macOS (respects system theme settings)
  • Linux (GTK compatibility)

Mod Update System​

Modrinth API Integration​

The updater communicates with the Modrinth API v2 to:

  • Query mod information and version history
  • Filter versions by game version compatibility
  • Check modloader requirements
  • Download mod files
  • Retrieve mod metadata

Version Compatibility​

The system performs sophisticated version matching:

Exact Version Matching

When Minecraft 1.21.1 is specified, it matches:

  • Versions tagged for 1.21.1 specifically
  • Versions supporting 1.21.x ranges
  • Versions with inclusive ranges containing 1.21.1

Sub-Version Support

The updater understands Minecraft's version numbering:

  • 1.21.1 is considered part of the 1.21 family
  • 1.20.4 is part of the 1.20 family
  • This allows "works with 1.21" to match "1.21.1" installations

Version Range Interpretation

Handles complex version specifications:

  • Single versions: 1.21.1
  • Ranges: >=1.20.0 <1.22.0
  • Multiple versions: [1.20.4, 1.21.0, 1.21.1]
  • Wildcard patterns: 1.21.x

Modloader Compatibility​

Different modloaders have compatibility relationships:

Fabric and Quilt

Quilt mods can use Fabric mods, but not vice versa. When using Quilt:

  • Quilt-specific mods are preferred
  • Fabric mods are acceptable fallbacks
  • Both are checked for updates

Forge and NeoForge

These are treated as separate ecosystems:

  • Forge mods only work with Forge
  • NeoForge mods only work with NeoForge
  • No cross-compatibility

Loader Detection

The system automatically detects the modloader from:

  • Index.json in the modpack
  • Existing mod files
  • User configuration

Update Process​

Discovery Phase​

The updater begins by:

  1. Parsing the modpack's index.json file
  2. Extracting mod project IDs and current versions
  3. Building a list of installed mods

Version Checking​

For each mod:

  1. Query Modrinth API for available versions
  2. Filter by Minecraft version compatibility
  3. Filter by modloader requirements
  4. Identify the latest compatible version
  5. Compare with currently installed version

Download and Installation​

When updates are found:

  1. Download new mod file to temporary location
  2. Verify file integrity (checksum)
  3. Backup existing mod file to backup directory
  4. Move new file into place
  5. Update index.json with new version information

Error Handling​

The system gracefully handles:

  • Network failures (retries with exponential backoff)
  • API rate limiting (respects rate limit headers)
  • File system errors (permission issues, disk full)
  • Corrupted downloads (checksum verification)
  • Missing dependencies (warns but continues)

Client/Server Pack Generation​

Pack Structure​

Generated .mrpack files follow the Modrinth specification:

modpack.mrpack (zip file)
├── modrinth.index.json    # Mod list and metadata
└── overrides/             # Custom files
    ├── config/            # Configuration files
    ├── resourcepacks/     # Resource packs
    └── ...                # Other custom content

Client Pack Generation​

Client packs include:

  • All client-side mods
  • Client-and-server mods
  • Client-only resource packs
  • Client configuration files

Environment tags are set appropriately:

  • client: Client-only mods
  • both: Works on client and server

Server Pack Generation​

Server packs filter for:

  • Server-side mods only
  • Server-and-client mods
  • Server configuration files

Client-only mods are excluded:

  • Minimap mods
  • Shader mods
  • Client-side performance mods
  • Audio enhancement mods

Environment Detection​

The system analyzes mod metadata to determine environment compatibility:

  • Checks Modrinth mod environment tags
  • Examines mod capabilities
  • Respects manual overrides in configuration

Overrides Folder​

Custom content in the overrides folder is included in generated packs:

  • Config files for mods
  • Custom resource packs
  • Custom data packs
  • World generation configurations
  • Custom scripts

Reporting System​

Terminal Output​

The console displays color-coded information:

[✓] Updated mod_name from 1.0.0 to 1.1.0
[!] No update found for stable_mod (current: 2.0.0)
[✗] Failed to check another_mod: API timeout

Colors:

  • Green: Successful operations
  • Yellow: Warnings or no updates available
  • Red: Errors or failures

Changelog Generation​

A Markdown changelog is generated with:

Summary Statistics

# Modpack Update - 2026-02-07

- Total mods checked: 150
- Mods updated: 23
- Mods unchanged: 125
- Errors: 2

Detailed Update List

For each updated mod:

## Updates

### Mod Name
- **Old Version**: 1.0.0 → **New Version**: 1.1.0
- **Changelog**: 
  - Fixed crash with X feature
  - Added support for Y
  - Performance improvements

Error Report

Lists any mods that couldn't be updated with reasons:

## Errors

### Failed Mod
- **Error**: Connection timeout after 30 seconds
- **Action**: Retry later or check manually

Update Summary​

The final summary displays:

  • Time taken for the update process
  • Bandwidth used for downloads
  • Number of files backed up
  • Success rate percentage

Installation and Setup​

System Requirements​

  • Python 3.8 or higher
  • Internet connection for API access
  • Sufficient disk space for backups and downloads

Installation Process​

Automated Setup​

Windows​
setup.bat

This script:

  • Creates a virtual environment
  • Installs dependencies
  • Sets up desktop shortcuts
  • Configures file associations
Linux/macOS​
chmod +x setup.sh
./setup.sh

This script:

  • Checks Python version
  • Creates virtual environment
  • Installs dependencies
  • Sets up launcher scripts

Manual Installation​

For more control over the setup:

python -m venv venv

# Activate virtual environment
# Windows:
venv\Scripts\activate
# Linux/macOS:
source venv/bin/activate

# Install dependencies
pip install -r requirements.txt

Dependencies​

The application requires these Python packages:

  • requests: HTTP library for API communication
  • tkinter: GUI framework (usually included with Python)
  • typing-extensions: Type hint support for older Python versions

All dependencies are listed in requirements.txt with pinned versions for reproducibility.

Usage Modes​

GUI Mode​

Launching the GUI​

Multiple methods available:

# Universal launcher (auto-detects best mode)
python launcher.py

# Explicit GUI launch
python launcher.py --gui

# Direct GUI script
python run_gui.py

# Platform-specific launchers
./run_gui.sh        # Linux/macOS
run_gui.bat         # Windows

GUI Workflow​

  1. Select Modpack: Browse to your modpack directory or .mrpack file
  2. Configure Settings: Set Minecraft version, modloader type
  3. Choose Outputs: Enable client/server pack generation if needed
  4. Start Update: Click the update button
  5. Monitor Progress: Watch real-time console output
  6. Review Results: Check the changelog and summary

GUI Features​

  • Live Console: Real-time updates during processing
  • Scrollable Output: Review long log histories
  • Copy Support: Select and copy log messages
  • Status Bar: Shows current operation and progress
  • Cancel Button: Stop long-running operations

Command Line Mode​

For automation, scripting, or server environments:

Basic Update​

python update_modpack.py --modpack-dir /path/to/modpack

Generate Client Pack​

python update_modpack.py \
  --modpack-dir /path/to/modpack \
  --client

Generate Server Pack​

python update_modpack.py \
  --modpack-dir /path/to/modpack \
  --server

Custom Overrides​

python update_modpack.py \
  --modpack-dir /path/to/modpack \
  --overrides-folder custom_files \
  --client \
  --server

Command Line Options​

  • --modpack-dir: Path to modpack folder or .mrpack file (required)
  • --client: Generate client .mrpack file
  • --server: Generate server .mrpack file
  • --overrides-folder: Folder with custom files to include (default: overrides)

Automated Mode​

For scheduled updates or CI/CD integration:

Cron Job Example (Linux)​

# Update modpack daily at 3 AM
0 3 * * * /path/to/venv/bin/python /path/to/update_modpack.py --modpack-dir /path/to/modpack >> /var/log/modpack-update.log 2>&1

Windows Task Scheduler​

Create a scheduled task that runs:

"C:\Path\To\venv\Scripts\python.exe" "C:\Path\To\update_modpack.py" --modpack-dir "C:\Path\To\Modpack"

CI/CD Integration​

GitHub Actions example:

name: Update Modpack
on:
  schedule:
    - cron: '0 0 * * 0'  # Weekly on Sunday
  workflow_dispatch:

jobs:
  update:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v2
      - name: Set up Python
        uses: actions/setup-python@v2
        with:
          python-version: '3.8'
      - name: Install dependencies
        run: pip install -r requirements.txt
      - name: Update modpack
        run: python update_modpack.py --modpack-dir ./modpack --client --server
      - name: Commit changes
        run: |
          git config user.name "Bot"
          git config user.email "bot@example.com"
          git add .
          git commit -m "Update mods" || echo "No changes"
          git push

Configuration​

Modpack Structure​

The updater expects this structure:

modpack/
├── modrinth.index.json    # Mod definitions
├── overrides/             # Custom files
│   ├── config/
│   ├── resourcepacks/
│   └── ...
└── mods/                  # Downloaded mod files (auto-managed)

Index.json Format​

The modrinth.index.json file contains:

{
  "formatVersion": 1,
  "game": "minecraft",
  "versionId": "1.0.0",
  "name": "My Modpack",
  "summary": "An awesome modpack",
  "files": [
    {
      "path": "mods/example-mod-1.0.0.jar",
      "hashes": {
        "sha512": "abc123...",
        "sha1": "def456..."
      },
      "env": {
        "client": "required",
        "server": "required"
      },
      "downloads": [
        "https://cdn.modrinth.com/data/PROJECT_ID/versions/VERSION_ID/example-mod-1.0.0.jar"
      ],
      "fileSize": 1048576
    }
  ],
  "dependencies": {
    "minecraft": "1.21.1",
    "fabric-loader": "0.15.0"
  }
}

Environment Variables​

Optionally configure via environment variables:

  • MODRINTH_API_KEY: API key for higher rate limits (optional)
  • MODPACK_DIR: Default modpack directory
  • DOWNLOAD_THREADS: Number of concurrent downloads (default: 5)

Advanced Features​

Backup Management​

Automatic Backups​

Before updating, mods are backed up to:

modpack/backups/YYYY-MM-DD_HH-MM-SS/

Each backup is timestamped and contains:

  • Original mod files
  • Original index.json
  • Backup metadata

Backup Retention​

Configure automatic cleanup:

# Keep last 5 backups
BACKUP_RETENTION_COUNT = 5

# Keep backups from last 30 days
BACKUP_RETENTION_DAYS = 30

Manual Restore​

To restore from a backup:

python restore_backup.py --backup-dir backups/2026-02-07_03-00-00

Rate Limiting​

The updater respects Modrinth API rate limits:

  • Checks rate limit headers in responses
  • Automatically throttles requests when approaching limits
  • Implements exponential backoff for 429 responses
  • Caches API responses to minimize requests

Dependency Resolution​

Automatic Dependency Detection​

The updater can:

  • Detect required dependencies for mods
  • Warn about missing dependencies
  • Optionally download required dependencies

Conflict Detection​

Identifies potential conflicts:

  • Mods that shouldn't be used together
  • Version incompatibilities
  • Duplicate functionality

Custom Filters​

Exclude Specific Mods​

Create a blacklist file:

{
  "excluded_mods": [
    "project-id-1",
    "project-id-2"
  ]
}

Pin Specific Versions​

Prevent certain mods from updating:

{
  "pinned_mods": {
    "project-id-3": "1.0.0",
    "project-id-4": "2.5.1"
  }
}

Troubleshooting​

Common Issues​

API Connection Failures​

Symptoms:

  • Timeout errors
  • Connection refused messages
  • 503 Service Unavailable

Solutions:

  • Check internet connection
  • Verify Modrinth API status
  • Wait and retry (may be temporary outage)
  • Check firewall settings

Version Compatibility Issues​

Symptoms:

  • No updates found for mods that have updates
  • "No compatible version" messages

Solutions:

  • Verify Minecraft version is correct
  • Check modloader type matches your setup
  • Look for beta/alpha versions if stable versions are missing
  • Check mod's Modrinth page manually

File Permission Errors​

Symptoms:

  • "Permission denied" when writing files
  • "Access denied" when creating backups

Solutions:

  • Run with appropriate permissions
  • Check directory ownership
  • Ensure disk isn't full
  • Verify antivirus isn't blocking access

GUI Won't Launch​

Symptoms:

  • Window doesn't appear
  • Crashes immediately
  • Import errors for tkinter

Solutions:

  • Ensure Python includes tkinter (python -m tkinter)
  • Install tk package (Linux: sudo apt-get install python3-tk)
  • Check Python version is 3.8+
  • Try command-line mode as fallback

Debug Mode​

Enable verbose logging:

python update_modpack.py --modpack-dir /path/to/modpack --verbose

This outputs:

  • API request/response details
  • File operations
  • Decision logic
  • Timing information

Validation​

Verify modpack integrity:

python validate_modpack.py --modpack-dir /path/to/modpack

Checks for:

  • Valid index.json format
  • File existence and checksums
  • Dependency satisfaction
  • Environment tag correctness

Best Practices​

Regular Updates​

  • Run updates weekly to stay current
  • Test updates in a development environment first
  • Keep backups before major version changes
  • Review changelogs for breaking changes

Version Control​

  • Keep modpack definition in version control (Git)
  • Exclude downloaded mod files (large binary files)
  • Include index.json and configuration
  • Track changelog files

Testing​

Before deploying updates:

  1. Update a test instance
  2. Launch Minecraft and verify loading
  3. Test critical functionality
  4. Check for console errors
  5. Verify mod compatibility

Documentation​

Maintain documentation for your modpack:

  • Required Minecraft version
  • Modloader and version
  • Known issues
  • Custom configuration notes
  • Update history

Security Considerations​

API Key Protection​

If using an API key:

  • Never commit API keys to version control
  • Use environment variables
  • Rotate keys periodically
  • Monitor API key usage

Download Verification​

The updater verifies downloads:

  • Checks SHA-512 checksums
  • Validates file sizes
  • Compares against Modrinth metadata

Safe Execution​

  • Run with minimal required permissions
  • Use virtual environment isolation
  • Review downloaded files if concerned
  • Keep Python and dependencies updated

Future Enhancements​

Planned features include:

  • Mod dependency auto-installation
  • Multi-pack management
  • Update scheduling interface
  • Mod recommendation system
  • Performance profiling
  • Automated testing integration

Community and Support​

Getting Help​

  • GitHub Issues: Bug reports and feature requests
  • Documentation: This guide and README
  • Modrinth Documentation: API reference
  • Community Forums: General discussion

Contributing​

Contributions welcome:

  • Bug fixes
  • Feature implementations
  • Documentation improvements
  • Testing and feedback

Follow the contribution guidelines in CONTRIBUTING.md.

License​

The Modrinth Auto Updater is released under the MIT License, allowing free use, modification, and distribution with attribution.