BG3 Mod Manager first time setup is the configuration sequence that runs once, immediately after extracting the release zip and before any mod is imported. The procedure has four mandatory parts: validating the extracted folder contents, launching the executable past Windows SmartScreen on a system with the .NET 8 Desktop Runtime present, populating the Game Data Path and Game Executable Path in Preferences, and clicking Refresh so the manager rebuilds its cache. This walkthrough covers each part in order and lists the most common first-launch mistakes from the GitHub tracker.
The procedure is current for BG3 Mod Manager v1.0.12.9 and Baldur’s Gate 3 Patch 8. No registry edits, no installer wizard, and no administrator rights are required for the standard portable layout.
Refresh Is Not Optional
BG3 Mod Manager has no installer. The release ships as a portable zip, and first-time configuration happens entirely inside the running application. Skipping the Refresh click after editing paths is the single most reported reason setup appears to fail on the GitHub tracker.
What Should Be in the BG3 Mod Manager Folder Before First Launch
The release archive on the LaughingLeader/BG3ModManager GitHub releases page is named BG3ModManager_Latest.zip. Once extracted to a writable location (Desktop, Documents, or a dedicated C:\Tools\BG3MM folder all work), the resulting directory must contain five entries: a _Lib folder, a Resources folder, a Tools folder, the BG3ModManager.exe entry point, and a BG3ModManager.exe.config file. If any of those five items is missing, the extraction was incomplete and the zip should be re-extracted with a tool that supports long paths (7-Zip or the built-in Windows Explorer extractor both work).
Two locations should be avoided on a first install: Program Files and Program Files (x86). Both are write-protected by UAC, and BG3 Mod Manager writes Preferences.xml, the active load order JSON, and the modsettings.lsx.bak file inside its own folder by default. A portable install in a protected location fails silently when those writes are denied. Issue #22 captures the original report; the maintainer’s recommendation has stayed consistent: extract to a user-writable directory.
Launching BG3 Mod Manager for the First Time on Windows
Double-clicking BG3ModManager.exe on a fresh Windows 10 or Windows 11 system produces one of three outcomes. The expected outcome is a brief splash followed by the main window: a left pane labelled Active Mods, a right pane labelled Inactive Mods, and a top toolbar with Refresh, Save, and Export Order buttons. The second outcome is a Windows SmartScreen dialog reading “Windows protected your PC”, dismissed by clicking More info then Run anyway. The third outcome is silent failure: no window, no error. That almost always means the .NET 8 Desktop Runtime is missing.
Verifying the .NET 8 Desktop Runtime Is Present
BG3 Mod Manager links against Avalonia UI, which requires the .NET 8 Desktop Runtime specifically (not the SDK, not the ASP.NET runtime, and not the older .NET 6 or .NET 7 runtimes). To check, open PowerShell and run dotnet --list-runtimes. The output should include a line beginning with Microsoft.WindowsDesktop.App 8.. If only Microsoft.NETCore.App entries appear, the desktop runtime is missing.
The runtime download lives on the official dotnet.microsoft.com page under “Run desktop apps”. Select the x64 Windows installer, run it, and reboot before retrying BG3MM. Issue #213 documents the silent-fail behaviour when the runtime is absent.
Pinning the SmartScreen Dialog Past on First Launch
The SmartScreen prompt appears because BG3ModManager.exe is signed by an open-source maintainer rather than a Microsoft-trusted commercial publisher. This is normal. The installation wiki at wiki.bg3.community documents the same dialog: click More info, then Run anyway. A second, less common dialog appears if the zip was downloaded via Microsoft Edge: a blocked-files attribute. The fix is to right-click BG3ModManager.exe, choose Properties, and tick Unblock at the bottom of the General tab.
The Game Data Path Setting Explained
Game Data Path is the single most important field in BG3 Mod Manager Preferences, and the one that produces the largest fraction of “nothing works” reports when set incorrectly. The field points at the Data subdirectory inside the Baldur’s Gate 3 install, not at the install root and not at the Steam library folder. BG3MM uses the value to read the bundled gameplay .pak files, resolve mod dependencies declared by imported archives, and validate that a campaign profile exists before allowing a load order export.
Per-Storefront Game Data Path Reference
- Steam (default):
C:\Program Files (x86)\Steam\steamapps\common\Baldurs Gate 3\Data - Steam (secondary drive):
D:\SteamLibrary\steamapps\common\Baldurs Gate 3\Data. Right-click the game in Steam, select Properties > Installed Files > Browse for the actual location. - GOG Galaxy:
C:\GOG Games\Baldurs Gate 3\Data. - Xbox Game Pass for PC:
C:\XboxGames\Baldur's Gate 3\Content\Dataafter taking ownership of the WindowsApps subdirectory.
The path field accepts both forward and backward slashes; trailing slashes are normalised internally. BG3 Mod Manager auto-detects the Steam install on most systems by reading the Steam registry keys, and the auto-detection populates the field on first launch. Manual entry is only required when auto-detection fails (secondary drive libraries, GOG, Game Pass) or when the path was previously set to a stale value.
Setting the Game Executable Path (Steam, GOG, Game Pass Differences)
The Game Executable Path field sits below Game Data Path in the same Preferences panel and points at the binary BG3MM invokes on Launch Game. The expected value differs by storefront because each ships a different launcher, and pointing at the wrong file produces either a “file not found” dialog or a launch that bypasses storefront integration.
- Steam DirectX 11:
...\Baldurs Gate 3\bin\bg3_dx11.exe - Steam Vulkan (default):
...\Baldurs Gate 3\bin\bg3.exe - GOG Galaxy:
...\Baldurs Gate 3\bin\bg3.exe(same binary as Steam Vulkan; GOG Galaxy attaches via the Galaxy overlay rather than a separate launcher). - Game Pass:
...\Baldur's Gate 3\Content\bin\bg3.exeafter ownership has been taken. Game Pass also requires running BG3MM as administrator on first launch so it can read the WindowsApps-protected directory.
For Steam, the choice between bg3.exe (Vulkan) and bg3_dx11.exe (DirectX 11) should match whichever renderer is being launched from the Steam library prompt. Modded BG3 generally runs more reliably on DirectX 11 because several popular shader and post-processing mods are tested only against the DX11 path. The renderer choice does not affect mod loading itself.
After populating both fields, the Save button writes the values to %APPDATA%\BG3ModManager\Preferences.xml and closes the dialog. At this point the panes are still empty: BG3 Mod Manager does not automatically rescan when Preferences are saved. The next section explains why a manual Refresh is required.
Why the Refresh Button Is Required After Path Changes
BG3 Mod Manager maintains an in-memory cache of three lists: bundled gameplay .pak files from the Game Data Path, user-installed .pak files from %LOCALAPPDATA%\Larian Studios\Baldur's Gate 3\Mods, and campaign profiles from %LOCALAPPDATA%\Larian Studios\Baldur's Gate 3\PlayerProfiles. The cache is built once at application startup, then kept in memory until the process exits. Edits in Preferences do not invalidate the cache: saved values are written to disk, but the running window still shows lists built from the previous paths.
The Refresh button on the main toolbar is the explicit “rebuild the cache from disk” trigger. Clicking it after a Preferences save causes BG3MM to re-enumerate the Mods folder, re-read the campaign profiles, and re-resolve dependencies against the new Game Data Path. The status bar briefly shows “Loading…” then updates with the detected mod count. Without that click, the panes remain empty even when the paths are correct.
What the Refresh Click Actually Does
- Rescans the Game Data Path’s
PublicandModssubdirectories for bundled gameplay archives. - Rescans
%LOCALAPPDATA%\Larian Studios\Baldur's Gate 3\Modsfor loose.pakfiles. - Re-reads the meta header of every detected
.pakto populate name, author, version, and dependencies. - Re-loads the campaign profile list from
PlayerProfilesand populates the active campaign dropdown. - Reconciles the new lists against the saved load order in
%APPDATA%\BG3ModManager\.
If Refresh produces no status-bar update, the saved Game Data Path is still invalid (typo, stale path, missing trailing \Data), or the path points at a directory the Windows user does not have read access to (the Game Pass case). The manager fails silently and leaves the panes unchanged. Reopening Preferences and confirming the path resolves in File Explorer is the correct response.
Confirming the Mods Folder Is Detected and the Active Campaign Is Selected
After the first successful Refresh, two things should be visible. The Inactive Mods pane on the right shows any loose .pak files that already live in the user-profile Mods folder. The campaign dropdown at the top of the window shows at least one entry, typically named Public or matching the most recent save. An empty dropdown indicates that Baldur’s Gate 3 has never been launched on this Windows user account, because the PlayerProfiles directory is created by the game on first run, not by BG3 Mod Manager.
Validating the Mods Folder Path
The Mods folder BG3 Mod Manager scans is fixed at %LOCALAPPDATA%\Larian Studios\Baldur's Gate 3\Mods for nearly every Windows install. Pasting that string into the File Explorer address bar opens the directory if it exists, or produces a “path not found” error if Baldur’s Gate 3 has not been launched yet. The fix is to launch the game once, exit, and click Refresh. The OneDrive redirected case is the exception: when Documents is redirected to OneDrive, the Mods folder may live under OneDrive\Documents\Larian Studios, and the Settings > Mods Folder field must be pointed there manually.
Selecting the Active Campaign Before Export
The active campaign dropdown determines which modsettings.lsx file is written on export. If the dropdown shows <None> after Refresh, the export silently no-ops and imported mods never appear in the in-game Mods menu. Selecting a real campaign (the entry matching the active save) is part of first-time setup, not a separate later step. Issue #238 contains user reports of this exact failure: panes populated, but mods do not load in-game because the campaign was never selected.
Common First-Launch Mistakes and How to Avoid Them
The failure patterns below account for the majority of “BG3 Mod Manager first time setup not working” threads. Each is matched to a specific Preferences value, file location, or runtime check.
- Extracting to Program Files. The portable layout writes Preferences and load orders inside its own folder; UAC silently blocks those writes. Move the entire folder to
C:\Tools\BG3MMor the Desktop. - Skipping the .NET 8 Desktop Runtime install. The application exits before showing a window. Run
dotnet --list-runtimesin PowerShell, look forMicrosoft.WindowsDesktop.App 8., and install if missing. - Pointing Game Data Path at the install root. The path must end in
\Data....\Baldurs Gate 3is wrong;...\Baldurs Gate 3\Datais correct. - Saving Preferences without clicking Refresh. The cache is not invalidated by the Save click. The Refresh button on the main toolbar must be clicked once after every Preferences edit.
- Leaving the campaign dropdown set to
<None>. Export silently no-ops when no campaign is selected. Issue #355 covers the related modsettings.lsx reset behaviour when this happens repeatedly. - Game Pass install without ownership transfer. The WindowsApps directory is locked. Right-click
C:\Program Files\WindowsApps\Larian.BaldursGate3..., choose Properties > Security > Advanced, and take ownership before pointing BG3MM at the Data folder. - OneDrive redirected Documents. The Larian profile may live under
OneDrive\Documents\Larian Studiosinstead ofDocuments\Larian Studios. Either disable OneDrive backup of Documents, or point the Mods Folder Settings field at the OneDrive location explicitly. - Importing a mod whose dependencies have not been installed. Issue #404 documents the missing-dependency warning. The dependent
.pakfile must be in the Mods folder and active before the dependent mod will resolve cleanly.
Once first-time setup is complete and Refresh has produced a populated mod list with a selected campaign, the manager is ready for normal operation. The next workflow most users hit is importing a downloaded archive, covered separately in install guides linked from the main BG3 Mod Manager guide. The latest signed release is linked from the download page.
Quick Setup Walkthrough Video
The video below walks through the same first-launch sequence covered in the article, in roughly five minutes: extracting the zip, dismissing SmartScreen, populating the two path fields, clicking Refresh, and confirming the mod count appears in the status bar.
Frequently Asked Questions
The full source for BG3 Mod Manager is on the official LaughingLeader/BG3ModManager repository, and the latest signed release that this walkthrough applies to is always linked from the download page. A general overview of the tool sits on the main BG3 Mod Manager guide.