Skip to main content

​
Installation

BD2 Mod Manager is available for Windows and requires Python 3.13 or higher to run from source. Most users will want to download the pre-built executable versions.

​
System requirements

  • Operating System: Windows 10 or later
  • Python: 3.13+ (only if running from source)
  • Game: Brown Dust 2 installed via the official launcher

​
Download options

BD2 Mod Manager is distributed in two formats:

​
Standalone executable (.exe)

A single-file executable that requires no installation. Simply download and run.
  • Pros: Convenient, no dependencies required
  • Cons: May trigger false positive antivirus warnings

​
Full version (*-Full.zip)

A complete package with all required files extracted.
  • Pros: Less likely to trigger antivirus false positives
  • Cons: Multiple files to manage
If your antivirus flags the .exe version, use the *-Full.zip version instead. Both are safe to use.

​
Download from GitHub releases

1

Visit the releases page

Go to the GitHub Releases page to download the latest version.
2

Choose your download

Download either:
  • BD2ModManager.exe - Standalone single-file version
  • BD2ModManager-Full.zip - Full version with all files
3

Extract (if using .zip)

If you downloaded the *-Full.zip version, extract all files to a folder of your choice.

​
First launch

When you first run BD2 Mod Manager, it will:
  1. Create application data directory - The app creates a folder in your AppData to store configuration, profiles, and mod metadata: 
    %APPDATA%\Bruhnn\BD2ModManager
  2. Create staging mods directory - If not configured, the app creates a default mods/ folder in the application data directory to store your mod files.
  3. Prompt for game directory - You’ll be asked to select your Brown Dust 2 installation folder (where BrownDust II.exe is located).
    BD2 Mod Manager includes automatic game detection and may find your game installation automatically.
  4. Download game data - The app will automatically download character and asset data required for mod management (if auto-update is enabled in settings).

​
Game directory selection

The app needs to know where Brown Dust 2 is installed. You’ll be prompted to select the directory containing BrownDust II.exe. Example path: 
F:\Neowiz\Browndust2\Browndust2_10000001
The exact path varies depending on your installation, but it should contain:
  • BrownDust II.exe (the game executable)
  • BrownDustX folder (where mods are synced)
If you select the wrong directory, BD2 Mod Manager will display an error: “BrownDust II.exe not found!” Simply select the correct folder to continue.

​
Antivirus false positives

Some antivirus programs may flag the .exe version as suspicious. This is a false positive caused by how PyInstaller packages Python applications. The program does not contain malware. If you’re concerned:
  • Use the *-Full.zip version instead (less likely to trigger warnings)
  • Check the source code on GitHub yourself
  • Build the executable from source if you prefer

​
Running from source

Advanced users can run BD2 Mod Manager directly from source code:
1

Clone the repository

git clone https://github.com/bruhnn/BD2ModManager.git
cd BD2ModManager
2

Install Python 3.13+

Ensure you have Python 3.13 or higher installed.
3

Install dependencies

The project uses pyproject.toml for dependency management:
pip install .
Core dependencies (from pyproject.toml):
  • packaging (25.0+)
  • pillow (11.2.1+) - Image processing
  • py7zr (1.0.0+) - Archive extraction
  • pyinstaller (6.14.2+) - Executable packaging
  • pyside6 (6.9.1+) - Qt bindings for UI
  • requests (2.32.4+) - HTTP requests for updates
4

Run the application

python main.py
You can also use command-line options:
python main.py --log-level debug
python main.py --version

​
Next steps

Once installed, proceed to the Quick start guide to learn how to add and sync your first mod.

Quick start guide

Learn how to add mods, enable them, and sync to your game

Build docs developers (and LLMs) love

Get started for freeTalk to us