Skip to main content

Modrinth Auto-Updater - Minecraft Modpack Management

A powerful tool that automatically updates Minecraft modpacks using the Modrinth API, featuring intelligent modloader compatibility and professional client/server .mrpack generation with a beautiful GUI interface.

Overview​

The Modrinth Auto-Updater is designed to streamline Minecraft modpack management by automating the update process while maintaining compatibility and providing professional-grade pack generation capabilities. Whether you're a modpack developer or server administrator, this tool simplifies the complex task of keeping modpacks current.

Key Features​

Beautiful GUI Interface​

  • Modern Design: Dark theme with LunarBit styling and enhanced typography
  • Smart File Selection: Choose between folder or .mrpack file with visual dialog
  • Real-time Status: Live path validation and detailed progress tracking
  • Rich Configuration: Enhanced options panel with descriptions and validation
  • One-Click Updates: Streamlined workflow with intelligent status updates
  • Beautiful Output: Enhanced terminal output with better fonts and spacing
  • Cross-platform Compatibility: Works on Windows, macOS, and Linux

Intelligent Mod Updates​

  • Automatic Checking: Checks for mod updates using Modrinth API v2
  • Version Compatibility: Respects Minecraft version compatibility including sub-versions (1.21.x)
  • Smart Modloader Filtering: Quilt ↔ Fabric backward compatibility support
  • Multi-Platform Support: Supports Fabric, Quilt, Forge, and NeoForge modloaders
  • Safe Backup System: Automatic backup and replacement of existing mod files

Client/Server Pack Generation​

  • Separate Pack Creation: Generate optimized client and server modpack files
  • Server Compatibility Filtering: Automatic filtering using Modrinth API
  • Environment Tags: Proper client/server required/unsupported tags
  • Override Support: Handle configs, resource packs, and custom files
  • Modrinth Specification: Follows official Modrinth modpack specification

Comprehensive Reporting​

  • Color-coded Output: Easy status tracking with detailed progress information
  • Changelog Generation: Detailed Markdown changelog with update summaries
  • Update Statistics: Counts of updated, up-to-date, and failed mods
  • Export Capabilities: Export all mods to local mods/ directory

Technology Stack​

  • Core Language: Python 3.8+
  • API Integration: Modrinth API v2
  • GUI Framework: Enhanced interface with platform-specific launchers
  • Features: Cross-platform compatibility, automatic backup system
  • Dependencies: Minimal external dependencies for easy deployment

Installation​

Prerequisites​

  • Python 3.8 or higher
  • Internet connection for Modrinth API access

Quick Setup​

  1. Clone the repository:

    git clone https://github.com/LunarBit-dev/Modrinth-Auto-Updater.git
    cd Modrinth-Auto-Updater

  2. Quick Setup (recommended):

    # Linux/macOS
    chmod +x setup.sh && ./setup.sh

    # Windows
    setup.bat

  3. Manual Installation:

    pip install -r requirements.txt

Usage​

GUI Mode​

Launch the beautiful GUI interface with enhanced LunarBit theming:

# Universal launcher (automatically chooses best mode)
python3 launcher.py

# Explicit GUI launch
python3 launcher.py --gui

# Platform-specific launchers
./run_gui.sh        # Linux/macOS
run_gui.bat         # Windows
python3 run_gui.py  # Direct Python

GUI Features​

  • 🎨 Stunning Design - Modern dark theme with LunarBit colors
  • 📁 Smart File Selection - Visual dialog for folder or .mrpack file selection
  • ⚡ Real-time Status - Live path validation and progress tracking
  • ⚙️ Rich Configuration - Enhanced options with descriptions
  • 🚀 One-Click Updates - Streamlined workflow
  • 📋 Beautiful Output - Enhanced terminal with better typography

Command Line Usage​

Universal Launcher​

# Auto-detect best mode (GUI if available, CLI otherwise)
python3 launcher.py

# Force CLI mode with arguments
python3 launcher.py --cli --modpack-dir path/to/modpack --client

# Auto-detect CLI mode (when CLI arguments are provided)
python3 launcher.py --modpack-dir path/to/modpack --server

Direct CLI Usage​

# Update mods and export to local mods/ folder
python3 update_modpack.py --modpack-dir path/to/modpack

# Generate client .mrpack file
python3 update_modpack.py --modpack-dir path/to/modpack --client

# Generate server .mrpack file (with server compatibility filtering)
python3 update_modpack.py --modpack-dir path/to/modpack --server

# Generate both client and server .mrpack files
python3 update_modpack.py --modpack-dir path/to/modpack --client --server

Command Line Options​

usage: update_modpack.py [-h] --modpack-dir MODPACK_DIR [--client] [--server] 
                        [--overrides-folder OVERRIDES_FOLDER]

