modsmith 0.3.0

A Python toolkit for Minecraft modpacks, mod loaders and game instances.

Documentation · English · 简体中文

Modsmith is a library, not a launcher. Its small modules work together or alone, so you can build your own modpack installer, updater, CLI or GUI.

Two platforms, one API Search and download from Modrinth and CurseForge the same way.	Modpacks, even offline Open Modrinth and CurseForge packs without a network connection.	Four mod loaders Install Forge, NeoForge, Fabric and Quilt with one call.
Safe updates Update a modpack and keep the changes players made.	The right Java Find the Java that a game version needs, or download it.	Reliable downloads Files are verified, and interrupted downloads pick up where they stopped.

Installation

Modsmith needs Python 3.12 or newer. Install it from PyPI:

pip install modsmith

Or with uv:

uv add modsmith

Quick start

Download a modpack from Modrinth, install its loader, create an instance and add it to the official launcher:

import modsmith as ms

with ms.platforms.Modrinth("my-tool/1.0") as modrinth:
    project = modrinth.get_project("fabulously-optimized")
    release = next(modrinth.iter_releases(project, game_version="1.21.1"))
    pack = ms.packs.load(modrinth.fetch(release, ".cache"))

game = ms.minecraft.GameDir.default()
version_id = pack.loader.install(game)

instance = ms.instances.Instance.open("instances/fabulously-optimized")
instance.sync(pack)

ms.launcher.Launcher(game).add_profile(pack.name, version_id, instance.path)

Open the official launcher once before you run this, and keep it closed while it runs. To update, run instance.sync(pack) again with a newer pack.

Recipes

Every module also works alone.

with ms.platforms.Modrinth("my-tool/1.0") as modrinth:
    results = modrinth.search("sodium", project_type="mod", loader="fabric", limit=5)

for project in results.projects:
    print(project.name, project.url, project.downloads)

import os
from pathlib import Path

with ms.platforms.CurseForge(os.environ["CURSEFORGE_API_KEY"]) as curseforge:
    pack = curseforge.resolve(ms.packs.load("pack.zip"))

for entry in pack.unresolved:
    print(entry.manual_url)

instance.sync(pack, adopt_from=[Path.home() / "Downloads"])

changes = instance.diff(pack)  # changes nothing

print("New:", changes.added)
print("Updated:", changes.updated)
print("Removed:", changes.removed)
print("Changed by the player:", changes.conflicts)

game = ms.minecraft.GameDir.default()

ms.loaders.Fabric("0.16.10", "1.21.1").install(game)
ms.loaders.NeoForge("21.1.233", "1.21.1").install(game)

ms.minecraft.install_version(game, "1.21.1")

component = ms.java.required_for(game.version("1.21.1"), game)
runtime = ms.java.find(component, game=game) or ms.java.download(component)
print(runtime.executable)

token = ms.CancelToken()  # call token.cancel() from any thread


def show(event: ms.Progress) -> None:
    print(f"{event.task}: {event.current}/{event.total} {event.unit}")


instance.sync(pack, progress=show, cancel=token)

from modsmith.errors import ModsmithError

try:
    instance.sync(pack)
except ModsmithError as error:
    print(f"Sync failed: {error}")

How it fits together

Platforms, pack formats and mod loaders are independent, and you can add your own.

Compatibility

Scope and status

Modsmith works alongside the official launcher. It does not sign in to accounts or start the game.

The project is in alpha, so the API may change. No automated test starts the game yet. A command-line tool and a desktop app are planned.

Contributing

Contributions are welcome. See CONTRIBUTING.md to get started.

License

Modsmith is released under the MIT License. It is not affiliated with Mojang, Microsoft, Modrinth or CurseForge.