User guide
In this page you will learn how to install CKAN and use it to install your first mod. Please note that CKAN is still under active development and that the information on this page might be out of date.
The CKAN client is heavily inspired by the many package management utilities available on Unix platforms: you might be already familiar with one of them.
NOTE: If you're upgrading from a previous CKAN version you only have to replace your ckan.exe with the new one.
Installing the client is very easy: just head to our releases and download the latest version of ckan.exe.
You don't have to worry about platforms: CKAN is built using Mono, so it will work the same on Windows, Mac or Linux. Even though it's a .exe file, it will still work, thanks to Mono!
Note: Mono, like .Net, runs on a VM platform similar to (and inspired by) JVM. Mono executables will run on any platform that has Mono installed, just as Java executables can be run on any platform that a JVM is present. To illustrate this, running ckan.exe may be performed with mono ckan.exe, but it is not required by most systems.
Just place the executable in any folder you like: the client can manage all your KSP installations from anywhere on your disk, so you don't have to worry about its location.
NOTES:
- If you're running Ubuntu, please check out our Installing CKAN on Ubuntu guide.
- If you're running macOS, please check out our Installing CKAN on macOS guide.
- If you're running Archlinux, you can use ckan or ckan-git from AUR
There are three ways to use the client:
- Using the GUI (default on Windows and Linux)
- Using the console UI (default on macOS)
- Using the command line
While the GUI is certainly the easiest option, advanced users might feel more comfortable using the command line.
To open the GUI on Windows or Linux, run the executable you have downloaded with no arguments. From here you can:
- See all the available packages
- Click on a package to see its description: author, version, license, relationship with other packages, and more
- Manage and launch any KSP installation
When you first launch CKAN, it will ask if you want to use auto-updates which is recommended to always have the latest client version. After that a dialog window will appear after CKAN has scanned your system to find your KSP installation directory: if for any reason it's unable to find it on its own, or if you want to manage another installation, you can just add another using the "Add new" button. Browse to your KSP installation and select the buildID.txt or buildID64.txt file, then click Open (see Adding game folders).
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 on the bottom. The search is not limited to identifiers and mod names, 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, make sure to check your filter settings. To show all indexed mods, even incompatible ones, select the "All" filter. If you also want to install an incompatible mod, see Choosing compatible game versions.
To install (or remove) a mod, just tick (or untick) the corresponding checkbox. In the picture, USI Freight Transport Technologies have been chosen. A new tab now appears called "Changeset". Take note that nothing has been installed yet.
When you click on 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.
By clicking "Apply", you will start the installation of the listed mods and a new tab will open up showing download progress, download speed and any installation messages. After installation is complete everything will work out of the box!
Should anything go wrong during the installation, CKAN will revert the GameData directory to its previous state, so don't worry about ruining your installation!
If one or more of the mods you are installing also recommends that you install other packages you will be shown a series of dialogs where you can select them: all of these are optional, so feel free to choose what you like and ignore the rest.
At first startup, CKAN will look for a KSP folder in the path where Steam normally stores it. If it finds one, it will use that folder. If you want to use a game folder in an alternate location, follow these steps:
-
File → Manage KSP Instances
-
The Manage KSP Instances window will appear. Click New KSP instance → Add Instance to CKAN
-
A file open dialog will appear. Navigate to your KSP folder and select the buildID.txt or buildID64.txt file.
-
Click Open. Your new game folder will be added to the list that CKAN knows about.
-
If you want CKAN to use this folder at startup, select it in the list and check the "Set as default" checkbox
-
Click the Select button and enjoy!
By default, CKAN requires mods to be compatible with your exact game version. 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:
However, remember that KSP often breaks 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!
You can start the console UI by opening a terminal and running:
ckan consoleui
On macOS 10.15 (Catalina) and later, console UI 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.
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
- Arrows - 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:
- F10
- Select KSP install...
- Pick your install
- Press 'e' to edit
- Tab a few times to get to the compatible version list
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
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.
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" />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.
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!