options:
  -h, --help                    Show this help message and exit
  --modpack-dir MODPACK_DIR     Path to modpack directory or .mrpack file
  --client                      Generate client .mrpack file
  --server                      Generate server .mrpack file  
  --overrides-folder FOLDER     Name of overrides folder (default: overrides)

Usage Examples​

Example 1: Basic Update​

python3 update_modpack.py --modpack-dir "./MyModpack/"

Result: Updates all mods, exports to mods/, generates changelog

Example 2: Client Distribution​

python3 update_modpack.py --modpack-dir "./MyModpack.mrpack" --client

Result: Creates MyModpack.mrpack optimized for client installation

Example 3: Server Deployment​

python3 update_modpack.py --modpack-dir "./MyModpack/" --server

Result: Creates MyModpack-server.mrpack with only server-compatible mods

Example 4: Full Distribution​

python3 update_modpack.py --modpack-dir "./MyModpack/" --client --server --overrides-folder config

Result: Creates both client and server .mrpack files with custom config folder

Input Formats​

The script accepts:

  • Modpack folders containing modrinth.index.json or index.json
  • .mrpack files (automatically extracted)

Modloader Compatibility​

Modpack TypeCompatible Mods
FabricFabric only
QuiltQuilt + Fabric (backward compatibility)
ForgeForge only
NeoForgeNeoForge only

Server Filtering​

When generating server .mrpack files, the script:

  1. Queries each mod's server_side compatibility via Modrinth API
  2. Includes only mods marked as "required" or "optional" for servers
  3. Excludes client-only mods (e.g., Sodium, OptiFine)
  4. Reports skipped mods in the output

Output Files​

Generated Files​

  • mods/ - Directory containing all updated mod files
  • {modpack-name}_changelog.md - Detailed update changelog
  • {modpack-name}.mrpack - Client modpack (if --client)
  • {modpack-name}-server.mrpack - Server modpack (if --server)

Changelog Format​

# Modpack Update Changelog - 2025-07-21

## 🔄 Updated Mods (2)
- **Sodium**: `mc1.21.4-0.6.0` → `mc1.21.6-0.6.13`
- **Fabric API**: `0.104.0+1.21` → `0.129.0+1.21.8`

## ✅ Up-to-date Mods (15)
- JEI: `19.22.4.118`
- REI: `16.0.744`
...

Project Structure​

modrinth-modpack-updater/
├── update_modpack.py          # Main script
├── launcher.py                # Universal launcher
├── run_gui.py                # GUI interface
├── requirements.txt           # Python dependencies
├── setup.sh / setup.bat      # Quick setup scripts
├── README.md                 # Documentation
├── LICENSE                   # MIT License
└── examples/                 # Example modpacks and configs

Code Features​

  • Type hints for better code maintainability
  • Error handling with detailed logging
  • Modular design with separate functions for each feature
  • API rate limiting respect for Modrinth API
  • Cross-platform compatibility (Windows, macOS, Linux)

Use Cases​

Modpack Developers​

  • Automated Updates: Keep development and release versions current
  • Client/Server Generation: Create optimized packs for different environments
  • Changelog Generation: Automatic documentation of changes
  • Quality Assurance: Ensure compatibility across modloader versions

Server Administrators​

  • Server Pack Creation: Generate server-optimized modpacks
  • Batch Processing: Update multiple server instances
  • Compatibility Checking: Verify mod server compatibility
  • Deployment Automation: Streamline server update processes

Content Creators​

  • Pack Maintenance: Keep featured modpacks up-to-date
  • Distribution: Create both client and server versions
  • Documentation: Automatic changelog generation for videos/posts
  • Version Management: Handle multiple Minecraft versions

Contributing​

Contributions are welcome! Please feel free to submit a Pull Request. For major changes, please open an issue first to discuss what you would like to change.

Development Setup​

  1. Fork the repository
  2. Create a feature branch (git checkout -b feature/amazing-feature)
  3. Make your changes
  4. Add tests if applicable
  5. Commit your changes (git commit -m 'Add amazing feature')
  6. Push to the branch (git push origin feature/amazing-feature)
  7. Open a Pull Request

Roadmap​

  • Support for CurseForge modpacks
  • Batch processing for multiple modpacks
  • Mod dependency resolution
  • Custom update channels (alpha, beta, release)
  • Integration with mod hosting platforms
  • Advanced filtering and exclusion rules
  • Automated testing and validation
  • Plugin system for custom processors

Known Issues​

  • Some mods may not have proper server compatibility tags on Modrinth
  • Very large modpacks (500+ mods) may take longer to process
  • Rate limiting may cause slower updates for modpacks with many mods

Support​

License​

This project is licensed under the MIT License - see the LICENSE file for details.

Acknowledgments​

  • Modrinth for providing an excellent API
  • Minecraft community for the amazing modding ecosystem
  • All contributors and users of this tool

Made with ❤️ by LunarBit for the Minecraft modding community