koboldcpp.dev

Every KoboldCpp flag, with defaults and history

Run KoboldCpp with --help to list its flags; this page lists all of them for the current version in one searchable table, with each flag's default, accepted values, the launcher field that sets it, and the version that added it. The most used are --model, --contextsize, --gpulayers, --usecuda or --usevulkan, --port and --config. Old names like --usecublas and --blasbatchsize still work as aliases; --useclblast was removed.

Checked against KoboldCpp 1.124.2 · updated 13 Nov 2026
  • lab-lnx: Linux test VM · 4 vCPU · 15 GB · no GPU
  • gha-w25: Windows Server 2025 test machine · 4 vCPU · 16 GB · no GPU
  • gha-w22: Windows Server 2022 test machine · 4 vCPU · 16 GB · no GPU
  • gha-u24: Ubuntu 24.04 test machine · 4 vCPU · 16 GB · no GPU
  • gha-mac15: macOS 15 test VM (Apple Silicon) · 3 vCPU · 7 GB · paravirtual Metal
How we test
On this page
  1. KoboldCpp flags: how to pass them
  2. The flags most people need
  3. Renamed, deprecated and removed flags
  4. Flags whose launcher box says the opposite
  5. Command line vs launcher vs .kcpps: which wins
  6. Environment variables
  7. Things that are not flags
  8. Utility modes
  9. How this table is kept current

Checked against KoboldCpp 1.124.2: the table below lists 183 entries, including 2 positional arguments. It is generated from the program’s own argument parser, and the summaries are our own words.

