Skip to main content
Koharu automatically detects your hardware at startup and selects the fastest available compute backend for its ML stack — text detection, OCR, translation, and inpainting all share a single chosen device. You do not need to configure anything manually in most cases, but understanding the selection order and driver requirements helps you get the best performance and troubleshoot issues when they arise.

​
Runtime selection order

Koharu evaluates backends in the following priority order and uses the first one that is available and fully initialized: If a higher-priority backend is present but fails to initialize (for example, due to an outdated driver), Koharu falls back to the next option in the list. CPU fallback is always available and prioritizes correctness over speed.

​
Platform and driver requirements

Koharu supports CUDA 13.0 on Windows and Linux.Driver requirement: CUDA 13.0 requires an NVIDIA driver from the R580 series or newer. Install the latest NVIDIA driver before launching Koharu. If your driver is older than R580, Koharu will skip CUDA and fall back to Vulkan or CPU.No separate CUDA Toolkit installation is required — Koharu bundles the runtime libraries it needs.

​
Model downloads and the local cache

Koharu resolves runtime dependencies and model files on demand rather than bundling them in the installer. Three kinds of data are downloaded and cached:
  • Native runtime packages — Torch, llama.cpp, and diffusion backend libraries compiled for your platform and selected runtime (e.g., CUDA or CPU)
  • Pinned model files — detection, OCR, and inpainting model weights fetched from Hugging Face
  • GGUF quantizations — local LLM files selected for the translation stage, also fetched from Hugging Face
All of these are stored under your operating system’s standard cache directory:
The exact path depends on your OS: Project data (your .khrproj files and imported pages) is stored separately under Documents/Koharu. Application settings are stored in ~/.koharu/config.toml. Downloads are staged before being published to the cache. A failed or interrupted download will be retried automatically on the next launch or the next time the relevant model is used — you do not need to manually clear anything.
WebGPU is required for the editor canvas. Even when ML inference falls back to CPU, Koharu’s canvas and editor interface use WebGPU inside an embedded webview. A working WebGPU adapter and an up-to-date graphics driver are required to launch the editor at all — not just for accelerated ML.

​
Choosing a quantization size

Koharu supports multiple GGUF quantization levels for local translation models. Smaller quantizations use less memory and load faster, usually with a small quality trade-off. Larger quantizations produce higher-quality translations but require more VRAM or system RAM.
Start with a mid-size quantization (such as Q4 or Q5) rather than the largest file your disk can hold. You can always switch to a larger quantization later once you have a sense of the quality difference for your content.

​
Troubleshooting startup and download failures

If Koharu fails to initialize a runtime or stalls on a model download, work through these steps:
  1. Check network access — Koharu fetches packages from GitHub release assets and model weights from Hugging Face. Confirm both are reachable from your network. Corporate firewalls or VPNs may block these endpoints.
  2. Update your GPU driver — an outdated driver is the most common reason CUDA or ROCm fails to initialize. Install the latest driver from your GPU vendor and relaunch Koharu.
  3. Retry the download — failed downloads are retried automatically on next launch. You can also trigger a retry by navigating to the relevant feature and running it again.
  4. Check the activity center — Koharu reports download and initialization errors in the activity center at the bottom of the window. The full error message there is useful when filing a bug report.
For persistent failures, capture the full error from the activity center and see the Troubleshooting reference page.