Install and run KoboldCpp on Windows

Before you start: KoboldCpp Windows checklist

Step 1: Download the right .exe

Old file names in videos and guides

See renamed files.

Check the file’s fingerprint (30 seconds)

In PowerShell, in the folder that holds the file, run Get-FileHash .\koboldcpp.exe -Algorithm SHA256 and compare the result with the hash the picker shows. A mismatch means delete the file and download it again. More in Is KoboldCpp safe?.

Step 2: Put it in its own folder

Create a folder you own, for example C:\KoboldCpp\, and a models folder inside it. KoboldCpp is portable: nothing is registered with Windows unless you register the file association later. Keeping the exe, your .kcpps settings and your models together makes updates simple. We have not yet tested what happens in Program Files or in a OneDrive-synced folder, so use a plain folder you own.

Step 3: First start, and the security prompts

Double-click the file. Windows may show a prompt. The fix is first in each case below.

“Windows protected your PC” (SmartScreen)

Choose More info, then Run anyway, only if the file came from the GitHub release and its hash matches. SmartScreen warns about new or rarely downloaded files and asks once per file. We have not photographed this dialog on a clean Windows 11 yet, so we cannot say whether a publisher name appears.

Microsoft Defender deletes or quarantines the file

Users report detections such as Trojan:Win32/Sabsik.FL.A!ml (#795) and Trojan:Win32/Wacatac.B!ml (#779), and Defender deleting the exe (#1649). In our scan on Windows Server 2025 (13 Nov 2026), Defender found no threats in koboldcpp.exe or koboldcpp-nocuda.exe F38. Our lab machines had real-time protection off, so this says nothing about your machine.

1. Check the source and the hash first.
2. In Windows Security, open Virus and threat protection, then Protection history, and restore the file if the hash matched.
3. Add an exclusion for that one folder only.

Smart App Control blocks it

Users report OSError: [WinError 4551] on koboldcpp_cublas.dll (#1946, #2590). We could not reproduce it on our machines. Options and trade-offs: it won’t start, and the message: WinError 4551.

The first start is slow, and that’s normal

The exe unpacks its libraries to a temporary folder before the launcher appears. On our test machines the small file was ready in 3.5 to 6.6 s with a tiny model and the 600 MB CUDA file in 9 to 12 s F04. Real-PC times are not measured yet. Antivirus scanning can make it much slower (users report).

Step 4: Choose a model and launch

The launcher opens on the Quick Launch tab F30.

Close

1. Backend: CUDA for NVIDIA, Vulkan for AMD and Intel, CPU if you have no GPU (backends).
2. GGUF Text Model: Browse for a file, or use HF Search (Hugging Face, models).
3. Launch.

The defaults that matter: context 16384, GPU layers set automatically and flash attention on F05. The full walkthrough with model choice is in getting started.

Step 5: The firewall prompt and the browser tab

Windows may ask to allow KoboldCpp through the firewall. We have not yet recorded this prompt. The --host default is empty, which, per upstream’s flag description, listens on all network interfaces. Choose what you want: allow on a private network only if you want your phone on your Wi-Fi to reach it (remote access); otherwise cancel (we have not yet recorded what cancel does to local use).

Launch Browser is on by default F30, so your browser opens Kobold Lite. If it does not, open http://localhost:5001. A first-time “Welcome” picker must be closed before a typed prompt is sent F31.

Check it worked

Do not trust the “offloaded N/N layers” line alone F17: see not using the GPU. If something looks wrong, paste the last lines into the log analyzer.

Run it from Command Prompt or PowerShell

If the window closes before you can read it, start KoboldCpp from a terminal so the text stays: how. In the folder’s address bar type cmd, then run:

> koboldcpp.exe --help
> koboldcpp.exe --model "C:\KoboldCpp\models\my model.gguf"

Quote paths that contain spaces. In PowerShell, start a file in the current folder with .\koboldcpp.exe. We have not tested non-ASCII paths. Flags are in flags, and the config builder writes the command for you.

Start it with one click next time

1. Use Save Config in the launcher to write a .kcpps file (.kcpps files), then make a desktop shortcut whose target is the exe, a space, and the path to the .kcpps.
2. Or, on the Extra tab, use the File Extensions Handler to register .kcpps files so that double-clicking one starts KoboldCpp.
3. Or put the command in a .bat file.

A .kcpps given as the only argument is treated as a config, not a model (upstream).

Where KoboldCpp puts files

Lite saves stories in the browser, not on disk. We have not measured whether the unpack folder is removed after a normal close, Ctrl+C, closing the window or killing the process.

Update KoboldCpp

Download the new exe and keep the old one, renamed with its version, until the new one works. The launcher’s Update button only opens the releases page. Releases come often; see the update steps and releases. We have not tested loading an old .kcpps in a new version; upstream says old keys such as usecublas are translated when a config is loaded.

Uninstall KoboldCpp

Nothing appears in Programs and Features. We have not yet recorded which registry entries the association creates.

Windows 10, Windows 11, Windows 7 and ARM

See Windows 7.

If it doesn’t start

Or paste your log into the log analyzer.