Published using Google Docs
Basic guide to installing TW3 mods
Updated automatically every 5 minutes

Basic guide to installing The Witcher 3 mods

By Wasteland Ghost aka wghost81

Table of contents:

Preface

Preparing your game to handle mods

Tools for TW3 modding

Different game and mod versions

Installing a mod

Things to remember when installing a mod

Installing core mod files manually

Mods with in-game menus

Mods with additional hotkeys

Mods with conflicting redswf files

Texture mods

Troubleshooting

Compilation errors

Compatibility problems (if you have more than one mod)

Key/button bindings problems

NMM problems

Other problems

How to update/restore your modded game properly

An easy way to enable developer console

Preface

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.

Preparing your game to handle mods

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.

Tools for TW3 modding

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).

Different game and mod versions

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).

Installing a mod

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:

  1. Installing core mod files manually or with NMM.
  2. Installing in-game mod menu (optional, depends on the mod).
  3. Installing new hotkeys (optional, depends on the mod).
  4. Initializing mod setting and hotkeys (optional, depends on the mod).
  5. Checking for script/xml conflicts with Script Merger.
  6. Merging texture mods with Mod Merger.

If you’re using fan-made The Witcher 3 Mod Manager, install steps include:

  1. Downloading mod package from Nexus.
  2. Installing the package you downloaded by pressing “Install Mod” button.
  3. Launching Script Merger to find and resolve possible script/xml conflicts.
  4. Merging texture mods with Mod Merger if needed.

Things to remember when installing a mod

Here are basic things you need to pay attention to while installing a mod:

  1. Mod version. Check if the mod is compatible with your current game version (if you have Unification patch installed and have doubts about which mod version to use with it, refer to this patch description page and comments section). If the mod is not compatible, try searching for updated versions in comments (if you have Unification patch installed, also check this patch comments section) or for other mods with similar functionality. If there’s no compatible version and no alternatives available, do not install this mod - you’ll have less problems with your game without it. If you really-really want it, try asking other mod makers about updating the mod or creating something similar.
  2. Required files. Check if the mod has any requirements - there is ‘Required files’ button below mod title and version number and also when you’re trying to download the mod with additional requirements, a window pops up, informing you about them. If there are any - you will need to install required mod/patches before installing this mod. Always check if different mods you’re trying to install have conflicting requirements, because if they do, you won’t be able to use them together.
  3. Manual, NMM or TW3 Mod Manager. Decide which method of managing your mods you will be using: manual install, NMM or automatic install with TW3 Mod Manager. Do not mix these methods - although it can be done, you can end up breaking your mods to the point where you will need to delete and reinstall everything.
  4. Launching vanilla game at least once. If you haven’t previously launched your game - do it now to make sure it works and to double check which game version you have.
  5. Additional install steps. Many of the mods have additional install steps you need to perform for the mod to work properly, so read the readme if you still haven’t. Note that if you’re using TW3 Mod Manager, it will auto-detect and install everything for you, but you still need to know what exactly should be installed to check if the manager did things right.
  6. Specific compatibility instructions. If the mod has specific compatibility instructions and you already have other mods installed, read them before attempting to merge your mods with Script Merger - mod readme might instruct you not to merge certain files or might have instructions on how to merge specific files.
  7. Check for conflicts. If you already have other mods installed, run Script Merger to find and resolve conflicts. If your new mod modifies the same files you already merged before, it’s better to delete corresponding merges and merge these files again.
  8. Texture mods limit. If you’re installing another texture mod, chances are high you’re at your texture mods limit. To make sure your game with lots of texture mods works properly, run Mod Merger and merge all your texture mods into one.
  9. Run the game. After you’ve finished merging, run the game and see if it starts up properly. If it doesn’t - then the mod you’ve just installed is responsible. This is why it’s important to install mods one by one - if you’ve installed like ten of them at once, it’s impossible to tell which one causes the problem.
  10. Close and restart the game. Remember to always close and restart the game after you’ve installed a new mod - in some cases playing the game without restarting after it has just compiled new scripts results in weird bugs and glitches.

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).

