文書Documentation

Kotoshu on Windows

gem install kotoshu on Windows: the tested Ruby versions, path handling, the onnxruntime soft dependency, and the honest status of the native extension.

The gem installs and runs on Windows the same way it does everywhere else — and the claim is not marketing: the CI matrix runs the full test suite on windows-latest for Ruby 3.3, 3.4, and 4.0, green on every merge to main. What differs on Windows — paths, soft dependencies, the native extension — is what this page documents, honestly.

窓Install & run

The sixty-second path, on Windows

gem install kotoshu

# Stage 1 — download a dictionary once
kotoshu setup en

# Stage 2 — check, cache-only, instant
kotoshu check README.md --language en

Works in PowerShell, cmd, and Windows Terminal alike. The gem requires Ruby 3.1 or newer; the versions CI actually proves are 3.3, 3.4, and 4.0, on windows-latest alongside Ubuntu and macOS — the same job runs the whole spec suite, not a reduced smoke set.

Two Windows bugs were found and fixed by that matrix rather than by users: dictionary files are now read with owned handles closed promptly, so Windows file locking no longer trips a re-check of an open file, and verified downloads write in binary mode, so corruption from text-mode newline translation is gone. Checking, stdin piping, and the SARIF and JSON formats behave identically across platforms.

場所Paths

Where things land

Kotoshu resolves its directories through the XDG convention rooted at your home directory — C:\Users\you on Windows — the same code path on every platform:

Concern	Default location	Override
Dictionaries, frequency lists, models	`%USERPROFILE%\.cache\kotoshu\`	`KOTOSHU_CACHE_PATH`
Personal dictionary, kotoshu.cfg	`%USERPROFILE%\.config\kotoshu\`	`KOTOSHU_CONFIG_PATH`
Personal dictionary file	`…\.config\kotoshu\personal.dic`	`KOTOSHU_PERSONAL_DIC`
Audit log	`%USERPROFILE%\.local\share\kotoshu\audit.log`	`KOTOSHU_AUDIT_LOG`

The XDG_CACHE_HOME / XDG_CONFIG_HOME / XDG_DATA_HOME variables are honored too, when set. Run kotoshu personal path or kotoshu status to see where yours resolve.

選択Soft dependencies

What installs, what waits

gem install kotoshu pulls three pure-Ruby dependencies and nothing else. Two capabilities are deliberately soft — installed separately, detected at load time:

Optional gem	Unlocks	Without it
`onnxruntime`	Semantic reranking — context-aware suggestions from the FastText-ONNX models	Dictionary checking works in full; semantic calls raise a caller-friendly `OnnxUnavailable` error. `KOTOSHU_NO_ONNX=1` forces it off even when present
`suika`	Japanese morphological tokenization	Every other language is unaffected; Japanese tokenization raises `SuikaUnavailable` when requested

They are soft precisely so a Windows machine without a build toolchain still gets a working gem install — their native pieces are never required for the traditional spelling path.

現状Native extension

The Rust accelerator, stated plainly

The gem carries an optional Rust extension over the kotoshu-rs core — an accelerator, not a requirement. Its Windows status, honestly: not yet built on Windows in CI. The matrix above runs the pure-Ruby engine, which is the complete implementation; the extension is exercised through separate compile and conformance tasks that are not part of the Windows job today. That is tracked work, not a hidden limitation.

What happens on gem install when the extension tries to build: RubyGems invokes the extconf, and if no Rust cargo is found, rb-sys bootstraps a rustup toolchain into the build directory. If the build still does not produce the extension — as can happen on Windows today — the install succeeds and the pure-Ruby engine serves everything; Kotoshu::Native.available? reports false. No feature you can call is missing without it.

Editing on Windows but checking in CI? The GitHub Action runs the check on the runner, so your local platform never constrains the pipeline — and the baseline and ignore tools keep it green while you work.

Verified against the gem source (paths.rb, kotoshu.gemspec, lib/kotoshu/models) and the repository’s CI runs — Ruby 3.3/3.4/4.0 on windows-latest, green on main. The native extension statement reflects what the workflows actually build today. The CLI reference and Caching & resources pages apply on Windows unchanged.