# How to Uninstall mise Tools: Complete Command Reference

> Uninstall specific tool versions with `mise uninstall`. Keep your mise.toml config and refresh shims automatically. Get the complete command reference now.

- Repository: [jdx/mise](https://github.com/jdx/mise)
- Tags: how-to-guide
- Published: 2026-08-09

---

**Use `mise uninstall` to selectively remove installed tool versions while preserving your [`mise.toml`](https://github.com/jdx/mise/blob/main/mise.toml) configuration and automatically refreshing shims.**

The `mise uninstall` command in the [jdx/mise](https://github.com/jdx/mise) repository provides a structured way to delete tool binaries and clean up runtime environments. Unlike manual file deletion, this command ensures consistency across backends, updates shell shims, and supports dry-run validation for automation workflows.

## Three Modes for Uninstalling Tools

The implementation in [`src/cli/uninstall.rs`](https://github.com/jdx/mise/blob/main/src/cli/uninstall.rs) supports three distinct operational modes depending on your cleanup requirements.

### Single Version Removal

Specify a tool and optional version to remove a specific installation. If you omit the version and only one version exists, mise automatically selects that version.

This mode parses the tool argument through `ToolArg` (lines 20–34), resolves the appropriate backend, and matches installed versions using `get_requested_tool_versions`.

```bash

# Remove specific Node.js version

mise uninstall node@18.0.0

# Remove the only installed Python version (no version argument needed)

mise uninstall python

```

### Remove All Versions

Use the `--all` flag to delete every installed version of a specific tool, or omit the tool name to purge all managed tools entirely.

This triggers `get_all_tool_versions` (lines 104–115), which gathers every installed version from the toolset via [`src/toolset/toolset_builder.rs`](https://github.com/jdx/mise/blob/main/src/toolset/toolset_builder.rs).

```bash

# Delete all Go versions

mise uninstall --all go

# Delete every tool managed by mise

mise uninstall --all

```

### Dry-Run Mode

Simulate uninstallation without making changes using `--dry-run` (or `-n`). For CI pipelines, `--dry-run-code` exits with status 1 if any removals would occur.

The `is_dry_run` check combines both flags (lines 40–42). During execution, the loop reports "uninstalled (dry-run)" instead of calling the actual delete operation (lines 76–80).

```bash

# Simulate removing all Ruby versions

mise uninstall --all ruby --dry-run

# CI check: exit 1 if Rust versions need uninstalling

mise uninstall --all rust --dry-run-code

```

## The mise uninstall Workflow

According to the source code in [`src/cli/uninstall.rs`](https://github.com/jdx/mise/blob/main/src/cli/uninstall.rs), the uninstallation process follows a five-step pipeline:

1. **Collect target versions** — The command invokes either `get_all_tool_versions` (for `--all`) or `get_requested_tool_versions` (for specific requests) to build the removal list.

2. **Deduplicate entries** — The `unique_by` function ensures each version processes only once (line 53), preventing redundant backend calls.

3. **Validate requests** — If you omit `--all` but specify multiple tools, the command aborts with an error (lines 55–57), forcing explicit `--all` for batch operations.

4. **Perform removal** — For each `(backend, ToolVersion)` pair, the system calls `backend.uninstall_version` defined in [`src/backend/mod.rs`](https://github.com/jdx/mise/blob/main/src/backend/mod.rs) (lines 70–72).

5. **Refresh shims** — After successful removal (non-dry-run), mise rebuilds shims and runtime symlinks to reflect the new state (lines 90–99), ensuring your shell environment stays synchronized.

## Practical Command Examples

```bash

# Uninstall a specific version

mise uninstall node@18.0.0

# Uninstall the default/only version

mise uninstall python

# Remove all versions of a tool

mise uninstall --all go

# Preview changes without applying

mise uninstall --all ruby --dry-run

# CI-friendly exit codes

mise uninstall --all rust --dry-run-code

```

## Key Implementation Files

The uninstall functionality spans several core modules:

- **[`src/cli/uninstall.rs`](https://github.com/jdx/mise/blob/main/src/cli/uninstall.rs)** — Implements command parsing, version resolution, validation logic, and the shim refresh orchestration.
- **[`src/backend/mod.rs`](https://github.com/jdx/mise/blob/main/src/backend/mod.rs)** — Defines the `Backend` trait; each tool backend provides the `uninstall_version` method called during removal.
- **[`src/toolset/toolset_builder.rs`](https://github.com/jdx/mise/blob/main/src/toolset/toolset_builder.rs)** — Builds the `Toolset` structure used by `get_all_tool_versions` to enumerate installed versions.
- **[`src/ui/multi_progress_report.rs`](https://github.com/jdx/mise/blob/main/src/ui/multi_progress_report.rs)** — Handles progress reporting during batch uninstall operations.
- **[`src/config/config.rs`](https://github.com/jdx/mise/blob/main/src/config/config.rs)** — Manages global configuration loading and reset operations post-uninstall.
- **[`src/cli/prune.rs`](https://github.com/jdx/mise/blob/main/src/cli/prune.rs)** — Contains similar uninstall logic for removing unused tool versions automatically.

## Summary

- **`mise uninstall`** removes binaries without modifying [`mise.toml`](https://github.com/jdx/mise/blob/main/mise.toml) configuration files.
- **Three modes** handle specific versions, all versions of a tool, or system-wide cleanup.
- **Dry-run options** (`--dry-run`, `--dry-run-code`) enable safe testing and CI integration.
- **Automatic shim refresh** ensures shell environments update immediately after removal.
- **Backend abstraction** in [`src/backend/mod.rs`](https://github.com/jdx/mise/blob/main/src/backend/mod.rs) ensures consistent cleanup across different tool types.

## Frequently Asked Questions

### Will `mise uninstall` remove entries from my [`mise.toml`](https://github.com/jdx/mise/blob/main/mise.toml)?

No. The command only deletes installed tool binaries and runtime files from your system. It does not modify configuration files, `.tool-versions`, or [`mise.toml`](https://github.com/jdx/mise/blob/main/mise.toml) entries. You must manually remove version specifications from configuration files if you no longer want mise to install those tools.

### What happens if I don't specify a version when uninstalling?

If you omit the version argument and exactly one version is currently installed, mise automatically selects that version for removal. If multiple versions exist, the command requires you to specify which version or use `--all` to remove every installed version of that tool.

### How does `--dry-run-code` differ from `--dry-run`?

Both options simulate the uninstallation without deleting files. However, `--dry-run-code` exits with status code 1 if any tools would have been removed, while `--dry-run` exits with status 0. This makes `--dry-run-code` useful for CI scripts that need to detect whether cleanup actions are pending.

### Where does mise perform the actual file deletion?

The actual removal happens in the `uninstall_version` method of the specific backend implementation (defined in [`src/backend/mod.rs`](https://github.com/jdx/mise/blob/main/src/backend/mod.rs)). Each backend (e.g., npm, cargo, asdf plugins) implements its own cleanup logic, ensuring proper removal of binaries, shims, and cached data specific to that tool type.