How to upgrade dsh: three routes, pinning and downgrading versions

Upgrading dsh means moving to a new version: check the current and latest versions first, then upgrade by install type — npx stays latest, npm update -g for globals, git pull plus rebuild for source — and pin or downgrade with @version when needed. This guide covers upgrade vs update, three upgrade routes, backup before upgrading, and version pinning and downgrading.

Overview: upgrading changes the version, never your data

An upgrade only swaps the program's version number; configs, sessions and plugins under ~/.dsh are all preserved. Three principles (source):

1. Check before upgrading: compare the current and latest versions;
2. Upgrade by install type: npx, npm and source each have their own command;
3. Versions are manageable: pin or downgrade whenever needed.

The upgrade paths at a glance:

Step 1: check the current and latest versions

Know your version landscape before acting, and avoid blind upgrades. Steps:

1. Open a terminal and check the current version:

# Current version (global install)
dsh --version

# Current version (npx route)
npx @deepseek-ai/dsh --version

2. Check the latest version on npm:

npm view @deepseek-ai/dsh version

3. Compare the numbers: if the current version is lower than the latest, an upgrade is due; for the differences between versions, check the changelog on dsh-plugin.org or the official release page.

Step 2: back up before upgrading (strongly recommended)

Back up the data directory before upgrading so you can always roll back if the new version misbehaves. Everything lives in ~/.dsh:

# Back up (configs, sessions, plugin list)
cp -r ~/.dsh ~/.dsh.backup-$(date +%Y%m%d)

# Also record the current version for comparison
dsh --version > ~/.dsh.version.old

Step 3: upgrade by install type

Upgrade commands map one-to-one to install types — pick the one you originally used. Three routes:

Route 1: npx (always latest)

npx re-pulls the latest version on every run, so no manual upgrade is needed. Just start:

npx @deepseek-ai/dsh web

Fallback: if the launched version is still old, the cache is stale — force a refresh:

npm cache clean --force
rm -rf ~/.npm/_npx
npx @deepseek-ai/dsh web

Route 2: npm global upgrade

If you installed globally, npm update -g upgrades to the latest in one step. Steps:

# Upgrade to the latest
npm update -g @deepseek-ai/dsh

# Confirm the version
dsh --version

If you used pnpm or yarn, use the equivalent: pnpm add -g @deepseek-ai/dsh@latest or yarn global add @deepseek-ai/dsh.

Route 3: source build upgrade

If you cloned and built from source, pull the latest code in the repo directory and rebuild. Steps:

# Enter the source repo directory
cd ~/dev/deepseek-harness

# Pull the latest code (git stash first if you have local changes)
git pull

# Reinstall dependencies and rebuild (same as the initial install)
npm install
# Run the build command from the repo docs, e.g. npm run build

Once the build finishes, restart dsh web to use the new version.

Step 4: pin or downgrade the version

When a new version feels off or a plugin is incompatible, pin or downgrade. Steps:

# Install a specific version globally (@ then the version)
npm install -g @deepseek-ai/[email protected]

# Confirm the version is back to the target
dsh --version

# Start a pinned version with npx (to verify the old version temporarily)
npx @deepseek-ai/[email protected] web

After pinning, npm update no longer bumps it automatically — a good fit for environments that need stability (source). To list all historical versions on npm, run npm view @deepseek-ai/dsh versions.

Step 5: verify after the upgrade

Confirm the version and functionality after upgrading, to avoid a "fake upgrade". Steps:

1. Re-run the version command and confirm the number changed;
2. Restart dsh web and confirm the page opens;
3. Open Settings → Plugin Center and confirm installed plugins load normally (with DSH Plugin Hub installed, you will see the plugin list and versions);
4. Check the notification center and system logs for any upgrade errors.

dsh-plugin-hub · notifications

Upgrade failed? Troubleshooting table

Read the error type first, then fix accordingly. Common issues:

One more thing: keep plugin versions in sync too

After upgrading the dsh core, watch plugin compatibility as well. The DSH Plugin Hub plugin pages show the compatible version each plugin is marked with; after upgrading, open Settings → Plugin Center and update any outdated plugins one by one to keep both in sync.

Quick reference

In one sentence: back up and check versions before upgrading, upgrade by install type (npx automatic / npm update -g / git pull + build), pin with @version when you need stability, then restart and verify. Four reminders:

1. Record the old version before upgrading so you can downgrade easily;
2. The npx route needs no manual upgrade — just clean the cache;
3. Pin versions with @version: npm install -g @deepseek-ai/dsh@<version>;
4. Restart before troubleshooting plugins after an upgrade, then consider reinstalling.

Sources: dsh CLI README, DeepSeek Harness docs - Quickstart, dshplugin/dsh-plugin-hub