Skip to main content
All posts
Tutorial

How to Install DeepSeek Harness on macOS, Windows, and Linux (2026)

DeepSeek Harness install steps for macOS, Windows, and Linux, covering the Node version pitfall, Arch Linux node-pty errors, and the Windows folder-picker bug.

DeepSeek Harness (dsh) installs the same way on every platform — npx @deepseek-ai/dsh web — but the failure modes are platform-specific: an old Node.js build breaks silently on macOS and Linux, Arch Linux blocks a native dependency's install script, and Windows has a known folder-picker bug with its own documented workaround. This guide covers the base install plus every platform-specific issue we could confirm from the official repo and its GitHub Discussions.

Baseline requirements (all platforms)

RequirementValue
Node.js^22.19.0 || >=24.0.0
CI-tested Node versions22.19, 24, 26
pnpmRequired once you start installing plugins (dsh plugin shells out to it)
Git2.26+, only if you're building from source

The single most common install failure across all three platforms is simply an outdated Node.js. dsh uses node:zlib's createZstdDecompress, which was only added in Node 22.15. On an older Node build, npx @deepseek-ai/dsh web fails immediately with:

The requested module 'node:zlib' does not provide an export named 'createZstdDecompress'

The fix is to upgrade Node — target 22.19+ or 24+ to match what dsh's engines field actually requires, not just the 22.15 floor for that one API.

macOS

macOS has no platform-specific install issues beyond the baseline Node requirement. The straightforward path:

npx @deepseek-ai/dsh web

If you manage Node with nvm, fnm, or asdf, confirm your active version with node -v before running the command — a stale shell session pinned to an old Node install is the most common cause of the zlib error above on macOS.

The Python SDK (covered in a separate guide) is also supported on macOS, but only on macOS 14+ (arm64) — Intel Macs are not listed as a supported target for the SDK's bundled runtime.

Windows

Windows install works the same way at the command level, but two issues are worth knowing about before you start.

Folder-picker failure

A documented Discussion (#30, 20 comments, with an accepted answer) describes "Add workspace" failing with:

directory picker failed: win32 folder dialog worker exited before reporting a result

The root cause is that the native directory picker depends on a native binding called koffi, and its install script sometimes fails to build on Windows. The workaround has two parts:

  1. Reinstall with --ignore-scripts to skip the failing native build step:

    npm i -g @deepseek-ai/dsh --ignore-scripts --registry=https://registry.npmjs.org

  2. Switch the profile's directory picker from the native backend to the browse (in-app) backend by editing ~/.dsh/profiles/web/cordis.patch.yml — disable directory-picker/directory-picker-native/directory-picker-auto and insert directory-picker-browse plus its matching client UI package instead. See our Web UI guide for what the two picker backends look like from the user's side.

Cannot find package after global install

A separate report (Discussion #55) describes pnpm add -g @deepseek-ai/dsh followed by dsh --profile headless --help crashing with Cannot find package '@deepseek-ai/cordis-plugin-timer' on Windows 11 + Node 24 + pnpm 11.9 — a dependency-resolution gap in that specific combination. The community discussion reports it as resolved, but no public patch details were confirmed at the time of our research. If you hit this, try reinstalling with a clean pnpm store (pnpm store prune) or switch to npx @deepseek-ai/dsh web rather than a global install, which sidesteps the global dependency tree entirely.

Chinese (and other non-ASCII) workspace paths

Two separate Discussions (#47 "The workspace does not support Chinese path names" and #107, "中文路径选择截断") report that workspace paths containing Chinese characters get truncated or rejected on Windows. No official fix was confirmed as of this writing — if your project lives under a path with non-ASCII characters, consider moving it to an ASCII-only path before pointing dsh at it as a workspace.

Linux

The baseline npx @deepseek-ai/dsh web install works on most distributions. One distribution-specific issue is documented:

Arch Linux: node-pty install script blocked

Discussion #49 reports that on Arch, npx @deepseek-ai/dsh web fails during plugin-tree loading with an error pointing at node-pty — npm on Arch doesn't trust node-pty's install script to run its own compile step by default. Two workarounds are documented:

# Option A: use bun instead, which trusts node-pty's install script by default
bun add --global @deepseek-ai/dsh

# Option B: stay on npm, install node-pty globally yourself, then clear the npx cache
npm install -g node-pty
rm -rf ~/.npm/_npx

Re-run npx @deepseek-ai/dsh web after either fix.

.env as a directory instead of a file

If your working directory happens to contain a directory (not a file) named .env, dsh prints failed to load .env: EISDIR on every startup. This is a confirmed bug (Discussion #71) — the .env-loading code reads the path without first checking it's a regular file. There are two separate code paths that hit this, so it can recur even if you think you've fixed it once. The workaround is simply to rename or remove the .env directory before launching dsh from that folder.

Installing from source (any platform)

If you want to run the unpublished master branch, or you're contributing to dsh itself:

git clone https://github.com/deepseek-ai/deepseek-harness.git
cd deepseek-harness
pnpm install
pnpm run build
pnpm dsh web

Two things to note here. First, the master branch's package.json version can lag behind what's actually published to npm — treat the npm latest dist-tag as the source of truth for "what version am I really running," not the repo's own version string. Second, a from-source pnpm run build failure with [ELIFECYCLE] Command failed with exit code 1 has been reported (Discussion #86) and traced to the repo's own build scripts internally mixing npm run and pnpm calls — dsh's build tooling is pnpm-only; don't substitute npm or yarn for the build step even though some internal scripts reference npm run.

Python SDK platform limits

If you plan to drive dsh programmatically instead of through the CLI or Web UI, be aware the Python SDK (pip install deepseek-harness-sdk) has a narrower supported platform list than the CLI: Linux x64, Linux arm64, and macOS 14+ (arm64) only — there is currently no documented Windows support for the Python SDK's bundled runtime, even though the CLI itself runs fine on Windows.

FAQ

What's the minimum Node.js version for DeepSeek Harness?

^22.19.0 || >=24.0.0 per the package's engines field. A lower version — even 22.14 — can appear to almost work but fails with a node:zlib error the moment dsh needs createZstdDecompress, which requires Node 22.15+.

Does DeepSeek Harness support Windows natively, or only through WSL?

Native Windows support exists (the CLI, Web UI, and a Windows ACL-based sandbox backend), but expect the two documented rough edges above: the koffi-dependent folder picker and Chinese-path handling. If you hit either, WSL is a reasonable fallback since it gives you the Linux install path instead.

Why does npx fail on Arch Linux specifically?

Arch's npm configuration doesn't trust node-pty's install script to run by default, and dsh depends on node-pty for terminal functionality. Switching to bun add --global @deepseek-ai/dsh sidesteps the issue because bun trusts that script by default.

Can I install DeepSeek Harness without an internet connection?

Not documented as supported — npx needs to fetch the package, and plugin installs go through pnpm hitting the npm/GitHub registries. There's no offline bundle format described in the official docs.

My install seems to have worked, but something is still broken — where do I look next?

Check DeepSeek Harness Troubleshooting for a broader list of confirmed error messages and fixes pulled from official GitHub Discussions (dsh's Issues tracker is disabled, so Discussions is the closest thing to an official bug tracker).

Next steps