Installing core mod files manually

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:

  1. All mod folders are named as ‘modSomething’, where ‘Something’ is a mod name. For example, mod folder for Friendly HUD mod is named ‘modFriendlyHUD’.
  2. If you take a look inside mod folder, you should see a folder named ‘content’.
  3. Mod authors often put additional folders, files and instructions like the readme directly into mod folder, so if you don’t know where to look for the readme - mod folder is the first place you should check.

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:

  1. Download a mod from the Nexus (don’t forget to check for mod version - see above).
  2. Unpack the mod you downloaded.
  3. Locate mod folder among unpacked files (‘modSomething’ where ‘Something’ is the name of the mod you’re installing).
  4. Copy mod folder into ‘[Path To The Witcher 3]\Mods’ folder.
  5. Double check if mod folder name starts with ‘mod’ and that it has ‘content’ folder inside.
  6. Check if there’s readme inside mod folder and read it.
  7. If you have other mods installed - use Script Merger to find and resolve possible conflicts.

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.

Mods with in-game menus

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!

Mods with additional hotkeys

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.

Mods with conflicting redswf files

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.

Texture mods

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.

Troubleshooting

Compilation errors

  1. If none of the mods work for you and you get a lot of compile errors and/or the game is not loading, then delete all your mods (and make sure ‘[Path To The Witcher 3]\Mods’ folder is indeed empty) and use Steam/GOG cache verification feature. Start the game once after verifying the cache to make sure it’s working. Reinstall Unification patch if you had it installed! And then try installing your mods again one by one.
  2. If some particular mod doesn’t compile - check if it’s compatible with your game version.
  3. If you have old version of the game - update it to the latest patch available. Reinstall Unification patch if you had it installed!
  4. Make sure you have all the required dependencies installed properly.
  5. If you have previously installed modBaseScripts to fix your compilation problems or any other type of ‘compilation error fix’, delete them all.
  6. If you have pre-ModKit mods installed, you need to uninstall them and restore backups/verify game cache/reinstall the game to make sure all your base files are vanilla. Otherwise you might experience problems with mods created with official ModKit. Reinstall Unification patch if you had it installed!
  7. If you have several different fixes, downgrade or upgrade mods/patches installed, then your game won’t work properly - check out item 1.
  8. If you’ve deleted all your mods but still getting compile errors - make sure ‘[Path To The Witcher 3]\Mods’ folder is indeed empty.
  9. Make sure you don’t have backups of original scripts folder inside [Path To The Witcher 3] folder tree. If you do, move them to another place, anywhere out of The Witcher 3 install folder.

Compatibility problems (if you have more than one mod)

  1. If you have several mods installed, use Script Merger to find and resolve compatibility problems. Note that there are several types of conflicts which Script Merger can’t resolve - textures, redswf and other non-text game resources.
  2. If you've upgraded one (or more) of your mods from previous version, you need to delete all existing merges related to this mod in Script Merger and then merge your mods again.
  3. If some of the installed mod features don't work, then it's probably a compatibility problem, check out items 1 and 2.
  4. Some of your mods might belong to different game versions, if so, delete the ones which version doesn’t match with your current game version.
  5. If you have previously installed mods that require you to edit ‘[My Documents]\The Witcher 3\mods.settings’ file, delete this file and merge your mods using Script Merger. If you want to keep this file, make sure you have priorities properly set and note that Script Merger might not work properly for you.
  6. If you have several texture mods installed and you’re experiencing weird glitches like missing or corrupt textures, very long or infinite loading screen or the game doesn’t start at all - then you might be at your texture mods limit. Use Mod Merger (not Script Merger!) to merge all your texture mods into one.

