| 1 | # Installing DeepSeek TUI |
| 2 | |
| 3 | This page covers every supported install path and the most common |
| 4 | "it didn't install" failures, including **Linux ARM64** and other less |
| 5 | common platforms. |
| 6 | |
| 7 | If you just want the short version, see the |
| 8 | [main README](../README.md#quickstart) or |
| 9 | [简体中文 README](../README.zh-CN.md#快速开始). |
| 10 | |
| 11 | --- |
| 12 | |
| 13 | ## 1. Supported platforms |
| 14 | |
| 15 | `deepseek-tui` ships prebuilt binaries for these |
| 16 | platform/architecture combinations from v0.8.8 onward: |
| 17 | |
| 18 | | Platform | Architecture | npm install | `cargo install` | GitHub release asset | |
| 19 | | ------------ | ------------ | :---------: | :-------------: | ----------------------------------------------------- | |
| 20 | | Linux | x64 (x86_64) | ✅ | ✅ | `deepseek-linux-x64`, `deepseek-tui-linux-x64` | |
| 21 | | Linux | arm64 | ✅ | ✅ | `deepseek-linux-arm64`, `deepseek-tui-linux-arm64` | |
| 22 | | macOS | x64 | ✅ | ✅ | `deepseek-macos-x64`, `deepseek-tui-macos-x64` | |
| 23 | | macOS | arm64 (M-series) | ✅ | ✅ | `deepseek-macos-arm64`, `deepseek-tui-macos-arm64` | |
| 24 | | Windows | x64 | ✅ | ✅ | `deepseek-windows-x64.exe`, `deepseek-tui-windows-x64.exe` | |
| 25 | | Other Linux (musl, riscv64, …) | — | ❌¹ | ✅² | build from source | |
| 26 | | FreeBSD / OpenBSD | — | ❌ | ✅² | build from source | |
| 27 | |
| 28 | ¹ The npm package will exit with a clear error and point you here. |
| 29 | ² Provided your toolchain can compile a recent Rust workspace; see |
| 30 | [Build from source](#5-build-from-source) below. |
| 31 | |
| 32 | > **Linux ARM64 note (v0.8.7 and earlier).** v0.8.7 and earlier do **not** |
| 33 | > publish a Linux ARM64 prebuilt; users on HarmonyOS thin-and-light, Asahi |
| 34 | > Linux, Raspberry Pi, AWS Graviton, etc. saw `Unsupported architecture: arm64` |
| 35 | > from `npm i -g deepseek-tui`. v0.8.8 publishes both `deepseek-linux-arm64` |
| 36 | > and `deepseek-tui-linux-arm64`, so a plain `npm i -g deepseek-tui` works |
| 37 | > on any glibc-based ARM64 Linux. If you're stuck on v0.8.7, jump to |
| 38 | > [Build from source](#5-build-from-source) — `cargo install` works fine. |
| 39 | |
| 40 | --- |
| 41 | |
| 42 | ## 2. Install via npm (recommended) |
| 43 | |
| 44 | ```bash |
| 45 | npm install -g deepseek-tui |
| 46 | deepseek |
| 47 | ``` |
| 48 | |
| 49 | `postinstall` downloads the right pair of binaries from the matching GitHub |
| 50 | release, verifies a SHA-256 manifest, and exposes both `deepseek` and |
| 51 | `deepseek-tui` on your `PATH`. |
| 52 | |
| 53 | Useful environment variables: |
| 54 | |
| 55 | | Variable | Purpose | |
| 56 | | ----------------------------------- | -------------------------------------------------------------------------------------- | |
| 57 | | `DEEPSEEK_TUI_VERSION` | Pin which release the wrapper downloads (defaults to `deepseekBinaryVersion`) | |
| 58 | | `DEEPSEEK_TUI_GITHUB_REPO` | Point the downloader at a fork (`owner/repo`) | |
| 59 | | `DEEPSEEK_TUI_RELEASE_BASE_URL` | Override the download root (e.g. an internal mirror or release-asset proxy) | |
| 60 | | `DEEPSEEK_TUI_FORCE_DOWNLOAD=1` | Re-download even if a cached binary marker matches | |
| 61 | | `DEEPSEEK_TUI_DISABLE_INSTALL=1` | Skip the `postinstall` download entirely (CI smoke, vendored binaries) | |
| 62 | | `DEEPSEEK_TUI_OPTIONAL_INSTALL=1` | Don't fail `npm install` on download/extract errors — useful in CI matrices | |
| 63 | |
| 64 | > **Slow npm download from mainland China?** If `npm install` itself is slow |
| 65 | > (not just the postinstall binary download), use an npm registry mirror: |
| 66 | > ```bash |
| 67 | > npm config set registry https://registry.npmmirror.com |
| 68 | > npm install -g deepseek-tui |
| 69 | > ``` |
| 70 | > See also [Section 3](#3-install-via-cargo-any-tier-1-rust-target) if you |
| 71 | > prefer Cargo over npm. |
| 72 | |
| 73 | --- |
| 74 | |
| 75 | ## 3. Install via Cargo (any Tier-1 Rust target) |
| 76 | |
| 77 | If GitHub releases are slow, blocked, or you're on an unsupported architecture, |
| 78 | install from crates.io directly. Both crates are required — the dispatcher |
| 79 | delegates to the TUI runtime at runtime. |
| 80 | |
| 81 | ```bash |
| 82 | # Requires Rust 1.88+ (https://rustup.rs) |
| 83 | cargo install deepseek-tui-cli --locked # provides `deepseek` |
| 84 | cargo install deepseek-tui --locked # provides `deepseek-tui` |
| 85 | deepseek --version |
| 86 | ``` |
| 87 | |
| 88 | ### China / mirror-friendly install |
| 89 | |
| 90 | When installing from mainland China, configure mirrors for both **rustup** |
| 91 | (the Rust toolchain installer) and **Cargo** (the package registry) to avoid |
| 92 | TLS timeouts and download failures. |
| 93 | |
| 94 | **Step 1: Install Rust via a rustup mirror** |
| 95 | |
| 96 | ```bash |
| 97 | # PowerShell |
| 98 | [Net.ServicePointManager]::SecurityProtocol = [Net.SecurityProtocolType]::Tls12 |
| 99 | (New-Object Net.WebClient).DownloadFile('https://win.rustup.rs/x86_64', 'rustup-init.exe') |
| 100 | |
| 101 | # git-bash / msys2 |
| 102 | export RUSTUP_DIST_SERVER=https://mirrors.tuna.tsinghua.edu.cn/rustup |
| 103 | export RUSTUP_UPDATE_ROOT=https://mirrors.tuna.tsinghua.edu.cn/rustup/rustup |
| 104 | ./rustup-init.exe -y --default-toolchain stable |
| 105 | |
| 106 | # Linux / macOS |
| 107 | export RUSTUP_DIST_SERVER=https://mirrors.tuna.tsinghua.edu.cn/rustup |
| 108 | export RUSTUP_UPDATE_ROOT=https://mirrors.tuna.tsinghua.edu.cn/rustup/rustup |
| 109 | curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh -s -- -y --default-toolchain stable |
| 110 | ``` |
| 111 | |
| 112 | The `RUSTUP_DIST_SERVER` and `RUSTUP_UPDATE_ROOT` environment variables must |
| 113 | be set **before** running rustup-init; the toolchain download otherwise hits |
| 114 | the same TLS handshake problem as the installer. |
| 115 | |
| 116 | **Step 2: Configure Cargo registry mirror** |
| 117 | |
| 118 | ```toml |
| 119 | # ~/.cargo/config.toml |
| 120 | [source.crates-io] |
| 121 | replace-with = "tuna" |
| 122 | |
| 123 | [source.tuna] |
| 124 | registry = "sparse+https://mirrors.tuna.tsinghua.edu.cn/crates.io-index/" |
| 125 | ``` |
| 126 | |
| 127 | `rsproxy`, Tencent COS, and Aliyun OSS mirrors work the same way; pick whichever |
| 128 | is fastest from your network. |
| 129 | |
| 130 | --- |
| 131 | |
| 132 | ## 4. Manual download from GitHub Releases |
| 133 | |
| 134 | Grab the matching pair of binaries for your platform from the |
| 135 | [Releases page](https://github.com/Hmbown/DeepSeek-TUI/releases) and drop them |
| 136 | side by side into a directory on your `PATH` (e.g. `~/.local/bin`): |
| 137 | |
| 138 | ```bash |
| 139 | # Linux ARM64 example |
| 140 | mkdir -p ~/.local/bin |
| 141 | curl -L -o ~/.local/bin/deepseek \ |
| 142 | https://github.com/Hmbown/DeepSeek-TUI/releases/latest/download/deepseek-linux-arm64 |
| 143 | curl -L -o ~/.local/bin/deepseek-tui \ |
| 144 | https://github.com/Hmbown/DeepSeek-TUI/releases/latest/download/deepseek-tui-linux-arm64 |
| 145 | chmod +x ~/.local/bin/deepseek ~/.local/bin/deepseek-tui |
| 146 | deepseek --version |
| 147 | ``` |
| 148 | |
| 149 | Verify integrity against the per-release SHA-256 manifest: |
| 150 | |
| 151 | ```bash |
| 152 | curl -L -o /tmp/deepseek-artifacts-sha256.txt \ |
| 153 | https://github.com/Hmbown/DeepSeek-TUI/releases/latest/download/deepseek-artifacts-sha256.txt |
| 154 | ( cd ~/.local/bin && sha256sum -c /tmp/deepseek-artifacts-sha256.txt --ignore-missing ) |
| 155 | ``` |
| 156 | |
| 157 | (Use `shasum -a 256 -c` instead of `sha256sum` on macOS.) |
| 158 | |
| 159 | --- |
| 160 | |
| 161 | ## 5. Build from source |
| 162 | |
| 163 | This is the catch-all for any platform we don't ship — including musl, riscv64, |
| 164 | LoongArch, FreeBSD, and pre-2024 ARM64 distros. |
| 165 | |
| 166 | ### Prerequisites |
| 167 | |
| 168 | - **Rust** 1.88 or later — install with [rustup](https://rustup.rs). |
| 169 | - **Linux build-time deps** (Debian/Ubuntu/openEuler/Kylin): |
| 170 | ```bash |
| 171 | sudo apt-get install -y build-essential pkg-config libdbus-1-dev |
| 172 | # openEuler / RHEL family: |
| 173 | # sudo dnf install -y gcc make pkgconf-pkg-config dbus-devel |
| 174 | ``` |
| 175 | - A working `cmake` is **not** required. |
| 176 | |
| 177 | ### Build and install |
| 178 | |
| 179 | ```bash |
| 180 | git clone https://github.com/Hmbown/DeepSeek-TUI.git |
| 181 | cd DeepSeek-TUI |
| 182 | |
| 183 | cargo install --path crates/cli --locked # provides `deepseek` |
| 184 | cargo install --path crates/tui --locked # provides `deepseek-tui` |
| 185 | |
| 186 | deepseek --version |
| 187 | ``` |
| 188 | |
| 189 | Both binaries land in `~/.cargo/bin/` by default; make sure that directory is |
| 190 | on your `PATH`. |
| 191 | |
| 192 | ### Cross-compiling from x64 to ARM64 Linux |
| 193 | |
| 194 | If you want to build an ARM64 Linux binary on an x64 Linux host (e.g. for a |
| 195 | HarmonyOS / openEuler ARM64 thin-and-light), use |
| 196 | [`cross`](https://github.com/cross-rs/cross), which wraps the official Rust |
| 197 | cross-targets in a Docker container: |
| 198 | |
| 199 | ```bash |
| 200 | # Once |
| 201 | rustup target add aarch64-unknown-linux-gnu |
| 202 | cargo install cross --locked |
| 203 | |
| 204 | # Per build |
| 205 | cross build --release --target aarch64-unknown-linux-gnu -p deepseek-tui-cli |
| 206 | cross build --release --target aarch64-unknown-linux-gnu -p deepseek-tui |
| 207 | ``` |
| 208 | |
| 209 | The resulting binaries land in |
| 210 | `target/aarch64-unknown-linux-gnu/release/deepseek` and |
| 211 | `target/aarch64-unknown-linux-gnu/release/deepseek-tui`. Copy the matched pair |
| 212 | to the ARM64 host (e.g. via `scp`) and `chmod +x` them. |
| 213 | |
| 214 | If you don't have Docker available, install the cross-linker directly and let |
| 215 | Cargo do the work: |
| 216 | |
| 217 | ```bash |
| 218 | sudo apt-get install -y gcc-aarch64-linux-gnu |
| 219 | rustup target add aarch64-unknown-linux-gnu |
| 220 | |
| 221 | cat >> ~/.cargo/config.toml <<'EOF' |
| 222 | [target.aarch64-unknown-linux-gnu] |
| 223 | linker = "aarch64-linux-gnu-gcc" |
| 224 | EOF |
| 225 | |
| 226 | cargo build --release --target aarch64-unknown-linux-gnu -p deepseek-tui-cli |
| 227 | cargo build --release --target aarch64-unknown-linux-gnu -p deepseek-tui |
| 228 | ``` |
| 229 | |
| 230 | The same recipe works for `aarch64-unknown-linux-musl` if your distro is |
| 231 | musl-based. |
| 232 | |
| 233 | ### Windows build from source |
| 234 | |
| 235 | Building on Windows requires the **MSVC C toolchain** from |
| 236 | [Visual Studio Build Tools](https://visualstudio.microsoft.com/downloads/#build-tools-for-visual-studio-2022) |
| 237 | (the free workload-selectable installer, not the full IDE). |
| 238 | |
| 239 | **Prerequisites (Windows)** |
| 240 | |
| 241 | 1. Install Visual Studio 2022 Build Tools — select the **"Desktop development |
| 242 | with C++"** workload. |
| 243 | 2. Install [Rust](https://rustup.rs) 1.88+ (see the |
| 244 | [China mirror instructions](#china--mirror-friendly-install) above if |
| 245 | downloading from mainland China). |
| 246 | 3. Install [Git for Windows](https://git-scm.com/download/win) (provides `git` |
| 247 | and the `git-bash` terminal). |
| 248 | |
| 249 | **Recommended terminals**: Windows Terminal, `git-bash`, or PowerShell. |
| 250 | `cmd.exe` works but has a small buffer and limited PATH behavior. |
| 251 | |
| 252 | **Setting up the MSVC environment** |
| 253 | |
| 254 | Visual Studio Build Tools install `cl.exe` to a versioned directory but do |
| 255 | **not** add it to `PATH` globally. You must set the environment manually or |
| 256 | use a Developer Command Prompt. The required variables are: |
| 257 | |
| 258 | ```powershell |
| 259 | # Adjust version numbers to match your installation |
| 260 | $msvc = "C:\Program Files (x86)\Microsoft Visual Studio\2022\BuildTools\VC\Tools\MSVC\14.44.35207" |
| 261 | $sdk = "C:\Program Files (x86)\Windows Kits\10" |
| 262 | $sdkv = "10.0.26100.0" |
| 263 | |
| 264 | $env:INCLUDE = "$msvc\include;$msvc\atlmfc\include;$sdk\Include\$sdkv\ucrt;$sdk\Include\$sdkv\um;$sdk\Include\$sdkv\shared" |
| 265 | $env:LIB = "$msvc\lib\x64;$msvc\atlmfc\lib\x64;$sdk\Lib\$sdkv\ucrt\x64;$sdk\Lib\$sdkv\um\x64" |
| 266 | $env:LIBPATH = "$msvc\lib\x64;$msvc\atlmfc\lib\x64" |
| 267 | $env:CC = "$msvc\bin\Hostx64\x64\cl.exe" |
| 268 | $env:CXX = "$msvc\bin\Hostx64\x64\cl.exe" |
| 269 | $env:PATH = "$msvc\bin\Hostx64\x64;$env:PATH" |
| 270 | ``` |
| 271 | |
| 272 | Alternatively, open a **"Developer Command Prompt for VS 2022"** (available |
| 273 | from the Start Menu after installing Build Tools), which runs `vcvars64.bat` |
| 274 | to configure all of the above automatically. Then add `cargo` to `PATH` inside |
| 275 | that session and run `cargo build` from the project root. |
| 276 | |
| 277 | **Cargo registry mirror** — on Windows the mirror config goes to |
| 278 | `%USERPROFILE%\.cargo\config.toml`. See [Step 2 above](#china--mirror-friendly-install). |
| 279 | |
| 280 | **Build** |
| 281 | |
| 282 | ```bash |
| 283 | git clone https://github.com/Hmbown/DeepSeek-TUI.git |
| 284 | cd DeepSeek-TUI |
| 285 | set CARGO_HTTP_CHECK_REVOKE=false # may be needed behind some Chinese ISPs |
| 286 | cargo build --release |
| 287 | ``` |
| 288 | |
| 289 | Both binaries appear in `target\release\deepseek.exe` and |
| 290 | `target\release\deepseek-tui.exe`. |
| 291 | |
| 292 | > **Prefer `npm install -g` on Windows unless you need to modify source.** |
| 293 | > The npm package pulls prebuilt binaries and avoids the C toolchain |
| 294 | > dependency entirely — see [Section 2](#2-install-via-npm-recommended). |
| 295 | |
| 296 | --- |
| 297 | |
| 298 | ## 6. Troubleshooting |
| 299 | |
| 300 | ### `Unsupported architecture: arm64 on platform linux` |
| 301 | |
| 302 | You're on a release earlier than v0.8.8 that doesn't publish Linux ARM64 |
| 303 | binaries. Either upgrade (`npm i -g deepseek-tui@latest`) or use |
| 304 | `cargo install` per [Section 3](#3-install-via-cargo-any-tier-1-rust-target). |
| 305 | |
| 306 | ### `MISSING_COMPANION_BINARY` at runtime |
| 307 | |
| 308 | The dispatcher (`deepseek`) requires the TUI runtime (`deepseek-tui`) to be on |
| 309 | the same `PATH`. If you installed only one crate via `cargo install`, install |
| 310 | both: |
| 311 | |
| 312 | ```bash |
| 313 | cargo install deepseek-tui-cli --locked |
| 314 | cargo install deepseek-tui --locked |
| 315 | ``` |
| 316 | |
| 317 | ### `deepseek update` reports `no asset found for platform deepseek-linux-aarch64` |
| 318 | |
| 319 | This is [#503](https://github.com/Hmbown/DeepSeek-TUI/issues/503) in v0.8.7 — |
| 320 | the self-updater used Rust's `aarch64`/`x86_64` arch names instead of the |
| 321 | release artifact's `arm64`/`x64`. Workaround until v0.8.8: |
| 322 | |
| 323 | ```bash |
| 324 | npm i -g deepseek-tui@latest |
| 325 | # or |
| 326 | cargo install deepseek-tui-cli --locked |
| 327 | ``` |
| 328 | |
| 329 | ### npm download is slow or times out from mainland China |
| 330 | |
| 331 | Set `DEEPSEEK_TUI_RELEASE_BASE_URL` to a mirrored release-asset directory |
| 332 | (rsproxy, TUNA, Tencent COS, Aliyun OSS), or skip npm entirely and use the |
| 333 | Cargo mirror setup in [Section 3](#3-install-via-cargo-any-tier-1-rust-target). |
| 334 | |
| 335 | ### Debian/Ubuntu: `error: linker 'cc' not found` while building |
| 336 | |
| 337 | Install the C toolchain: |
| 338 | |
| 339 | ```bash |
| 340 | sudo apt-get install -y build-essential pkg-config libdbus-1-dev |
| 341 | ``` |
| 342 | |
| 343 | ### Wrapper installs but `deepseek` isn't found |
| 344 | |
| 345 | `npm i -g` installs into `$(npm prefix -g)/bin`; make sure that directory is on |
| 346 | your shell's `PATH`. With nvm: `nvm use --lts && hash -r`. |
| 347 | |
| 348 | ### Windows: `TLS handshake eof` or `CRYPT_E_REVOCATION_OFFLINE` from `rustup-init` |
| 349 | |
| 350 | The TLS handshake to `static.rust-lang.org` fails from behind the GFW or |
| 351 | certain Chinese ISPs. Set the rustup mirror environment variables **before** |
| 352 | running the installer: |
| 353 | |
| 354 | ```bash |
| 355 | # git-bash / msys2 |
| 356 | export RUSTUP_DIST_SERVER=https://mirrors.tuna.tsinghua.edu.cn/rustup |
| 357 | export RUSTUP_UPDATE_ROOT=https://mirrors.tuna.tsinghua.edu.cn/rustup/rustup |
| 358 | ./rustup-init.exe -y --default-toolchain stable |
| 359 | ``` |
| 360 | |
| 361 | If you see `CRYPT_E_REVOCATION_OFFLINE` from Cargo after Rust is installed, |
| 362 | also set `CARGO_HTTP_CHECK_REVOKE=false` during `cargo build`. |
| 363 | |
| 364 | ### Windows: MSVC compiler (`cl.exe`) not found during `cargo build` |
| 365 | |
| 366 | Visual Studio Build Tools do not add `cl.exe` to the global `PATH`. Either: |
| 367 | |
| 368 | 1. Open **"Developer Command Prompt for VS 2022"** from the Start Menu, add |
| 369 | `%USERPROFILE%\.cargo\bin` to `PATH` in that window, and run `cargo build` |
| 370 | from there; or |
| 371 | 2. Set the MSVC environment variables manually — see the |
| 372 | [Windows build from source](#windows-build-from-source) section for the |
| 373 | PowerShell snippet. |
| 374 | |
| 375 | Verify the compiler is reachable: `cl.exe /?` should print help text. |
| 376 | |
| 377 | ### Windows: `拒绝访问 (os error 5)` when Cargo executes build scripts |
| 378 | |
| 379 | Third-party antivirus software (Huorong, 360, Kaspersky, etc.) may block |
| 380 | Cargo from executing freshly-compiled build-script binaries |
| 381 | (e.g. `libsqlite3-sys`, `aws-lc-sys`, `instability`). The error is |
| 382 | path-agnostic — moving `target-dir` does not help. |
| 383 | |
| 384 | **Symptoms**: `could not execute process ... build-script-build (never executed)` |
| 385 | |
| 386 | **Workarounds** (pick one): |
| 387 | |
| 388 | 1. **Add the project's `target/` directory to your AV exclusions list.** |
| 389 | 2. **Close the antivirus software temporarily** during `cargo build`. |
| 390 | 3. **Use `npm install -g deepseek-tui` instead** — the npm package ships |
| 391 | prebuilt binaries and skips the Cargo build entirely |
| 392 | ([Section 2](#2-install-via-npm-recommended)). |
| 393 | 4. **Use `cargo install deepseek-tui-cli --locked`** from crates.io — this |
| 394 | changes the binary path, which some AV tools treat differently. |
| 395 | |
| 396 | To verify that the build-script binary itself is valid (not corrupted), locate |
| 397 | it under `target/debug/build/<crate>/build-script-build` and run it manually: |
| 398 | |
| 399 | ```bash |
| 400 | target/debug/build/libsqlite3-sys-*/build-script-build |
| 401 | # If this runs but panics with "NotPresent" (no C compiler), the binary is |
| 402 | # fine — the AV is blocking Cargo's process-spawning path specifically. |
| 403 | ``` |
| 404 | |
| 405 | --- |
| 406 | |
| 407 | ## 7. Verifying your install |
| 408 | |
| 409 | ```bash |
| 410 | deepseek --version |
| 411 | deepseek doctor # checks API key, provider, runtime, and PATH integrity |
| 412 | deepseek doctor --json |
| 413 | ``` |
| 414 | |
| 415 | `doctor` exits non-zero if it finds a problem and prints structured remediation |
| 416 | hints. Paste the JSON output into a GitHub issue if you need help. |
| 417 |