How to Copy Thunderstore Mods Using Code

by | Blog

Modding has been a cornerstone of the gaming community for decades, allowing players to personalize and extend the functionality of their favorite games. Thunderstore is one of the most widely used mod repositories, particularly known for supporting games like Valheim, Bonelab, Lethal Company, and more. While installing mods through a mod manager or manually is common, there are situations where copying or managing Thunderstore mods using code becomes essential—especially for developers, mod pack authors, or server administrators. This article provides a comprehensive, step-by-step guide on how to copy Thunderstore mods using code in a clean, effective, and reliable way.

TL;DR

If you want to copy mods from Thunderstore using code, your best route is through the Thunderstore API or by programmatically parsing the mod manager files (typically in JSON or BepInEx formats). You can automate downloads with Python or another scripting language and handle dependencies intelligently using available metadata. Make sure to honor mod licenses and attributions, and structure your scripts to handle version updates gracefully. This guide explains everything in full detail below.

1. Understanding Thunderstore’s Mod Structure

Before diving into automation, it’s essential to know what you’re dealing with. Thunderstore uses a structured convention for each mod package. Mods are typically built for BepInEx or MelonLoader frameworks. When you install a mod through the Thunderstore Mod Manager (or TMM), the mod’s content is placed in a directory structure based on metadata such as author, package name, and version.

  • Example mod path: /BepInEx/plugins/MyMod/
  • Metadata info: Usually comes from a file like manifest.json
  • Mods may have dependencies, configuration files, and compatibility notes.

2. Fetching Metadata and Mod Files Programmatically

You can programmatically access metadata and download links for mods through Thunderstore’s API, which is GraphQL-based. Another approach involves parsing mod manager files locally. Below is an outline of both methods.

Option A: Using Thunderstore API

Thunderstore offers a public-facing API that can be used to fetch mod metadata. Here is a basic example in Python using the requests library:

import requests

query = """
{
  package(author: "username", name: "mod-name") {
    versions {
      versionNumber
      downloadUrl
    }
  }
}
"""

response = requests.post(
    "https://thunderstore.io/api/experimental/graphql",
    json={'query': query}
)

data = response.json()
print(data)

Important Notes:

  • Replace "username" and "mod-name" with the mod’s actual author and package name.
  • This API may change, so check Thunderstore’s docs frequently for updates.

Option B: Reading from the Mod Manager’s Local Files

When using Thunderstore Mod Manager, it maintains metadata and file structure for each mod in a known, consistent folder path—often inside your AppData or game directory. You can parse these files to identify and copy required mods.

import os
import shutil

mod_source_dir = os.path.expanduser("~\\AppData\\Roaming\\Thunderstore Mod Manager\\profiles\\GameProfile\\BepInEx\\plugins")
mod_destination_dir = "C:\\MyModBackup\\plugins"

if not os.path.exists(mod_destination_dir):
    os.makedirs(mod_destination_dir)

for mod_file in os.listdir(mod_source_dir):
    full_file_name = os.path.join(mod_source_dir, mod_file)
    if os.path.isfile(full_file_name):
        shutil.copy(full_file_name, mod_destination_dir)

This code snippet helps you automate the copying process on Windows. You can adapt it for Linux or macOS by changing the paths accordingly.

3. Handling Dependencies

Thunderstore mods often rely on other packages or frameworks. It’s critical to resolve these dependencies programmatically. Each mod comes bundled with a manifest.json that lists dependencies in a structured way.

{
  "name": "MyMod",
  "version_number": "1.0.0",
  "website_url": "...",
  "description": "....",
  "dependencies": [
    "BepInEx-BepInExPack-5.4.16",
    "OtherDev-DependencyMod-1.3.2"
  ]
}

Pro tip: Parse this file using Python’s json module and automatically queue the dependencies for download using the same API-fetching logic described previously.

4. Version Management and Updates

Many mods receive frequent updates, sometimes including breaking changes. To handle this programmatically, consider implementing version checking logic that regularly queries metadata and compares the current version to the installed one.

def is_update_available(current_version, latest_version):
    return tuple(map(int, latest_version.split("."))) > tuple(map(int, current_version.split(".")))

Use a mapping or database to store current versions, and rerun the script periodically (daily or weekly) to check for updates.

5. Building an Automated Mod Copy Script

You can integrate the above concepts into a single Python script that copies, tracks, and updates mods intelligently. Below is a simplified workflow outline for a larger system:

  1. Fetch list of target mods from a config or JSON file.
  2. Query Thunderstore API or local mod manager to verify current version.
  3. Compare to installed version using version control logic.
  4. Download and extract new mods using requests and zipfile.
  5. Place mod files into appropriate directories (e.g., BepInEx/plugins).

It’s a good idea to log operations and errors. Use Python’s logging module to write to an easily auditable log file. You can also consider more advanced features like parallel downloads using concurrent.futures.

6. Tips for Windows and Linux Compatibility

If you’re planning to run your script cross-platform (e.g., managing a dedicated server on Linux while developing on Windows), make sure to:

  • Use os.path and os.sep instead of hardcoded paths.
  • Avoid platform-specific features without testing.
  • Use environment variables to define game or mod manager path roots.

7. Ethical and Legal Considerations

Always respect copyright and licensing restrictions. Most mods on Thunderstore are open for personal use, but redistribution—especially in automated setups—may violate the license the creator provides. Some mods require explicit permission for use in modpacks or server packs. Always:

  • Read the mod’s license or usage agreement.
  • Credit authors appropriately in any automated or redistributed package.
  • Avoid stripping or modifying author metadata unless explicitly allowed.

8. Conclusion

Copying and managing Thunderstore mods using code is not only feasible but also extremely efficient for server admins, developers, and content pack creators. With a working knowledge of API usage, local file parsing, and scripting (especially in Python), you can streamline mod updates and ensure consistency across environments. Just remember to operate within legal and ethical boundaries, and always test your setup thoroughly before deploying to production or sharing with others.

As the modding ecosystem continues to grow, automating your workflow becomes not just a convenience—but a necessity.

Pin It on Pinterest