Valheim Mod Manager (vmm)

A command-line tool for managing and automatically downloading Valheim mods and their dependencies.

Features

Automatically downloads mods from Thunderstore
Resolves and downloads all dependencies
Tracks downloaded mod versions
Only updates when new versions are available
Displays download progress with intuitive UI

Installation

From Source

# Clone the repository
git clone https://github.com/Endoze/valheim-mod-manager.git
cd valheim-mod-manager

# Install the application
cargo install --path .

# The binary will be installed in your Cargo bin directory

Configuration

vmm looks for configuration in the following order:

A vmm_config.toml in the current directory (local config)
~/.config/vmm/vmm_config.toml (global XDG config)

If neither exists, a default config is created at the global location on first run.

You can also specify a config file directly with the --config flag, which bypasses the above lookup entirely.

The config file supports the following settings:

mod_list: List of mods to install (in the format "Owner-ModName")
log_level: Logging verbosity (error, warn, info, debug, trace)
install_dir: Optional directory where unzipped mods will be copied (e.g., your Valheim mods folder)

Example configuration:

mod_list = ["denikson-BepInExPack_Valheim", "ValheimModding-Jotunn"]
log_level = "info"
install_dir = "~/some/path/to/Valheim/BepInEx/plugins"

Usage

Update Mod Manifest

Fetches the latest information about available mods from Thunderstore:

vmm update manifest

Update Mods

Downloads all mods in your configuration, including their dependencies:

vmm update mods

List Mods

Lists all mods from your configuration including resolved dependencies:

vmm list

By default outputs one mod per line. Use --format json for structured output:

vmm list --format json

Text output (default):

  denikson-BepInExPack_Valheim 5.4.2202
  ValheimModding-Jotunn 2.28.0

JSON output:

[
  {"full_name": "denikson-BepInExPack_Valheim", "version": "5.4.2202"},
  {"full_name": "ValheimModding-Jotunn", "version": "2.28.0"}
]

Search for Mods

Searches available mods by name:

vmm search <term>

This performs a case-insensitive search for mods containing the specified term in their name, displaying matching mods with their owner, name, version, and description.

Global Options

`--config <path>`

Override the config file location, bypassing the local/global lookup:

vmm --config /path/to/my/vmm_config.toml update mods

Downloads and cached data always go to ~/.config/vmm/ regardless of which config file is used. Respects $XDG_CONFIG_HOME if set.

How It Works

Reads your configuration to determine which mods to download
Downloads the mod manifest from Thunderstore
Builds a dependency graph for all required mods
Downloads required mods and their dependencies
Extracts mod files, skipping those already downloaded with matching versions
If install_dir is configured, copies the extracted mods to that directory

Directory Structure

~/.config/vmm/: Config and cache directory (respects $XDG_CONFIG_HOME)
~/.config/vmm/downloads/: Downloaded mod archives and extracted files

Troubleshooting

If you encounter issues, increase log verbosity in your config:

log_level = "debug"

Then run the command again to see more detailed output.

License

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

Acknowledgments

Thunderstore for hosting Valheim mods
The amazing Valheim modding community

valheim-mod-manager 0.2.0