[Tutorial] How to install mods (manually & CKAN)

[4x4cheesecake]

I know there are already quite a few tutorials about this topic but I want to write my own anyway

Let's not waste any time and start directly

In general, there are two methods to install mods: manually and via CKAN. Both methods got their advantages and disadvantages.
 

Manual installation	CKAN installation
Advantages: Every mod can be installed manually Full control over the installation process   Disadvantages: Updating mods one by one can be quite annoying You have to take care of dependencies as well	Advantages: Quick and easy installation process Dependencies are handeld by CKAN automatically Version control and easy update method Disadvantages: Not every mod supports CKAN Less control over the installation process

 

A few more things in general and about this tutorial

If you got KSP on Steam, it is recommend to move the game directory out of the Steam directory to prevent auto-updates! It is not possible to deactivate updates on Steam but a new game version may break a mod and/or your (modded) savegame, so you definitly don't want to update the game before you know if all your mods will still work fine or got updated.
Keep in mind that many mods which are compatible with KSP 1.4.x, are still compatible with 1.5.x and 1.6.x. If you play on 1.5.x or 1.6.x and the mod you want to install isn't available for your specific game version, you can still try an older mod version with good chances of success

For most parts of this tutorial, I'm going to use "SCANsat" as an example, for various reasons

 

How to install a mod manually

Before you install a mod, you should know your game version so you can get the corresponding mod version. If you are not sure which game version you got, launch the game and take a look at the lower right corner in the main menu:

In this example, the game version is 1.6.1.

Where to download mods

There are three "main sources" for mods:

• Spacedock (provides a short preview/description and you can search for mods, many mods available)
• CurseForge (also a short preview/description and a search function)
• This forum /github (searching the forum can be difficult but the mod threads contain the most informations about the mod. Most release threads contain a download link to Spacedock, CurseForge and/or GitHub)

 

Download the correct mod version

On Spacedock, you can download the latest mod version via the "Download" button and the compatible game version is listed in the information panel. If you need a different mod version, open the "Changelog" and Spacedock will present every previous released mod version to you, together with the game version it was build for:

Spoiler

The design on CurseForge is similar: One button to "Download Latest File" and a "File" section which contains a list of previous versions:

Spoiler

Many GitHub links already direct you to the "Release" section of a repository but if you find yourself in the "Code" section, you have to browser there on your own

Spoiler

The "Release" section looks a bit differently but the latest version will always be the first entry. Old mod versions are available as well but there is not always the corresponding KSP version number listed. Sometimes it can be found in the mod name or the changelog of a release. To download the mod, just click on the link for the .zip archive:

Spoiler

In fact, @Gargamel already posted a detailed explanation about this topic, so if you are still in doubt how it works, you may want to read it as well

 

Dependencies

Quite a few mods require one or more other mod(s) to run properly or at all, these "other mods" are called dependencies. A distinction is made between hard- and soft dependencies:
Hard dependency: Required with no exception. If you don't install a hard dependency, you'll experience crashes, errors and misbehaviour of the mod.
Soft dependency: Required for additional features but not necessary to run the mod.

Dependencies are usually listed in the very first post (OP) of the mod release thread, in the "Information" tab of SpaceDock or the "Overview" tab on CurseForge. 
Sometimes, the dependencies are highlighted like this:

Sometimes, they are just mentioned somewhere in the text, in this case in the install instructions:

Take your time to read the informations provided by the mod author, so you don't miss anything crucial

 

Installation

Let's start with the step, all of you are waiting for

First of all, you need to find and open your KSP install directory. The install location depends on your system and where you bought the game so if you don't know where to look at, search your system for the "KSP_x64.exe". Keep a window with your KSP directory open.

Mods are usually distributed within .zip archives. You can un-zip the archive in a separate folder or unpack the files directly where they are supposed to be, that's up to you. I prefer the latter method
Open the folder/zip file of the mod in a separate window and place it somwhere next to the window which shows your game directory. Now, there are two cases which can happen:

Case 1: The mod folder comes with a "GameData" folder
As pointed out by @MaltYebisu, this method doesn't work on MacOS. Mac users, please scroll down a bit and read about case 2
If the mod folder contains it's own "GameData" folder, you can drag and drop it directly into your game directory, which also contains a "GameData" folder. This will merge both folders together (should work on each operating system):

