Basic guide to installing The Witcher 3 mods
By Wasteland Ghost aka wghost81
Table of contents:
The first thing you should know before starting to install TW3 mods - modding support for this game is very basic, it’s not Skyrim level, not even close. Although there are very complex mods for TW3, installing them is not as easy as clicking one button - in most cases additional steps are needed for the mod to work properly. And if you have several mods, you’re very likely to have compatibility issues you’ll need to resolve using fan made tools.
Nexus Mod Manager (NMM) support for TW3 mods is also very basic: it can download and unpack the mod into proper folder for you, but for many mods out there it’s not enough. Texture mods work fine with NMM, but if you hit texture mods limit the game has, you’d still need fan made tools to get around it.
So, NMM can only be used as mod organizer for TW3, because it can’t fully handle all TW3 mods. If you’re not using NMM for other games and not yet familiar with it, you probably better off managing your mods manually (see below).
A fan-made Mod Manager for TW3 was released recently that handles even the most complex mods well and can auto-detect and properly install additional DLCs, menus and hotkeys that come with a mod. The tool is still work in progress, but it can already be recommended as a preferred method of installing mods for TW3.
Before you even start installing mods for TW3 (and for any other game, actually), you need to move the game out of system protected folder tree! Here’s good explanation why. If you have Steam version, here is a guide on how to move your installed game to another folder.
You could argue that you already have a lot of games with a lot of mods installed into Program Files and they work properly - and I would agree with you, because it’s possible. But this doesn’t mean you won’t have problems with this particular game or with some specific mod. So it’s easier to move your game now and guarantee you won’t have OS related issues than to run into weird game/mod behaviour and spend hours troubleshooting your unique problem no one else seems to have.
The Witcher 3 Mod Manager is a new fan-made tool to fully automatically install, disable/enable and uninstall even the most complex mods. It’s still work in progress, but it can already be recommended as a preferred method of installing mods for TW3. The tool auto-detects and installs additional DLCs, menus and hotkeys that come with a mod, eliminating the need for doing it manually. However, due to how TW3 engine works, you still need both Script Merger and Mod Merger (see below) to find and resolve mod conflicts and to work around texture mod limit. Here’s a guide on how to use TW3MM.
Script Merger is the most important tool to have if you intend to use script based mods - it helps you both to detect conflicts and to resolve them by merging conflicting scripts. In many cases the tool is able to merge mods automatically, but sometimes auto-merging fails and you need to do it manually - so make sure you read the whole description page as it has useful explanations and links you might need. Script Merger can also help with conflicting xml files, but keep in mind that these often require basic modding skills and game resources knowledge to merge properly. Other conflicts, like textures or sfw menus, can be detected but can’t be resolved by the tool. Note that latest Script Merger version also shows conflicts between unbundled xml files, but this feature doesn’t work properly, so ignore it and follow instructions from corresponding mod readme or this guide. Here’s a guide on how to use Script Merger.
Mod Merger is needed if you plan to use texture mods a lot, because there’s hidden limit on how many separate texture mods the game can handle. If you have too many, you might start experiencing weird glitches, like missing textures, infinite loading screen, black screen or crashes. To resolve this problem you will need to merge all your installed texture mods into one with Mod Merger.
Nexus Mod Manager can also be used to install TW3 mods, but keep in mind that unlike The Witcher 3 Mod Manager it doesn’t fully support different mod types, so always read the description/readme for the mod you’re trying to install to see if you need any additional steps. Also NMM can’t help with resolving script conflicts and texture mod limit problem, so if you have several script mods you still need to run Script Merger after installing them with NMM and you still have to use Mod Merger if you’ve reached texture mod limit.
Note that several TW3 mod users also reported problems when using NMM and Script Merger together: NMM appears to create virtual folder structure, so Script Merger is not always able to properly locate your Mods folder. If you have such a problem, refer to NMM guides to resolve it or switch to installing mods manually (see below).
As a general rule you won’t be able to use mods if they were created for older or newer version of the game than you currently have, so checking if the mod supports your game version is very important. Texture mods (i.e. mods that change how characters and equipment look) are usually compatible with different game versions, but script mods and xml mods (i.e. mods that affect gameplay) are not - even if the game runs fine it doesn’t always mean it works properly as you might experience sudden crashes, glitches or balance issues.
Game version can be seen in the main menu. Current latest game version is 1.31, but there are still a lot of mods which only support 1.30 or 1.22 versions of the game. There also is one specific game version which is incompatible with any other versions: Game Of The Year (GOTY) edition by GOG (Steam GOTY is a bundle, not a special version). Main menu for GOTY shows 1.31 version number, but it’s not 1.31 compatible, so if you have GOTY edition you need to specifically check for GOTY compatibility.
If you don’t want to bother with game/mod version problem and make sure you have all the latest official features and fixes, there’s Unification patch available on Nexus, which combines GOTY and non-GOTY scripts to create feature complete final version of the game. Update your game to the latest patch available for your platform/version and then install Unification patch. Make sure you read the description page as it has useful information on how to install the patch and how to install mods with the patch.
Note that many of the top TW3 mods on Nexus are no longer supported by their original authors, but you can often find updated mod version in comments section - if the mod is very popular some mod user with modding knowledge might have updated it and uploaded for everyone else to use. Also note that this is considered a good manner to still download an outdated file and endorse the original mod if you liked it.
Also note that mods which were made for different game versions are generally incompatible. This means you can’t install 1.22, 1.30 and 1.31GOTY mods together and expect them to work (unless they’re simple texture mods).
Some mods might instruct you to downgrade your game, using one of the downgrade patches available on Nexus (like this one). It is an acceptable option, especially if you don’t intend to use any other mods. But do remember that you can’t mix different downgrade patches, especially patches that result in different game versions. And of course you can’t mix downgrade and upgrade patches (like 1.30 downgrade patch with Unification patch).
First and the most important rule you should follow to avoid unnecessary problems - install mods one by one. Even simple mods, even texture mods - install them one by one and check if the game starts up properly. Second important rule - never install mods or make any changes to any of the game files while the game is running. Third important rule - always read the description page and the readme before installing a mod.
Basic install steps usually include:
If you’re using fan-made The Witcher 3 Mod Manager, install steps include:
Here are basic things you need to pay attention to while installing a mod:
If the game starts up fine - you can close it and proceed to install the next mod or restart and play the game. If the game doesn’t start and displays script compiler window with compiling errors - then you’ve done something wrong. Do not attempt to google for ‘compiling error fix’ or something - there are indeed such files available, but it’s unlikely they could solve your particular issue, because there are dozens of different script errors caused by different incompatibilities and installing any additional files is more likely to create even more problems. Instead, remove the last mod you’ve installed, run Script Merger again, check if everything has returned to normal and the game starts up properly and proceed to perform Troubleshooting steps (see below).
All the mods for TW3 are located inside ‘[Path To The Witcher 3]\Mods’ folder. For example, I have Steam version of the game and I have my SteamLibrary on disk D, so my path looks like this: ‘D:\SteamLibrary\The Witcher 3\Mods’.
Not everything you drop into this folder is considered a mod - there’s strict naming and file structure convention the game uses:
Mod authors usually distribute their mods as compressed mod folder, so the first thing you should do is uncompress it. Some mod authors use zip, some rar and some 7zip compression for packing their mods. If you don’t have corresponding program installed, they might look like unknown file or like broken text file when you try to open them. In this case I recommend you download and install free 7zip program. It’s easy to use and it can uncompress every type of a file you can find on Nexus.
For example, if you downloaded a file named ‘modFriendlyHUD for patch 1.30 and 1.31-365-12-0.7z’, you need to uncompress it with 7zip. By default 7zip will uncompress it to ‘modFriendlyHUD for patch 1.30 and 1.31-365-12-0’ folder and when you look inside this folder, you will see modFriendlyHUD folder, which is the mod folder you need to copy into your ‘[Path To The Witcher 3]\Mods’ folder.
Here are basic steps for manual install:
Note that some mods might have specific install instructions which require you to copy files and folders into different places - so always read the readme and the description page!
To uninstall a mod, locate its mod folder inside ‘[Path To The Witcher 3]\Mods’ folder and delete it. If you have merged files - use Script Merger to fix them.
If you want to disable a mod temporarily, rename its mod folder so it doesn’t begin with ‘mod’. For example, if you rename ‘modFriendlyHUD’ to ‘~modFriendlyHUD’ it will be ignored by the game. Note that after renaming a mod you need to use Script Merger to fix your merged files.
If you’re using TW3 Mod Manager, it should auto-detect and install all in-game menus that come with the mod. In case auto-detection fails or you want to install everything manually, read the text below.
If the description page for a mod mentions something about in-game configuration menu - this means you won’t be able to fully install this mod with NMM and you will definitely need to perform additional steps manually.
In-game menu consists of xml file(s) and compiled localized text file(s). If the mod is non-localizable and requires you to install Custom Localization Fix to work properly, then chances are high it’s an old mod which is incompatible with current version of the game - recent mods use proper localization files to create proper and localizable in-game menus, so you don’t need any additional ‘fixes’ for the menu to work.
Xml files for in-game menus need to be copied into ‘[Path To The Witcher 3]\bin\config\r4game\user_config_matrix\pc’ folder. There’s no conventional way to install mods with menus - some authors use bat scripts, some use bin folder inside mod folder and others even distribute menu as a separate package. So to install in-game menu properly always follow the readme and/or the description!
Localization files are w3string files located inside mod folder, you don’t need any additional actions to install them, but if the menu is not displayed properly for you, chances are something happened to those files and you need to redownload/reinstall the mod to fix the problem.
If you delete the mod from ‘[Path To The Witcher 3]\Mods’ folder, xml menu file will still be there, so you will see menu in-game, but it won’t be properly displayed. To remove the menu you need to delete corresponding xml file from ‘[Path To The Witcher 3]\bin\config\r4game\user_config_matrix\pc’ folder. Mods with menus usually have uninstall instructions in the readme/description, so follow them to remove proper xml file.
Some of the mods with menus require you to initialize mod default settings either by copying some text into ‘[My Documents]\The Witcher 3\user.settings’ file or by adjusting them directly in-game. Note that without this step those mods might not work properly!
If you’re using TW3 Mod Manager, it should auto-detect and install all new hotkeys that come with the mod. In case auto-detection fails or you want to install everything manually, read the text below.
If the description page for a mod mentions new hotkeys - this means you won’t be able to fully install this mod with NMM and you will need to perform additional steps manually for these hotkeys to work.
Installing new hotkey(s) usually requires editing or replacing of ‘[Path To The Witcher 3]\bin\config\r4game\user_config_matrix\pc\input.xml’ file and adding new entries into ‘[My Documents]\The Witcher 3\input.settings’ file.
There’s no conventional way of installing hotkeys, so different mods might use different methods: bat files, manual copying or manual editing. It’s important to know that if you have several mods with new hotkeys installed, using bat files or replacing existing input.xml file will remove hotkeys from all previously installed mods, so in this case manual editing is the only proper way.
Both input.xml and input.settings files are simple text files that can be edited with standard Windows notepad or notepad++ (free alternative to standard notepad with syntax highlight and many other useful features).
Newest Script Merger version has a feature to merge unbundled xml files and since many mod authors distribute altered input.xml file inside mod folder, Script Merger treats them as conflicting. However, there’s a problem with merging input.xml files - the feature doesn’t actually work properly. This is why mod authors still provide manual merging instructions for input.xml in the readme. So, if you have latest Script Merger version and you see input.xml conflict in unbundled files category, ignore it, but check the readme to make sure you’ve installed hotkeys properly.
Note that if you don’t add new hotkeys into input.xml and only add them into input.settings, they are very likely to be deleted by the game when it starts, i.e. your new hotkeys won’t work. And if you add new hotkeys into input.xml properly, but don’t add them into input.settings, they won’t be initialized and you won’t be able to assign them properly - they will appear to be assigned, but won’t work and will reset after restarting the game.
To uninstall the hotkeys you need to remove corresponding lines from input.xml file - mods with new hotkeys usually have uninstall instructions in the readme/description, so follow them to remove proper lines. Never delete the whole input.xml file as you will delete all vanilla hotkeys as well.
Game menus are defined in redswf files. There are no official tools to work with these, but some skilled modders can actually make changes to redswf and menus. Examples of mods with altered menus are Sort Everything, Colored Map Markers, All Quest Objectives.
The problem with such mods is if they change the same set of redswf files they can’t be merged (not without a lot of work and advanced modding skills anyway). So if you run Script Merger and it see redswf file(s) among conflicting bundled files, this means that corresponding mods are incompatible and can’t be used together - unless mod author(s) have made specific version, which needs to be used with specific mod. For example, Colored Map Markers mod has special version which you need to use if you have All Quest Objectives mod installed.
Different texture mods which change the same set of files and shown as conflicting in Script Merger are incompatible with each other unless mod author(s) have specific instructions and/or specific compatibility versions.
There is a hidden limit to how many texture mods you can use - if you have too many, you might start experiencing weird glitches, like missing textures, infinite loading screen, black screen or crashes. To resolve these problems you will need to merge all your installed texture mods into one with Mod Merger.
There’s no need to install console enabler mods to activate developer console in TW3. Instead open your [My Documents]\The Witcher 3\user.settings file and insert this text at the beginning:
Save the file and run the game - you will now be able to access the console with ~ (tilde) key.