User guide

This page explains how to use CKAN to install mods. For help with installing CKAN, see Home#Installing CKAN or find your platform's link in the sidebar →.

Using CKAN

There are three ways to use the CKAN client:

• Using the GUI (most user friendly, default on Windows and Linux)
• Using the console UI (default on macOS) On macOS 10.15 (Catalina) and later, this is the default when you double click the CKAN icon because Apple decided to sunset support for 32-bit applications, leaving no way to run WinForms apps like CKAN's GUI in Mono.
• Using the command line (for advanced users)

If you want to share a modlist with other people, see Sharing a modlist (metapackages).

Using the GUI

To open the GUI on Windows or Linux, run the executable with no arguments.

The first time you open a particular game instance in CKAN, it will ask if you want to check for updates of CKAN automatically, which is recommended so you will always have the latest client version.

Adding game folders

At first startup, CKAN will look for a game folder in the path where Steam normally installs it. If no such folder is found, you will need to tell CKAN where to find your copy of the game. To tell CKAN about your game folder or add more folders later:

1. File → Manage game instances (the popup will appear automatically if CKAN couldn't find the game)

   

2. The Manage Game Instances window will appear. Click New game instance → Add Instance to CKAN

   

3. A file open dialog will appear. Navigate to your game folder and select the game executable file (KSP_x64.exe for KSP1 or KSP2_x64.exe for KSP2).

4. Click Open. The game folder will be added to CKAN's list of known game folders.

5. If you want CKAN to use this folder at startup, select it in the list and check the "Set as default" checkbox

6. Click the Select button and enjoy!

Main mod list

The main screen of the GUI is the list of mods. Click on a mod to see its description, author, version, compatibility, license, relationships with other mods, and more:

The first thing you will want to do is to click the "Refresh" button. This will update CKAN's registry from the online repository to refresh the list of available mods and updates.

Now you can search for mods in the list using the search box at the top. The search looks at identifiers and mod names by default, but it also supports searching by relationships, authors, and more. Click on the small button right next to the search box to show these options.

If you can't find a mod in the list, check your current search filter. To show all indexed mods, even incompatible ones, select the "All" filter. Incompatible mods can be identified by the "-" instead of a checkbox in the first column. If you also want to install an incompatible mod, see Choosing compatible game versions.

A mod shown with "AD" instead of a checkbox in the first column means that CKAN has detected this mod as manually installed. You can let CKAN manage it by "upgrading" the mod.

To install or remove a mod, tick or untick the leftmost checkbox in its row. Below, USI Freight Transport Technologies has been chosen. A new tab now appears called "Changeset". Take note that nothing has been installed yet.

When you click Apply changes or choose the Changeset tab it will show the list of mods you have choosen as well as their dependencies. For USI Freight Transport Technologies this looks as follows:

Click "Apply" to start the installation of the listed mods. If one or more of the mods you are installing also recommends that you install other mods, you will be shown a dialog where you can select them. All of these are optional, so choose what you like and ignore the rest.

After recommendations (if applicable), a new tab will open showing download progress, download speed and any installation messages. After installation is complete, you are ready to run the game with your chosen mods. Should anything go wrong during the installation, CKAN will revert the GameData directory to its previous state, so don't worry about ruining your game.

Choosing compatible game versions

CKAN keeps track of which game versions each mod supports, according to the mod authors. By default, CKAN requires mods to be known compatible with your exact game version to be installed. However, version compatibility is a fuzzy concept, and sometimes a mod may work with more versions than are currently reflected in CKAN. If you wish to make the requirement less strict, you can select additional game versions to be considered compatible:

Games often break mod compatibility, even between minor versions! If you install mods that are not explicitly compatible with your game version, your game may become unstable or raise error messages. Use this feature at your own risk! Do not blanket-select every version!

Using the console UI

You can start the console UI by opening a terminal and running:

ckan consoleui

In general the console UI obeys conventions of DOS applications from the early 1990s. The bottom line of the window describes keystrokes that are currently available, in addition to:

• TAB - Move the focus from one field to the next
• ↑↓←→ - Move the focus up, down, left, or right within the currently focused field
• Alt+X - Quit

In most screens, additional options are available via the hamburger menu, accessed via F10.

For more details, see the documentation from when the console UI was created:

• https://github.com/KSP-CKAN/CKAN/pull/2177

Choosing compatible game versions

1. F10
2. Game instance settings...
3. Press TAB three times to get to the compatible version list
4. Press A and select a new version from the list to add it as compatible

Using the command line

On Windows, follow the instructions from this awesome reddit comment:

1. In the folder where the .exe lives go up one folder
2. Hold Shift and right-click the folder you just left
3. Click "Open command window here"
4. Type ckan.exe help to get started

On Linux or macOS, open a new terminal window, navigate to the folder where you placed ckan.exe, and run:

mono ckan.exe help

Note: on Windows, you don't need Mono provided you have the .NET framework installed (and you most likely have it by default).

Advanced users might like the command line more. If you have already used package managers like pacman or apt-get, you will find ckan familiar.

To run any command, just type

ckan.exe <command>

on your terminal. Note that ckan, like many other package managers, does not run in an interactive session: each command is a self-contained operation.

Here are the commands you will need the most:

• ckan.exe update: refreshes the master list from the CKAN-meta repository, allowing you to find new mods and updates for the packages you have installed.
• ckan.exe scan: scans your GameData folder to find mods that you have installed or removed manually.
• ckan.exe available: lists all the mods available for installation via CKAN.
• ckan.exe list: lists all the mods that CKAN has installed. Will indicate with a caret ^ which mods have new versions available.
• ckan.exe upgrade <identifier>: upgrades the mod to the most recent version, including dependencies.
• ckan.exe upgrade --all: upgrades all mods with newer versions, including dependencies.
• ckan.exe upgrade ckan: upgrades the CKAN client to the newest version.
• ckan.exe show <identifier>: shows information about a mod, such as author, version, and dependencies.
• ckan.exe install <identifier>: installs a package and all its dependencies.
• ckan.exe install <identifier>=<version>: installs a specific version of a package, and all dependencies.

To see the full list of available commands, just run

ckan.exe help

Disk space management

There are three ways CKAN can run out of disk space:

• If your %TEMP% (Windows) or /tmp (Linux or macOS) folder fills up
• If your download cache fills up (chosen in the CKAN settings)
• If your game folder fills up

Depending on how your system is configured, these might all be on the same drive, or each may be on a different device with its own separate free space. There is an option for clearing the cache in the CKAN settings, and you can also specify a maximum cache size to avoid running out of space (CKAN will purge the oldest file when it reaches this limit).

Logging

By default CKAN does not generate a log file. To enable it, save this file to the folder where you run ckan.exe:

https://github.com/KSP-CKAN/CKAN/blob/master/GUI/log4net.xml

This file can be edited with a text editor such as Notepad to customize how the log is generated. All of the standard Apache log4net settings are supported.

Log file name

This line controls the file name to use for logs:

    <file value="./CKAN.log" />

By default the same log file will be appended to each time you run CKAN. It's helpful to isolate each session in its own log file; to achieve this, try replacing the above line with this:

    <file type="log4net.Util.PatternString" value="CKAN-%date{yyyy-MM-dd_HH-mm-ss}.log" />

Logging levels

This line controls the verbosity of the log messages:

    <level value="WARN" />

To change which messages are logged, change WARN to your desired level:

Level	Description
OFF	Nothing will be logged. There is not much point in using this setting.
FATAL	High severity errors that require immediate termination of the program will be logged. A typical session will create a 0-byte file with this setting.
ERROR	Only exceptions and error messages are logged. A typical session will create a 0-byte file with this setting.
WARN	In addition to errors, warnings about unusual conditions will be logged. A typical session will create a 0-byte file with this setting. This is the default in the log4net.xml file linked above.
INFO	Basic summary messages are logged. A typical session results in 1-300 kilobytes of logs with this setting.
DEBUG	Verbose details of every operation are logged. A typical session generates 30+ MB of logs and run significantly more slowly with this setting.
ALL	Drink from the firehose.

tl;dr: Use INFO.

Known issues

You can click here to see a list of all issues we're currently tracking that we have confirmed as bugs. To see all issues (confirmed and unconfirmed bugs alike) click here.

If you have any trouble, remember that we are happy to help you on the Discord server!