Uninstall

mx uninstall <packageName> removes an installed package's directory from the package store. It is a thin operation: it does not stop runtimes, does not run any cleanup hooks, and does not preserve a backup. Stop runtimes before uninstalling.

Synopsis

mx uninstall <packageName> [--packages-dir <path>] [--json]

Source: packages/mx-cli/src/commands/uninstall.ts.

export async function uninstallCommand(packageName, options): Promise<IUninstallCommandResult> {
  const cwd = path.resolve(options.cwd ?? process.cwd());
  const nodeModulesRoot = resolvePackagesNodeModulesRoot(cwd, options.packagesDir);
  const removedPath = path.join(nodeModulesRoot, packageNameToPath(packageName));

  if (!fs.existsSync(removedPath)) {
    throw new Error(`Package is not installed: ${packageName}`);
  }

  fs.rmSync(removedPath, { recursive: true, force: true });
  return { packageName, removedPath };
}

The implementation is intentionally minimal: it deletes the package directory and reports the path it removed.

Stop runtimes first

If a runtime is running the package you're about to uninstall, take it down first:

hivecast runtimes --home /tmp/matrix-home
# Find any runtime whose packageRef matches the package you want to remove

hivecast down <runtimeId> --home /tmp/matrix-home
mx uninstall @open-matrix/chat --packages-dir /tmp/matrix-home/packages/global

If you uninstall while a runtime is still loaded, the runtime process keeps running until it exits or restarts. On the next restart it will fail to import runtime.entry and the supervisor will mark it failed. Your system.runtimes view will be out of sync until that happens.

What uninstall does not do

Concern	Status
Stop running runtimes	No — use hivecast down first
Run an uninstall.* lifecycle hook	No — there is no such hook in the validator
Remove logs or runtime records	No — <host-home>/runtimes/*.json and <host-home>/logs/runtimes/*.log survive
Remove published artifacts from any registry	No — uninstall is local-store only
Uninstall transitive dependencies	No — only the named package's directory is removed

The lack of an uninstall lifecycle hook is intentional today; if a package needs to clean up state (database tables, files outside <MATRIX_HOME>/packages/), that state belongs in <MATRIX_HOME>/ under a clearly-named directory and the operator removes it explicitly.

Force / non-existent target

If the package isn't installed, mx uninstall throws Package is not installed: <name>. There is no --force flag because uninstall has no preservation behavior to override.

To remove a package whose directory is partially corrupt, delete the directory directly:

rm -rf /tmp/matrix-home/packages/global/node_modules/@open-matrix/chat

This is the one acceptable hand-edit of the package store, because the package is already broken; nothing the install path could do would change the outcome.

Reinstalling

Reinstalling is the same as installing:

mx install @open-matrix/chat --packages-dir /tmp/matrix-home/packages/global

If the previous uninstall was clean (the directory is gone), no flags are needed. If you skipped uninstall and want to overwrite in place, pass --force.

See also

• Installing → Install from registry
• Installing → Install from local folder
• Installing → Package store
• Running → hivecast down

Source: projects/matrix-3/packages/mx-cli/src/commands/uninstall.ts is the entire implementation; the parent mx-cli/src/index.ts wires up the mx uninstall command.