Be sure, to drop the folder into an empty space and not into any other folder!

Case 2: You get the plain mod folder
If the mod is not distributed with it's own "GameData" folder, you drop the mod folder directly into the "GameData" folder of your game:

Again, be sure, to drop the folder into an empty space and not into any other folder!

On a sidenote: Some mod authors who wrote/maintain multiple mods, uses an additional sub folder for all of their mods (for example: Kerbal Alarm Clock and Transfer Window Planner). Don't worry about this, just treat them like the mod in the case 1 scenario and merge the folders together

(Case 3: ModuleManager)
"ModuleManager" (MM) is powerful mod on it's own and a common dependency for many other mods but so far, the install instructions don't fit for MM. It is a little bit special in two ways: First of all, you will not find a release version within the github repository, on SpaceDock or CurseForge. In order to download ModuleManager manually, you have to visit the MM thread here in the forum:

 

The very first post of this thread contains multiple download links for MM to fit for different versions of KSP. You have to scroll down a bit to find them:

Spoiler

If you cannot find your KSP version in this list, follow the instructions in the MM thread.
Also, MM is distributed as a plain .dll file and to install it, you have to place the "ModuleManager.dll" directly within the "GameData" folder of your game....no sub folder or anything else, just like this:

Spoiler

(Picture was added quite some time after I wrote this tutorial, please don't get confused by the different mods which are installed here, compared to previous screenshots)

That's already everything you have to do, MM is now installed properly
 

How to install a mod via CKAN

CKAN is a powerful and very well supported tool to manage your mods. You can install, update and remove mods with just a few clicks and even dependencies are handled automatically. It is available for Windows, Linux and MacOS and can be downloaded here:

Launch CKAN

After starting CKAN, you are asked to choose a KSP installation (you can manage multiple installations and versions):

CKAN automatically searches in some default installation paths for KSP, but if you followed my recommendation from the beginning and moved it somewhere else, you need to add it manually. Click on "Add new", navigate to your KSP install and select the "buildID64.txt".
On the first run for a new KSP install, CKAN will also ask you if you want to update the modlist and repository on each launch. I would suggest to allow both options so you are always up-to-date but it's up to you:

 

 

Basics about the UI

The UI of CKAN is pretty intuitive:

By default, all mods which are compatible with your KSP version will be listed. Since the list will be pretty long, there are some search options available like "mod name", "author" and "description". You can also decide which mods are listed in general by setting up the filter:

 

Manage your mods

As soon as you found the mod you want to install, click into the little box on the left to select the mod:

Now, the "Apply changes" button becomes available. Click on it, to display the changeset (you can also click on the "Changeset" tab). In this example, you will notice that ModuleManager will be installed as well even though we didn't select it manually. ModuleManager is set as an dependency for SCANsat so CKAN will install it automatically:


Hit "Apply" in the lower right corner to proceed.
The next two steps are optional, it depends on the mod you want to install:
Some other mods may be recommend or suggested to use along with the mod(s) you want to install. The main difference between those options is the pre-selection: Recommend mods are "opt-out" and suggested mods are "opt-in". In both cases, you will find a button in the lower left corner to select or de-select all mods from these lists.
If any of these lists appears, pick your choices and click on "Continue" to proceed.

CKAN will now download and install all selected mods and their dependencies

If you want to uninstall a mod, just unselect the mod in your list and repeat the installation steps.
Dependencies are not removed automatically but if you remove a dependency, every mod which depends on it will be removed as well!

 

Advanced stuff

CKAN provides some very useful tools and informations and I want to show you a few of them.

Compatible KSP Versions
by default, CKAN will only lists mods which are compatible with your game version. Since many mods which are compatible with 1.4.x still work fine in 1.5.x and 1.6.x, you can allow CKAN to show and install these mods as well:

Just select the versions you want to allow and apply the changes.

Metadata/Relationships/Contents/Versions
On the right side of the CKAN UI, you will find four tabs to display Metadata, Relationships, Contents and Versions:

Metadata shows some general informations about the mod like version, author and links to the homepage (usually forum post) and the source code.

Relationships shows informations about dependencies, recommendations, suggestions and mod conflicts:

Dependencies are marked with a "star", recommendations got a "thumb up", suggestions are marked with a "i" and conflicts are marked with a "!". If a mod name is highlighted red, it is not compatible with your game version (if it's a dependency, you cannot install the mod!). You can double click on these mods to find the corresponding CKAN entry.

Contents will show you a simple list of the mod contents but it requires to download the mod. There is also a button there to download it (without installation).

Versions provides a list of all available mod versions. Compatible versions are highlighted and if you want to install an older mod version, just double click on the list entry. If a newer version is already install, you need to remove it first.

 

I guess that's all for now, fedback and corrections are welcome

Happy modding

Edited January 8, 2021 by 4x4cheesecake
Updated screenshot leading to github release section

[HebaruSan]

1 hour ago, 4x4cheesecake said:

conflicts are red highlighted and marked with a "!"

The red highlight indicates a mod that's incompatible with your KSP version. Obviously that's good news for conflicts, since it means you aren't at risk of installing both, but if a dependency turns red then that'll block installation.

https://github.com/KSP-CKAN/CKAN/blob/4f3b3d7cdf9c65afd17283fd0631bd1749aa3f3a/GUI/MainModInfo.cs#L335

[4x4cheesecake]

22 minutes ago, HebaruSan said:

The red highlight indicates a mod that's incompatible with your KSP version. Obviously that's good news for conflicts, since it means you aren't at risk of installing both, but if a dependency turns red then that'll block installation.

https://github.com/KSP-CKAN/CKAN/blob/4f3b3d7cdf9c65afd17283fd0631bd1749aa3f3a/GUI/MainModInfo.cs#L335

Corrected, thanks

[A Random Kerbonaut]

I have a Mac, so I can't really use this.

[4x4cheesecake]

3 hours ago, A Random Kerbonaut said:

I have a Mac, so I can't really use this.

As far as I know, the installation procedure is the same on each operating system. The game still got a "GameData" folder, which is everything you need for the manual installation, and CKAN runs on a mac as well.

At which point do you see a major difference so you cannot use the tutorial? If there is something special on a mac I don't know about, I can probably add a few more informations for other mac users

[kcs123]

Few things that are worth to mention and that everyone should be aware of.

1. Many mod authors pack not only their mods, but also dependencies as well. However, when some of dependencies updates it is often not case that mod developers updates their archives as well. Double check if you actualy have latest version of dependency mod. Especialy if you encounter some bug in game. For example main mod may not need update, but some of dependency mod need update for latest KSP version
2. Quite a lot of mods share same dependency mod. Most common is MM, but there is others as well, like B9PartSwitch, FireSpitter and so on. Again, double check when you merge such mod that you didn't overwritten dependency mod with older version by accident. You may experience bugs in game if you are not careful.
3. When you uninstall some mod, be sure that you have removed whole folder of that mod. The way that MM works when it checks if some mod is installed or not is that it only search for mod folder name inside Gamedata folder. If it found one and in config files for MM patches is command to alter other files if mod in question is installed, it will apply patches for it while you actualy don't have such mod installed. That will lead to odd misbehaviours in game and in some cases crashes.
4. Issue #3 may happen more often if you use CKAN. It is due to way how CKAN do installs and uninstalls. CKAN will only delete files that it have unpacked trough install process as it keeps track of those files. However, some mods would create additional config files when you run them for the first time in game. Things like mod window position on screen, colours and similar that is prefered in different way for each user. In such case, when you want to remove mod with CKAN, it would not remove such config file and would not delete mod folder either. That will create issues mentioned at #3.
5. To avoid issue #3 and #4, before you remove some mod with CKAN, check it's folder name. After you uninstall mod, double check your KSP/Gamedata folder if mod is properly removed.
6. Some mods may be in conflict with some other mod. Be sure to read some info about mod you want to install, before you start using it.

Once you are aware how mods work in KSP, you will less likely make mistakes trough (un)install of mods. More than 90% of bug reports comes from faulty installs somewhere. So, if you encounter some bug, be nice to mod authors and double check your installs before reporting issues. Install mistake may happen to new KSP players as well as veteran players. No wonder, considering the number of mods available and when you want to install significant number of mods it may be tedious and tiresome process that can lead to mistakes.

[Heliocentric]

Congrats on TOTM!

[4x4cheesecake]

@kcs123 These are some nice addtional tipps, thanks

@HelioCentric Thanks

[Starboost88]

Thanks! I personally use manual installation, because idk if CKAN works for MacOS High Sierra.

[4x4cheesecake]

24 minutes ago, Starboost88 said:

idk if CKAN works for MacOS High Sierra.

I don't know either but I'm sure you'll find an answer to this question in the CKAN thread (linked above) or the wiki:

https://github.com/KSP-CKAN/CKAN/wiki/User-guide

In my experience, the CKAN people are very helpful and friendly, so if you want to try CKAN but got any issues, all you need to do is asking for help

[Gargamel]

Some individual help requests have been moved to their own thread. 

[MaltYebisu]

Great tutorial, I think it should be pinned to the mod releases forum.

A small typo in the beginning:

On 3/19/2019 at 6:15 AM, 4x4cheesecake said:

Updating mods one by one can be quiet annoying

quiet → quite  

[4x4cheesecake]

14 minutes ago, MaltYebisu said:

Great tutorial, I think it should be pinned to the mod releases forum.

Thank you very much

14 minutes ago, MaltYebisu said:

quiet → quite  

Actually, I honestly thought this is the correct spelling and I'm writing it this way since always (three times just in the OP)... I'm quite surprised you are the first one to correct me Thanks!

Edited May 21, 2019 by 4x4cheesecake

[MaltYebisu]

On 3/19/2019 at 6:15 AM, 4x4cheesecake said:

If the mod folder contains it's own "GameData" folder, you can drag and drop it directly into your game directory, which also contains a "GameData" folder. This will merge both folders together (should work on each operating system):

If you do that on macOS, you will not get the option to merge. You only get the options 'stop' and 'replace'. If you choose 'replace', the entire GameData folder will be replaced entirely (deleting the Squad folder and any mods you have installed).

I suggest to open the downloaded GameData folder and follow the Case 2 setup for Mac users. 

[4x4cheesecake]

40 minutes ago, MaltYebisu said:

If you do that on macOS, you will not get the option to merge. You only get the options 'stop' and 'replace'. If you choose 'replace', the entire GameData folder will be replaced entirely (deleting the Squad folder and any mods you have installed).

I suggest to open the downloaded GameData folder and follow the Case 2 setup for Mac users. 

Ok, didn't know that. I'll add a hint, thanks again

[Snark]

Moving to Add-on Discussions, hopefully a bit closer to the target audience.

[4x4cheesecake]

2 minutes ago, Snark said:

Moving to Add-on Discussions, hopefully a bit closer to the target audience.

And you also pinned it? Wow, thank you

[kspnerd122]

I would like to say that direct install is much better e.g. planet mod lags the game, remove a few planets, currently im playing using, KW rocketry, Restock +, Kerbal Reusability Expansion, KSP interstellar, Extrasolar, Galaxies Unbound, Kopernicus

CKAN can auto update your mods(breaks kopernicus, and by extention your planet mods, and your modded saves get corrupted, I never use CKAN), also I tried it and it is INFURIATING to find what went wrong with e.g your new planet mod because you don't know where to look because you don't know where the logs and gamedata folders are

[Tonka Crash]

On 4/16/2020 at 7:51 AM, kspnerd122 said:

CKAN can auto update your mods(breaks kopernicus, and by extention your planet mods, and your modded saves get corrupted, I never use CKAN), also I tried it and it is INFURIATING to find what went wrong with e.g your new planet mod because you don't know where to look because you don't know where the logs and gamedata folders are

CKAN doesn't do anything automatically without you explicitly telling it to, it just can't.  You have to launch CKAN and tell it to update for it to do anything at all.  My understanding is that Steam will try to keep your game updated by default and this seems to create no end of problems, but CKAN doesn't and never has.

But, it's always a good idea to back up your game before what could be a game breaking update.  Parts packs aren't usually a big deal, but if a mod has a history of creating problems (Restock, KIS/KAS, TweakScale) I copy/paste the entire install tree and name it something like: "Kerbal Space Program - 1.9.1 - 200416 - Before TweakScale Update".  Only then do I run CKAN.  If I'm really paranoid, I'll use Beyond Compare after the update to compare the newly updated version against my backup to make sure nothing unexpected changed.

Edited April 17, 2020 by Tonka Crash

[bonyetty]

Case 3: ModuleManager)
One little thing is left to mention: "ModuleManager" (MM) is powerful mod on it's own and a common dependency for many other mods but so far, the install instructions don't fit for MMbecause it is distributed as a plain .dll file. Place the "ModuleManager.dll" directly within the "GameData" folder of your game....no sub folder or anything

Where would these elusive thing/s be? now there’s my problem. 

[4x4cheesecake]

1 hour ago, kspnerd122 said:

I would like to say that direct install is much better e.g. planet mod lags the game, remove a few planets,

Depends on how you remove these planets. If you just delete the required files from the mod, you have to do it every time you update the mod, regardless which install process you've used. But if you add a custom MM patch to your game which removes these planets, you don't have to worry about any updates in 99% of the cases (1% chance that a planet got renamed or new planets were added which needs you to adjust the patch).

Of course, you can always handle the modding however it fits the best for you

  

14 minutes ago, Tonka Crash said:

CKAN doesn't do anything automatically without you explicitly telling it to, it just can't.  You have to launch CKAN and tell it to update for it to do anything at all.  My understanding is that Steam will try to keep your game updated by default and this seems to create no end of problems, but CKAN doesn't and never has.

This^

That's why I recommend right at the beginning of this guide to move the game out of the steam directory as well.

 

19 minutes ago, bonyetty said:

Where would these elusive thing/s be? now there’s my problem.

Are my instruction on ModuleManager not clear enough? I could add another picture to make it easier to understand and/or edit the instructions at all if you can explain to me at which point you struggled to follow

[bonyetty]

How does one know what modular manager file/folder to use for a mod? Should modular managers be refers to as the “ModuleManager.dll file” as this is what the thing to be pasted into the GameData folder as this is what is actually needed? How does one know where to find them? .dll ??? Do modulemanagers folders/files have these files in them because I can’t see a.dll in sarbians modulemanager in the master folder or modulemanager file/folder that I downloaded from github. There is a cat folder in there. 

 

just put the key in the slot and go. shhh it’s a key card ba ha ha ha and he is trying to start it with a door key I pointed to. 

[4x4cheesecake]

5 minutes ago, bonyetty said:

How does one know what modular manager file/folder to use for a mod? Should modular managers be refers to as the “ModuleManager.dll file” as this is what the thing to be pasted into the GameData folder as this is what is actually needed? How does one know where to find them? .dll ??? Do modulemanagers folders/files have these files in them because I can’t see a.dll in sarbians modulemanager in the master folder or modulemanager file/folder that I downloaded from github. There is a cat folder in there. 

 

just put the key in the slot and go. shhh it’s a key card ba ha ha ha and he is trying to start it with a door key I pointed to. 

You can find the download link in the ModulManager release thread:

You have to scroll down a bit to find the download link:

Spoiler

 

This is indeed something I haven't covered in my tutorial and I'll add it on the weekend, thanks for pointing it out

[bonyetty]

16 minutes ago, 4x4cheesecake said:

You can find the download link in the ModulManager release thread:

You have to scroll down a bit to find the download link:

  Reveal hidden contents

 

This is indeed something I haven't covered in my tutorial and I'll add it on the weekend, thanks for pointing it out

Yes thank you, 4x4cheese cake also pointed out (and linked) that ModuleManager with the x.x.x.dll is the file needed. Thank you

I am a bit confused why x.x.x.dll appears not to be mentioned or referred to when the mods require the ModuleManager.X.X.X.dll to function, not a folder called ModuleManager? on the other hand it could be my internet blindness

[Stone Blue]

12 hours ago, bonyetty said:

I am a bit confused why x.x.x.dll appears not to be mentioned or referred to when the mods require the ModuleManager.X.X.X.dll to function, not a folder called ModuleManager? on the other hand it could be my internet blindness

I dont quite understand the first part of your question, but most mods include multiple files/folders, so to make it easy to install/remove, they generally come with one, parent folder that contains everything. And generally, you only have to "put" that one folder in your /GameData/ folder.
ModuleManager is just *one* file, so no need to have it in its own folder. So to make it easier, you just have to "put" that one file in your /GameData/ folder.
Plus, when troubleshooting or asking for help with broken mods, using a screenshot of the list of folders (mods) in your /GameData/ folder, its easier for anyone trying to help, to actually *see* the ModuleManager file, and to know *exactly* what version it is, and that its the correct one or not, because the version number is in the file name. vOv

Edited April 17, 2020 by Stone Blue