Key/button bindings problems

  1. Make sure you're editing input.settings file and not input.settings.bak file. If you can’t find input.settings file, it can be associated with some program and Windows hides its extension, so you might see just ‘input’ instead.
  2. Make sure you’ve added new actions into input.xml file and that they’re still there. If they’re not - see Preparing your game to handle mods part above.
  3. Make sure you don't have backup copies in the same folder where input.xml file is. If you do, move them to another place, anywhere out of The Witcher 3 install folder.
  4. Do not make edits while the game is running. Exit the game, edit the file, save and close it, run the game.
  5. If new keys keep resetting, copy all the necessary lines to input.settings again and set ‘read only’ attribute for this file. Note that in this case you will be unable to change any bindings, including vanilla key bindings, in-game.
  6. If you copy/pasted new bindings at the beginning of the file but can't see them in the same place after running the game it doesn't necessarily mean they were deleted. The game rearranges this file each time it starts, so search for new bindings under corresponding sections.
  7. If you have AZERTY or any other type of keyboard, which is not QWERTY, then default key bindings might correspond to other keys for you.

NMM problems

  1. If you've installed a mod with NMM and something doesn't work or it looks like not all mod files were extracted properly, try deleting it and installing the mod manually.
  2. If a mod has in game menu or new hotkeys, you have to perform additional steps described in mod readme for them to work even when installing the mod with NMM, because these things are not officially supported and NMM can't handle them.
  3. Sometimes Script Merger shows no conflicts for actually conflicting mods - it happens because NMM uses virtual folder structure and Script Merger can’t find installed mods. Refer to NMM manual to find where your mods are located and adjust Script Merger options accordingly or switch to installing mods manually.

Other problems

  1. If you have some weird problems, like settings disappearing/reverting back to vanilla or files you copied suddenly missing or reverting back to vanilla, read Preparing your game to handle mods section above.
  2. Sometimes the game just stops recognizing mods for no reason. To fix the problem, you need to trigger recompilation by deleting this file: ‘[Path To The Witcher 3]\content\content0\x64.final.redscripts’.
  3. Make sure you exit and restart the game after it compiled the new scripts, otherwise you might experience weird glitches, like wrong number of potions (-1), etc.

How to update/restore your modded game properly

  1. Backup your [Path To The Witcher 3]\Mods and [My Documents]\The Witcher 3 folders to a safe place.
  2. Delete [Path To The Witcher 3]\Mods folder to make sure you have no leftover mods and merges.
  3. Delete [My Documents]\The Witcher 3\input.settings, [My Documents]\The Witcher 3\input.settings.bak, [My Documents]\The Witcher 3\user.settings and [My Documents]\The Witcher 3\user.settings.bak to both make sure all changes from patch are applied properly and to make sure you don't have leftover changes from mods.
  4. Delete [Path To The Witcher 3]\content\content0\scripts folder and [Path To The Witcher 3]\content\content0\x64.final.redscripts file to make sure your scripts will be updated properly.
  5. Delete [Path To The Witcher 3]\bin\config\r4game\user_config_matrix\pc folder to make sure you have no leftover key bindings and menu files from mods.
  6. If you have ever edited ini files in [Path To The Witcher 3]\bin\config folder delete the whole [Path To The Witcher 3]\bin\config folder to make sure you graphics and keybindings settings are vanilla.
  7. If you ever had reshade or console enabler, remove them from the game folder. If unsure what to remove, delete the whole [Path To The Witcher 3]\bin folder. Note: Don't do it for GOG version as you will be unable to verify the game after this! Delete only console/reshade files manually!
  8. Verify the game using Steam/GOG cache verification.
  9. Run the game once to let it create default settings files.
  10. Re-apply your personal graphics, gameplay, key binding, etc. settings.
  11. Install mods one by one, make sure that mods you're installing were updated to work with latest patch (see the above sections on how to install mods and troubleshoot modding problems).

An easy way to enable developer console

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:

[General]

DBGConsoleOn=true

Save the file and run the game - you will now be able to access the console with ~ (tilde) key.