Every KoboldCpp flag
model_param–Positional—–––currentBare model path given without a flag (e.g. `koboldcpp model.gguf`). Kept for backward compatibility; a .kcpps/.kcppt path here is treated as a config.–
port_param–Positional5001–––currentBare port number given as the second positional argument. Same effect as --port.–
--usecuda--usecublas --usehipblasCore options—0 | 1 | 2 | 3 | all | mmq | nommq | normal | lowvram | rowsplitQuick Launch › Backendv1.33deprecatedSelects the NVIDIA CUDA backend (or hipBLAS/ROCm in ROCm builds). Optionally give a GPU index or 'all'; legacy sub-options (mmq/nommq/lowvram/rowsplit) are still parsed and translated into the newer flags.F17
--usevulkan–Core options—[Device IDs]Quick Launch › Backendv1.56currentSelects the Vulkan backend, which works on NVIDIA, AMD and Intel GPUs. Optionally list device indices; leave empty to auto-detect.F17
--usecpu–Core optionsoff–Quick Launch › Backendv1.75currentForces CPU-only inference with no GPU backend. Replaces the old --noblas.F17
--model-mCore options—[filenames]Quick Launch › GGUF Text Model + "HF Search" buttonv1.8currentPath(s) or URL(s) of the GGUF/GGML text model. Several values are only accepted when they are URLs (split model parts); URLs are downloaded first.–
--config–Core options—[filename]–v1.41currentLoads a .kcpps settings file (or .kcppt template, also from a URL). Anything you also pass on the command line wins over the file.F08
--contextsize--ctx-size -cCore options16384[256 to 524288]Quick Launch › Context Sizev1.20currentMaximum context window in tokens to allocate (256-524288). Bigger values need more RAM/VRAM; default 16384 in 1.124.F05 F06 F22
--gpulayers--gpu-layers --n-gpu-layers -nglCore options-1[GPU layers]Quick Launch › GPU Layersv1.23betacurrentHow many model layers to offload to the GPU. -1 (default) turns on autofit; 0 keeps everything on the CPU.F05 F41
--host–Core options—[ipaddr]Network › Host / Portv1.0.8betacurrentIP address to bind the HTTP server to. Empty (default) listens on all interfaces; use 127.0.0.1 for local-only.–
--launch–Core optionsoff–Quick Launch › Launch Browserv1.10currentOpens your web browser on the UI once the model has loaded.–
--tensor_split--tensorsplit --tensor-split -tsCore options—[Ratios]–v1.37currentFor CUDA/Vulkan multi-GPU: space-separated proportions for how much of the model each GPU gets, e.g. `7 3`.–
--threads-tCore optionsauto machine-dependent (physical cores)[threads]Hardware › Threadsv1.0.8betacurrentCPU threads used for generation. Default is computed from your physical core count (the value shown in --help is machine-specific).F07
--port–Core options5001[portnumber]Network › Host / Portv1.0.8betacurrentTCP port for the web UI and all APIs. Default 5001.F05
--version–Core optionsoff––v1.82currentPrints the KoboldCpp version and exits.–
--noblas–Core optionsoff––v1.0.8betadeprecatedHidden legacy flag: old way to disable BLAS; now mapped to --usecpu.–
--agent–Advancedoff–Agent › Launch KoboldCpp Agentv1.122currentStarts the bundled KoboldCpp Agent (tool-using assistant for code and tasks) in a new terminal window, or in the current one when combined with --cli. Forces Jinja and raises context/gen defaults.–
--agentload–Advanced—[filename]Agent › Load Agent Sessionv1.123currentResumes a saved KoboldCpp Agent session from its JSON save file when the agent starts.–
--analyze–Advanced—[filename]–v1.82currentPrints metadata, tensor names and weight types of a GGUF or safetensors file, then exits.–
--autofit--fit -fitAdvancedoff–Quick Launch › Force AutoFitv1.104currentForces automatic fitting of the model across GPU(s)/CPU (layers, MoE overrides, splits), overriding manual layer settings.–
--autofitpadding–Advanced1024[padding in MB]Hardware › Autofit Paddingv1.108currentSpare VRAM in MB that autofit leaves free as a safety margin (default 1024).–
--batchsize--blasbatchsize --batch-size -bAdvanced512-1 | 16 | 32 | 64 | 128 | 256 | 512 | 1024 | 2048 | 4096Hardware › Batch Sizev1.8deprecatedLogical batch size for prompt processing (default 512). Larger is faster but uses more memory; -1 turns batching off. Formerly --blasbatchsize.–
--ubatchsize--ubatch-size -ubAdvanced-1-1 | 16 | 32 | 64 | 128 | 256 | 512 | 1024 | 2048 | 4096Hardware › Physical Batch Sizev1.122currentPhysical micro-batch size inside each batch. -1 (default) means same as --batchsize; lower it to save memory.–
--benchmark–Advanced—[filename]Hardware › Run Benchmarkv1.57currentRuns a benchmark instead of starting the server; optionally appends results to a CSV file.F16
--blasthreads--batchthreads --threadsbatch --threads-batchAdvanced0[threads]Hardware › Batch Threadsv1.19currentThread count used during batched prompt processing; defaults to the --threads value.–
--chatcompletionsadapter–AdvancedAutoGuess[filename]Loaded Files › Chat Adapter + "Pick Premade"v1.62currentInstruct-template adapter (JSON file or bundled name such as ChatML, Llama-3) used to format /v1/chat/completions prompts. Default AutoGuess detects it from the model.–
--cli–Advancedoff–Hardware › CLI Terminal Onlyv1.87currentRuns an interactive chat in the terminal with no HTTP server. With --agent, runs the agent in the same terminal.–
--debugmode–Advanced0–Hardware › Debug Modev1.15currentExtra diagnostic output: -1 quiet (used for Horde), 0 normal, 1 verbose, higher for more detail.–
--defaultgenamt–Advanced2048–Context › Default Gen Amtv1.86.1currentTokens to generate when a request does not specify a length (default 2048). Most frontends send their own value.–
--device-devAdvanced—<dev1,dev2,..>Hardware › Device Overridev1.106.1currentllama.cpp-style comma-separated device list (e.g. Vulkan0,Vulkan1) that overrides the normal GPU selection.–
--downloaddir–Advanced—[directory]Loaded Files › Download Dirv1.107.2currentFolder where models given as URLs are downloaded to and looked up in (default: working directory).–
--draftamount--draft-max --draft-n --spec-draft-n-maxAdvanced4[tokens]Loaded Files › Draft Amount / Splits / Layersv1.79currentNumber of tokens the draft model proposes per step in speculative decoding (default 4).–
--draftgpulayers--gpu-layers-draft --n-gpu-layers-draft -ngldAdvanced999[layers]Loaded Files › Draft Amount / Splits / Layersv1.80currentGPU layers for the draft model (default 999 = fully offloaded).–
--draftgpusplit–Advanced—[Ratios]Loaded Files › Draft Amount / Splits / Layersv1.80currentMulti-GPU split ratios for the draft model; only applies when the main model is split with --tensor_split.–
--draftmodel--model-draft -mdAdvanced—[filename]Loaded Files › Draft Modelv1.79currentSmall model with the same vocabulary as the main model, used for speculative decoding to speed up generation.–
--enableguidance–Advancedoff–Context › Enable Guidancev1.91currentTurns on classifier-free guidance so negative prompts work for text; costs speed and memory.–
--exportconfig–Advanced—[filename]–v1.85.1currentWrites the current arguments to a .kcpps file (then exits) for reuse with --config.F08
--exporttemplate–Advanced—[filename]–v1.85.1currentWrites the current arguments as a shareable .kcppt template with machine-specific settings stripped.–
--failsafe–Advancedoff–Quick Launch › Backendv1.80currentMaximum-compatibility mode for very old CPUs (no AVX); implies --noavx2. Very slow.F15
--foreground–Advancedoff–Hardware › Keep Foregroundv1.45currentWindows only: brings the console window to the front on each new generation to avoid idle slowdowns.–
--gendefaults–Advanced—{"parameter":"value",...}Context › Default Paramsv1.105currentJSON object of default generation fields added to API requests that don't set them, e.g. {"temperature":0.7}.–
--gendefaultsoverwrite–Advancedoff–Context › Default Paramsv1.105currentMakes --gendefaults values override what clients send instead of only filling gaps.–
--genlimit--promptlimitAdvanced0[token limit]Context › Prompt Limitv1.73deprecatedHard cap on generated tokens for every request (0 = no cap). Formerly --promptlimit.–
--highpriority–Advancedoff–Hardware › High Priorityv1.18currentRaises the process CPU priority. Experimental; can cause system lag.–
--ignoremissing–Advancedoff––v1.61.2currentSkips optional files (LoRA, mmproj, etc.) that cannot be found instead of aborting.–
--jinja--jinja_tools --jinja-tools --jinjatoolsAdvancedoff–Quick Launch › Use Jinjav1.102deprecatedUses the model's embedded Jinja chat template (including tool calls) for chat completions, falling back to KoboldCpp's universal formatting if it fails. Since 1.123 also covers the former --jinjatools.–
--jinja_kwargs--jinja-kwargs --jinjakwargs --chat-template-kwargsAdvanced—{"parameter":"value",...}–v1.111currentExtra JSON variables passed into the Jinja template renderer (llama.cpp's --chat-template-kwargs).–
--jinjatemplate--chat-template-fileAdvanced—[filename]Loaded Files › Jinja Templatev1.112currentPath to a custom .jinja chat template that replaces the model's own.–
--jinjathink–Advanceddefaultdefault | true | falseContext › Jinja Thinkingv1.114currentQuick switch for thinking/reasoning in Jinja templates: default, true or false. Setting it enables Jinja.–
--lora–Advanced—[lora_filename]Loaded Files › Text Lora + Multiplierv1.11currentApplies a text LoRA (GGUF) on top of the base model.–
--loramult–Advanced1[amount]Loaded Files › Text Lora + Multiplierv1.93currentStrength multiplier for the text LoRA (default 1.0).–
--lowvram-nkvo --no-kv-offloadAdvancedoff–Hardware › No KV offloadv1.100currentKeeps the KV cache in system RAM instead of VRAM (llama.cpp -nkvo). Fits more layers but is slow.F42
--maingpu--main-gpu -mgAdvanced-1[Device ID]Hardware › Main GPUv1.94currentIn multi-GPU setups, index of the GPU used as the main device (-1 = default).–
--maxrequestsize–Advanced32[size in MB]Network › Max Req. Sizev1.88currentLargest HTTP request body accepted, in MB (default 32); bigger requests are dropped.–
--mcpfile–Advanced—[mcp json file]Loaded Files › MCP JSONv1.106currentPath to a Claude-Desktop-format mcp.json listing MCP tool servers (HTTP or stdio) to expose to the UI and agent.–
--mmproj–Advanced—[filename]Loaded Files › Mmproj Filev1.61currentMultimodal projector GGUF that adds image (and for some models audio) understanding to a compatible text model.–
--mmprojcpu--no-mmproj-offloadAdvancedoff–Loaded Files › V.Force CPUv1.90currentKeeps the vision/audio projector on the CPU even when the main model is on GPU.–
--lazy-mode--lazymodeAdvancedautoauto | on | offContext › Lazy Tensorsv1.124currentControls on-demand reading of large architecture-specific tensors (e.g. per-layer embeddings): auto (>4 GiB), on, or off.–
--moe-cache-mib--moecacheAdvanced0MiBContext › MoE Cache MiBv1.124currentExperimental VRAM cache (MiB) for MoE experts that otherwise live on the CPU; use with --moecpu or --autofit.–
--moecpu--n-cpu-moe -ncmoeAdvanced0[layers affected]Context › MoE CPU Layersv1.97currentKeeps the MoE expert weights of the first N layers (all if no number) in system RAM, freeing VRAM for big MoE models.–
--ffncpu--n-cpu-ffn -ncffnAdvanced0[layers affected]Context › FFN CPU Layersv1.121currentLike --moecpu but for dense FFN weights of the first N layers.–
--moeexperts–Advanced-1[num of experts]Context › MoE Expertsv1.80currentOverrides how many experts are active per token in MoE models (-1 = model default).–
--multiplayer–Advancedoff–Network › Shared Multiplayerv1.79currentHosts a shared Kobold Lite session that several users can join and edit together.–
--nocertify–Advancedoff–Network › NoCertify Modev1.59currentDisables SSL certificate verification for outgoing connections (e.g. the Horde worker). Insecure.–
--nofastforward–Advancedoff–Context › Use FastForwardingv1.78currentDisables fast-forwarding, so every prompt is fully reprocessed; also disables context shift.–
--noflashattention--no-flash-attn -nofaAdvancedoff–Quick Launch › Use FlashAttentionv1.107currentTurns off flash attention, which is on by default since 1.107.F09
--noavx2–Advancedoff–Quick Launch › Backendv1.5currentUses the slower non-AVX2 library for older CPUs (with Vulkan if requested).F15
--nobostoken–Advancedoff–Context › No BOS Tokenv1.86.1currentStops the BOS token being prepended to prompts. Rarely needed.–
--nommq–Advancedoff–Quick Launch › Use MMQv1.113currentCUDA only: disables quantized matrix-multiplication (MMQ) kernels.–
--nomodel–Advancedoff–Loaded Files › Allow Launch Without Modelsv1.74currentStarts the server/UI without loading any model (e.g. to use the UI with Horde or a remote API).–
--noshift--no-context-shiftAdvancedoff–Quick Launch › Use ContextShiftv1.48currentDisables ContextShift (KV-cache shifting when the context is full).–
--noswa--swa-fullAdvancedoff–Context › Allow SWAv1.114currentUses a full-size KV cache instead of sliding-window attention on models that support SWA. Needed if you want context shifting on such models.–
--onready–Advanced—[shell command]–v1.44currentShell command to run once the model has loaded (e.g. start a tunnel). Ignored when it comes from a config file unless --allow-config-onready is set.–
--allow-config-onready–Advancedoff––v1.116currentLets configs loaded after launch (admin swaps) set --onready. Only for trusted configs.–
--overridekv--override-kvAdvanced—[name=type:value]Context › Override KVv1.89currentOverrides GGUF metadata keys, format name=type:value, comma-separated (llama.cpp --override-kv).–
--overridenativecontext–Advanced0[trained context]Context › Custom RoPE Config / Manual Rope Scale, RoPE Scale, Base, Override Native Contextv1.98currentPretends the model was trained on this context length when computing RoPE scaling.–
--overridetensors--override-tensor -otAdvanced—[tensor name pattern=buffer type]Context › Override Tensorsv1.89currentPlaces tensors matching a regex on a chosen backend buffer (llama.cpp -ot), e.g. to push experts to CPU.–
--parallelrequests--continuous-batching --contbatchAdvanced1[slots]Network › Parallel Requests / Parallel Total Contextv1.113currentNumber of generation slots that can run at once (experimental continuous batching). Default 1.F26
--paralleltotalcontext--parallel-total-contextAdvanced0[tokens]Network › Parallel Requests / Parallel Total Contextv1.124currentTotal KV budget in tokens shared by all parallel slots; defaults to --contextsize.–
--password–Advanced—[API key]Network › Passwordv1.61currentAPI key that clients must send to use text endpoints (image endpoints are not protected). Also settable via KCPP_PASSWORD.F25
--preloadstory–Advanced—[savefile]Loaded Files › Preload Storyv1.49currentServes a saved story JSON at /api/extra/preloadstory so Kobold Lite opens with it.–
--prompt-pAdvanced—[prompt]–v1.73currentRuns a single prompt, prints the reply to stdout and exits (can be combined with --benchmark).–
--quantkv–Advancedf16f16 | bf16 | q8_0 | q5_1 | q4_0 | 0 | 1 | 2 | 3Context › Quantize KV Cachev1.67deprecatedKV-cache data type: f16 (default), bf16, q8_0, q5_1 or q4_0. Quantizing saves memory; without flash attention only K is quantized. Old numeric values 0-3 still accepted.F10
--queuelimit–Advanced10limitNetwork › Queue Limitv1.123currentMaximum number of requests allowed to wait in the queue (default 10).–
--quiet–Advancedoff–Quick Launch › Quiet Modev1.51currentHides prompts and generated text from the console (auto-on for Horde workers).–
--ratelimit–Advanced0[seconds]Network › IP Rate Limiterv1.99currentPer-IP rate limit: each IP may start a new generation only every N seconds (0 = off).–
--reasoningeffort–Advanceddefaultdefault | none | low | medium | high | xhighContext › Think Effortv1.115currentDefault reasoning effort for thinking models (none/low/medium/high/xhigh); API requests can override it.–
--remotetunnel–Advancedoff–Quick Launch › Remote Tunnelv1.48currentDownloads cloudflared and opens a trycloudflare.com tunnel so the instance is reachable from the internet without port forwarding.–
--ropeconfig–Advanced0 10000[rope-freq-scale],[rope-freq-base]–v1.36currentManual RoPE scaling: frequency scale then frequency base (e.g. 0.25 10000). Without it, scaling is set automatically.–
--savedatafile–Advanced—[savefile]Loaded Files › SaveData File + "Enable Server Side SaveData File"v1.85.1currentServer-side save database (.jsondb) so users can save/load stories to the server.–
--singleinstance–Advancedoff–Admin › SingleInstance Modev1.93currentLets a newly started instance on the same port shut this one down, avoiding port clashes.–
--smartcache–Advanced0limit–v1.104currentKeeps KV-cache snapshots in RAM (optionally N slots) so switching between chats avoids full reprocessing. Requires fast-forwarding.–
--smartcontext–Advancedoff–Context › Use SmartContextv1.7deprecatedLegacy context-reuse trick that reserves part of the context; superseded by ContextShift and not recommended.–
--splitmode-sm --split-modeAdvancedlayerlayer | row | tensorHardware › SplitModev1.113deprecatedHow the model is split across GPUs: layer (default) or tensor (experimental). 'row' is still accepted but, since row split was removed in v1.118, it prints a warning and is treated as tensor split (splitmode_choices_to_int @ v1.124.2).–
--ssl–Advanced—[cert_pem],[key_pem]–v1.53currentServes HTTPS using an unencrypted certificate and key PEM file.–
--swapadding–Advanced0–Context › SWA Padding Tokensv1.112currentExtra tokens of padding for the SWA KV cache, which controls how far you can rewind before forced reprocessing.–
--unpack–Advanced—destination–v1.70currentExtracts the bundled files of the single-file binary into a folder (for running from source/unpacked).–
--usemtp–Advancedoff–Loaded Files › Use MTPv1.115currentUses a model's built-in multi-token-prediction layers as the draft for speculative decoding, if present.–
--usemlock--mlockAdvancedoff–Hardware › Use mlockv1.18currentLocks the model in RAM so the OS cannot swap it out.–
--usemmap–Advancedoff–Quick Launch › Use MMAPv1.3currentMemory-maps the model file instead of reading it fully. Off by default since 1.82.F12
--usedirectio--directio --direct-io -dioAdvancedoff–Hardware › Direct I/Ov1.120currentLoads GGUF files with direct I/O, which can speed up cold loads on some disks.–
--visionmaxres–Advanced1024[max px]Loaded Files › Vision MaxResv1.83currentMaximum image resolution fed to the vision projector (512-2048, default 1024).–
--visionmaxtokens--image-max-tokensAdvanced-1[tokens]Loaded Files › V.Min/Max Tokv1.112currentOverrides the maximum number of embedding tokens per image (-1 = model default).–
--visionmintokens--image-min-tokensAdvanced-1[tokens]Loaded Files › V.Min/Max Tokv1.112currentOverrides the minimum number of embedding tokens per image (-1 = model default).–
--websearch–Advancedoff–Network › Enable WebSearchv1.81currentEnables the built-in web search proxy (DuckDuckGo) used by Kobold Lite and the agent.–
--showgui–Advancedoff––v1.75currentShows the GUI launcher even when a config was passed, pre-filled with those settings.–
--skiplauncher–Advancedoff––v1.15currentNever shows the GUI launcher (headless start); overrides --showgui.–
--nommap--no-mmapAdvancedoff––v1.4deprecatedHidden legacy flag from when mmap was the default.–
--hordemodelname–Horde worker—[name]Horde Worker › Horde Model Namev1.65currentModel name your AI Horde worker advertises.–
--hordeworkername–Horde worker—[name]Horde Worker › Horde Worker Namev1.65currentName of your AI Horde worker.–
--hordekey–Horde worker—[apikey]Horde Worker › API Keyv1.65currentYour AI Horde API key; setting it (with names) starts the embedded Horde worker.–
--hordemaxctx–Horde worker0[amount]Horde Worker › Max Contextv1.65currentLargest context your Horde worker accepts (0 = same as --contextsize).–
--hordegenlen–Horde worker0[amount]Horde Worker › Gen. Lengthv1.65currentMost tokens your Horde worker will generate per job.–
--sdaudiovae–Image generation—[filename]Image Gen › Audio VAEv1.114currentAudio VAE used by LTX 2.3 video generation (video with sound).–
--sdclamped–Image generation0[maxres]Image Gen › Clamp Resolutionv1.65currentShared-server safety: caps image steps and size (optional max side length, min 512).–
--sdclampedsoft–Image generation0[maxres]Image Gen › Clamp Resolutionv1.94currentCaps total image area (e.g. 640 allows 640x640 or 512x768) to limit memory use.–
--sdclip1--sdcliplImage generation—[filename]Image Gen › Clip-1 File / Clip-2 Filev1.78deprecatedFirst CLIP text encoder file (e.g. CLIP-L) if not baked into the image model. Formerly --sdclipl.–
--sdclip2--sdclipgImage generation—[filename]Image Gen › Clip-1 File / Clip-2 Filev1.78deprecatedSecond CLIP encoder (e.g. CLIP-G) or tokenizer file. Formerly --sdclipg.–
--sdclipdevice–Image generation—[Device ID]Image Gen › VAE dev / CLIP devv1.114currentWhere image text encoders/LLM run: GPU index, main, or CPU (default CPU).–
--sdconvdirect–Image generationoffoff | vaeonly | fullImage Gen › Conv2D Directv1.98currentConv2D direct mode for image generation: off (default), vaeonly or full. May save memory or crash on some backends.–
--sdflashattention–Image generationoff–Image Gen › SD Flash Attentionv1.98currentUses flash attention in image/video generation.–
--sdlora–Image generation—[filename]Image Gen › Runtime LoRAs toggle; Image LoRAs + Multiplier, or LoRA Dirv1.66currentImage LoRA files (or a folder for runtime LoRAs) to apply.–
--sdloramult–Image generation1[amounts]Image Gen › Runtime LoRAs toggle; Image LoRAs + Multiplier, or LoRA Dirv1.66currentStrength multiplier(s) for the image LoRAs.–
--sdmaingpu–Image generation—[Device ID]Image Gen › ImgGPUv1.111currentGPU (index, main or CPU) that holds the image-generation weights.–
--sdmodel–Image generation—[filename]Image Gen › Image Modelv1.65currentImage/video model (safetensors or GGUF) to enable image generation: SD1.5, SDXL, SD3, Flux, Qwen Image, WAN, etc.–
--sdoffloadcpu–Image generationoff–Image Gen › Model Offloadv1.100currentKeeps image weights in RAM and moves them to VRAM only when needed.–
--sdphotomaker–Image generation—[filename]Image Gen › PhotoMakerv1.94currentPhotoMaker model for face cloning with SDXL models.–
--sdquant–Image generation00 | 1 | 2Image Gen › Compress Weightsv1.65currentQuantize the image model on load to save memory: 0 off, 1 q8, 2 q4.–
--sdllm–Image generation—[filename]Image Gen › Image LLMv1.122currentText encoder or LLM used by newer image models (T5-XXL, Qwen, etc.). Replaces --sdt5xxl.–
--sdthreads–Image generation0[threads]Image Gen › ImgThreadsv1.65currentCPU threads for image generation (default: same as --threads).–
--sdtiledvae–Image generation512[maxres]Image Gen › VAE Tiling Thresholdv1.94currentImage size above which VAE decoding is tiled to save memory (default 512; 0 disables).–
--sdupscaler–Image generation—[filename]Image Gen › Upscalerv1.107currentESRGAN upscaler model for enlarging generated images.–
--sdvae–Image generation—[filename]Image Gen › Image VAEv1.66currentCustom VAE that replaces the one inside the image model.–
--sdvaeauto–Image generationoff–Image Gen › Automatic VAEv1.66currentUses the bundled tiny TAESD VAE: very fast, also fixes broken VAEs.–
--sdvaedevice–Image generation—[Device ID]Image Gen › VAE dev / CLIP devv1.114currentWhere the image VAE runs: GPU index, main (default) or CPU.–
--sdvramlimit–Image generation0[limit MB]Image Gen › VRAM Limiterv1.115currentCaps VRAM use of image generation to this many MB.–
--whispermodel–Whisper—[filename]Audio › Audio Transcriptionv1.67currentWhisper .bin model for speech-to-text, or a SheetSage2 GGUF for music-to-ABC transcription.–
--ttsmodel–TTS—[filename]Audio › TTS Modelv1.82currentText-to-speech GGUF model (Kokoro, OuteTTS, Qwen3-TTS, Parler, Dia, etc.).–
--ttswavtokenizer–TTS—[filename]Audio › WavTokenizer Modelv1.82currentWavTokenizer/codec GGUF required by some TTS models (OuteTTS, Qwen3-TTS).–
--ttsgpu–TTSoff–Audio › TTS Use GPUv1.82currentRuns the TTS model on the GPU.–
--ttsmaxlen–TTS4096–Audio › TTS Threads / TTS Max Tokensv1.83currentMaximum audio tokens generated per TTS request (default 4096).–
--ttsthreads–TTS0[threads]Audio › TTS Threads / TTS Max Tokensv1.82currentCPU threads for TTS (default: same as --threads).–
--ttsdir–TTS—[directory]Audio › TTS Voices Dirv1.109currentFolder of reference voice samples for TTS voice cloning.–
--musicllm–Music—[filename]Audio › MusicLLM / MusicEmbeds / MusicDiffuser / MusicVAEv1.109currentMusic language model (ACE-Step LM or YuE2) for music generation.–
--musicembeddings–Music—[filename]Audio › MusicLLM / MusicEmbeds / MusicDiffuser / MusicVAEv1.109currentText embedding model used by music generation (e.g. Qwen3-Embedding-0.6B).–
--musicdiffusion–Music—[filename]Audio › MusicLLM / MusicEmbeds / MusicDiffuser / MusicVAEv1.109currentMusic diffusion (DiT) model, e.g. ACE-Step v1.5 turbo.–
--musicvae–Music—[filename]Audio › MusicLLM / MusicEmbeds / MusicDiffuser / MusicVAEv1.109currentMusic VAE / audio decoder model.–
--musiclowvram–Musicoff–Audio › Music Low VRAMv1.109currentUnloads music models when not generating to save VRAM.–
--embeddingsmodel–Embeddings—[filename]Loaded Files › Embeds Model + ECtx + GPUv1.87currentGGUF embedding model to serve /v1/embeddings and /api/extra/embeddings.–
--embeddingsmaxctx–Embeddings4096[amount]Loaded Files › Embeds Model + ECtx + GPUv1.93.2currentOverrides the maximum context of the embeddings model.–
--embeddingsgpu–Embeddingsoff–Loaded Files › Embeds Model + ECtx + GPUv1.94currentOffloads the embeddings model to the GPU.–
--rpcmode–RPCdisableddisabled | connect | hostNetwork › RPC Modev1.114currentRPC GPU sharing over the network: disabled, connect (use remote GPUs) or host (share yours).–
--rpcport–RPC5551[portnumber]Network › RPC Host IP / Port / Devices / Cachev1.114currentPort the RPC server listens on in host mode (default 5551).–
--rpchost–RPC0.0.0.0[IP address]Network › RPC Host IP / Port / Devices / Cachev1.114currentIP the RPC server binds to in host mode (default 0.0.0.0).–
--rpcdevice–RPC—<dev1,dev2,..>Network › RPC Host IP / Port / Devices / Cachev1.114currentComma-separated devices exposed by the RPC host.–
--rpccache–RPC—<directory>Network › RPC Host IP / Port / Devices / Cachev1.124currentHost mode: folder where tensors sent by clients are cached so reloading the same model is faster. Never cleaned; trust all clients.–
--rpctargets–RPC—[remotehost1:port1,remotehost2:port2]Network › RPC Endpointsv1.114currentConnect mode: comma-separated host:port list of remote RPC servers.–
--admin–Administrationoff–Admin › Enable Model Administrationv1.83currentEnables admin mode: models/configs can be unloaded and swapped at runtime from the UI or admin API.–
--adminpassword–Administration—[password]Admin › Admin Passwordv1.83currentPassword protecting admin functions (strongly advised on public instances). Also via KCPP_ADMINPASSWORD.–
--admindir–Administration—[directory]Admin › Config Directoryv1.83currentFolder of .kcpps/.kcppt/.gguf files that admin mode may switch between.–
--adminunloadtimeout–Administration0–Admin › Auto Unload Timeoutv1.110currentSeconds of idleness after which the current model is unloaded automatically (0 = never).–
--routermode–Administrationoff–Admin › Router Modev1.110currentReverse-proxy router that swaps to the model named in each OpenAI-API request, then answers it. Requires --admin.–
--reqtimeout–Administration600[seconds]Network › Request Timeoutv1.113currentHTTP request timeout in seconds (default 600; 0 = library default).–
--autoswapmode–Administrationoff–Admin › Autoswap Modev1.111currentOn top of router mode, automatically switches between the model types defined in one config (text, image, audio...) as requests arrive.–
--autoswapthreshold–Administration256–Admin › Autoswap Thresholdv1.122currentIn autoswap mode, model families up to this size (MB, default 256) stay loaded; only one larger family is resident at a time.–
--baseconfig–Administration—–Admin › Base config .kcppsv1.112currentBase .kcpps applied during admin model swaps when no other base is chosen.–
--hordeconfig–Deprecated—––v1.28deprecatedDeprecated (1.65): old combined Horde settings; translated to the --horde* flags.–
--sdconfig–Deprecated—––v1.60deprecatedDeprecated (1.65): old combined image settings; translated to --sdmodel etc.–
--nopipelineparallel–Deprecatedoff––v1.107deprecatedDeprecated (1.122): pipeline parallelism is now decided automatically.–
--pipelineparallel–Deprecatedoff––v1.104deprecatedDeprecated (1.107): replaced by --nopipelineparallel, itself later deprecated.–
--sdnotile–Deprecatedoff––v1.82deprecatedDeprecated (1.94): use --sdtiledvae 0.–
--sdt5xxl–Deprecated—[filename]–v1.78deprecatedDeprecated (1.122): converted to --sdllm.–
--sdvaecpu–Deprecatedoff––v1.100deprecatedDeprecated (1.114): use --sdvaedevice CPU.–
--sdclipgpu–Deprecatedoff––v1.100deprecatedDeprecated (1.114): use --sdclipdevice.–
--forceversion–Deprecatedoff––v1.19deprecatedDeprecated (1.104): forced a legacy GGML file version; no longer used.–
--sdgendefaults–Deprecatedoff––v1.100deprecatedDeprecated (1.105): use --gendefaults.–
--flashattention--flash-attn -faDeprecatedoff––v1.64deprecatedDeprecated (1.107): flash attention is on by default; use --noflashattention to disable.F09
--useswa–Deprecatedoff––v1.92deprecatedDeprecated (1.114): SWA is automatic; use --noswa to disable.–
--multiuser–Deprecated—limit–v1.44deprecatedDeprecated (1.123): multi-user queueing is always on; use --queuelimit / --parallelrequests.–
--testmemory–Internaloff––v1.102hiddenInternal debug flag (memory test).–
--run-bundled-agent--run-agentInternaloff––v1.122hiddenInternal: used by the binary to start the bundled agent process.–
--agent-base-url–Internal—––v1.122hiddenInternal: API base URL passed to the agent process.–
--agent-api-key–Internal—––v1.122hiddenInternal: API key passed to the agent process.–
--stream–Removed—––v1.0.8betaremovedRemoved or replaced. Version history: v1.0.8beta..v1.59.1 (deprecated earlier, removed after 1.59).–
--psutil_set_threads–Removed—––v1.1removedRemoved or replaced. Version history: v1.1..v1.59.1.–
--useclblast–Removed—––v1.5removedRemoved or replaced. Version history: v1.5..v1.106.2 (CLBlast backend removed in v1.107).–
--unbantokens–Removed—––v1.13removedRemoved or replaced. Version history: v1.13..v1.59.1.–
--usemirostat–Removed—––v1.19removedRemoved or replaced. Version history: v1.19..v1.59.1.–
--renamemodel–Removed—––v1.27removedRemoved or replaced. Version history: v1.27 only (replaced by --hordeconfig).–
--bantokens–Removed—––v1.34.2removedRemoved or replaced. Version history: v1.34.2..v1.63 (removed in 1.64).–
--linearrope–Removed—––v1.35removedRemoved or replaced. Version history: v1.35 only (replaced by --ropeconfig).–

Open a row’s link to share it, or copy the table as Markdown or CSV. Searching an old name such as cublas finds --usecuda through its alias.

KoboldCpp flags: how to pass them

To build a command for your shell, or to check an old one, use the command builder.

Write the program name, then the flags. A flag with a value takes a space and then the value. A flag that is a switch is just the flag. Quote paths that contain spaces. Several values are separated by spaces, for example --tensor_split 3 1.

Command Prompt
koboldcpp.exe --model "D:\My Models\model.gguf" --contextsize 8192

A value outside the allowed range is rejected at start. In our test, a context size of the wrong range stopped KoboldCpp with this message F22:

Context out of rangeR-run1-lnx-nocuda-fail-ctx-too-big · lab-lnx · KoboldCpp 1.124.2 (F22)
koboldcpp-linux-x64-nocuda: error: argument --contextsize/--ctx-size/-c: must be within [256, 524288]1
  1. koboldcpp-linux-x64-nocuda: error: argument --contextsize/--ctx-size/-: The flag, its aliases and the allowed range.

The config builder builds a command for you.

The flags most people need

The flags most people need
--modelThe model file. Without it (or a config) the launcher opens.F59
--contextsizeDefault 16384; KoboldCpp adds 256; allowed range 256 to 524288.F05 F06 F22
--gpulayersDefault -1 means automatic. How many to use.F05
--usecuda --usevulkan --usecpuA GPU flag without that GPU silently runs on the CPU.F17
--threadsAutomatic used half of four virtual CPUs; four threads were faster.F07
--portDefault 5001.F05
--hostEmpty (the default) listens on all interfaces; 127.0.0.1 keeps it local. See the warning below.upstream
--passwordProtects generation, not discovery.F25
--launchOpens the browser when ready.F30
--config --exportconfigLoad or write a .kcpps file; it round-trips exactly.F08
--quantkvSaves memory at long context; see the warnings.F10
--noflashattentionFlash attention is already on by default.F09
--usemmapOff by default; lowers the reported working set on Windows.F12
--skiplauncherNever show the launcher.upstream
--remotetunnelOpens a public link. See the warning below.upstream
--benchmarkFills the context and writes one CSV row.F16
--parallelrequestsTwo at once; no extra throughput on CPU.F26
--failsafe --noavx2For CPUs without AVX2; they cost speed.F15

Renamed, deprecated and removed flags

Old guides from 2023 and 2024 use names that have changed. Aliases work today but may be removed.

Renamed, deprecated and removed flags
--usecublas--usecuda (alias kept)1.96
--blasbatchsize--batchsize (alias kept)1.101
--promptlimit--genlimit (alias kept)1.99
--sdclipl, --sdclipg--sdclip1, --sdclip21.100
--usecuda lowvram--lowvram (also -nkvo)1.100
--usecuda rowsplit--splitmode (row split removed later)1.113, 1.118
--noblashidden; maps to --usecpu1.75
--hordeconfig, --sdconfighidden; translated to new flagsdeprecated 1.65
--smartcontextstill present but discouraged–
--flashattention (-fa)hidden; flash attention is on by default1.107
--pipelineparallel--nopipelineparallel; both hidden1.107, 1.122
--sdnotile--sdtiledvae 01.94
--sdt5xxl--sdllm1.122
--sdvaecpu, --sdclipgpu--sdvaedevice, --sdclipdevice1.114
--sdgendefaults--gendefaults1.105
--useswaautomatic SWA; --noswa turns it off1.114
--multiuserhidden; always on1.123
--jinjatoolsalias of --jinja1.123
--forceversionno effect1.104
--useclblastremoved: the CLBlast backend is gone1.107
--bantokensremoved: bans are per request1.64
--stream, --psutil_set_threads, --unbantokens, --usemirostatremovedafter 1.59.1
--linearropereplaced by --ropeconfig1.36
--renamemodelreplaced by --hordeconfig1.28
--lora base model argumentdropped1.93
--onready from configsignored unless --allow-config-onready1.90, 1.116

Since 1.99 KoboldCpp also accepts llama.cpp-style aliases (-m, -c, -ngl, -ts, -b, -fa, -ot, --n-cpu-moe). Row anchors for old names such as #flag-usecublas and #flag-blasbatchsize open the current flag’s row. Why 2023 guides fail: they use removed or renamed flags.

Flags whose launcher box says the opposite

Five checkboxes in the launcher are inverted: unticking “Use ContextShift”, “Use FastForwarding”, “Use FlashAttention”, “Allow SWA” or “Use MMQ” writes --noshift, --nofastforward, --noflashattention, --noswa or --nommq.

Command line vs launcher vs .kcpps: which wins

A .kcpps loaded with --config is applied, except for options that were also given on the command line: those win, and the console says so. In our test the console printed these lines F08:

Config loaded, command line winsconf-load · lab-lnx · KoboldCpp 1.124.2 (F08)
Overriding Config Value: port1Overriding Config Value: skiplauncher
  1. Overriding Config Value: port: The command line gave --port too, so the file's value was not used.

Keys in a .kcpps are the flag names with underscores: see .kcpps files.

Environment variables

KCPP_PASSWORD and KCPP_ADMINPASSWORD set the defaults of --password and --adminpassword. The KCPP_MODEL and KCPP_ARGS variables belong to the Docker image, not to KoboldCpp itself: Docker.

Things that are not flags

A system prompt is set in Kobold Lite or in your client, not by a flag. --gendefaults sets default generation parameters for requests and --gendefaultsoverwrite forces them. The interface language and sampler presets are in Lite: Lite guide and samplers.

Utility modes

Some flags do something and exit or change the mode: , , , , , , (one reply) and (terminal chat).

How this table is kept current

On every release we dump the flags from the program’s own parser and compare them with the previous list. The “Added in” column comes from the release history, which we could verify only back to the releases that have their own page, so treat it as a best estimate. See how we test and releases.

Frequently asked questions

Where can I see all KoboldCpp command-line options?

Run KoboldCpp with --help, or use the table on this page, which lists all 183 entries of version 1.124.2 with defaults, aliases and the version each was added.

What replaced --usecublas?

--usecuda, since 1.96. The old name still works as an alias, and --usehipblas is also an alias of --usecuda.

Is the API key required?

No. A key is only needed if you start KoboldCpp with --password. In our test, with a password set, generation endpoints answered 401 without the key and 200 with it.

What is the default context size?

16384 in 1.124.2. KoboldCpp adds 256 to the value you give it, so the log shows 16640 by default.

How do I start KoboldCpp without the launcher?

Give it a model with --model or a saved config with --config. --skiplauncher makes sure the launcher never opens.

Can I use llama.cpp flags like -ngl and -c?

Yes. Since 1.99 KoboldCpp accepts llama.cpp-style aliases such as -m, -c, -ngl, -ts, -b, -fa and -ot. The table lists each flag's aliases.